compact-agent 1.10.0 → 1.11.0

package/resources/ecc/rules/perl/testing.md

@@ -0,0 +1,54 @@
+---
+paths:
+  - "**/*.pl"
+  - "**/*.pm"
+  - "**/*.t"
+  - "**/*.psgi"
+  - "**/*.cgi"
+---
+# Perl Testing
+
+> This file extends [common/testing.md](../common/testing.md) with Perl-specific content.
+
+## Framework
+
+Use **Test2::V0** for new projects (not Test::More):
+
+```perl
+use Test2::V0;
+
+is($result, 42, 'answer is correct');
+
+done_testing;
+```
+
+## Runner
+
+```bash
+prove -l t/              # adds lib/ to @INC
+prove -lr -j8 t/         # recursive, 8 parallel jobs
+```
+
+Always use `-l` to ensure `lib/` is on `@INC`.
+
+## Coverage
+
+Use **Devel::Cover** — target 80%+:
+
+```bash
+cover -test
+```
+
+## Mocking
+
+- **Test::MockModule** — mock methods on existing modules
+- **Test::MockObject** — create test doubles from scratch
+
+## Pitfalls
+
+- Always end test files with `done_testing`
+- Never forget the `-l` flag with `prove`
+
+## Reference
+
+See skill: `perl-testing` for detailed Perl TDD patterns with Test2::V0, prove, and Devel::Cover.

package/resources/ecc/rules/php/coding-style.md

@@ -0,0 +1,40 @@
+---
+paths:
+  - "**/*.php"
+  - "**/composer.json"
+---
+# PHP Coding Style
+
+> This file extends [common/coding-style.md](../common/coding-style.md) with PHP specific content.
+
+## Standards
+
+- Follow **PSR-12** formatting and naming conventions.
+- Prefer `declare(strict_types=1);` in application code.
+- Use scalar type hints, return types, and typed properties everywhere new code permits.
+
+## Immutability
+
+- Prefer immutable DTOs and value objects for data crossing service boundaries.
+- Use `readonly` properties or immutable constructors for request/response payloads where possible.
+- Keep arrays for simple maps; promote business-critical structures into explicit classes.
+
+## Formatting
+
+- Use **PHP-CS-Fixer** or **Laravel Pint** for formatting.
+- Use **PHPStan** or **Psalm** for static analysis.
+- Keep Composer scripts checked in so the same commands run locally and in CI.
+
+## Imports
+
+- Add `use` statements for all referenced classes, interfaces, and traits.
+- Avoid relying on the global namespace unless the project explicitly prefers fully qualified names.
+
+## Error Handling
+
+- Throw exceptions for exceptional states; avoid returning `false`/`null` as hidden error channels in new code.
+- Convert framework/request input into validated DTOs before it reaches domain logic.
+
+## Reference
+
+See skill: `backend-patterns` for broader service/repository layering guidance.

package/resources/ecc/rules/{php-hooks.md → php/hooks.md}

@@ -1,11 +1,14 @@
 ---
-description: "PHP hooks extending common rules"
-globs: ["**/*.php", "**/composer.json", "**/phpstan.neon", "**/phpstan.neon.dist", "**/psalm.xml"]
-alwaysApply: false
+paths:
+  - "**/*.php"
+  - "**/composer.json"
+  - "**/phpstan.neon"
+  - "**/phpstan.neon.dist"
+  - "**/psalm.xml"
 ---
 # PHP Hooks
 
-> This file extends the common hooks rule with PHP specific content.
+> This file extends [common/hooks.md](../common/hooks.md) with PHP specific content.
 
 ## PostToolUse Hooks
 

package/resources/ecc/rules/php/patterns.md

@@ -0,0 +1,33 @@
+---
+paths:
+  - "**/*.php"
+  - "**/composer.json"
+---
+# PHP Patterns
+
+> This file extends [common/patterns.md](../common/patterns.md) with PHP specific content.
+
+## Thin Controllers, Explicit Services
+
+- Keep controllers focused on transport: auth, validation, serialization, status codes.
+- Move business rules into application/domain services that are easy to test without HTTP bootstrapping.
+
+## DTOs and Value Objects
+
+- Replace shape-heavy associative arrays with DTOs for requests, commands, and external API payloads.
+- Use value objects for money, identifiers, date ranges, and other constrained concepts.
+
+## Dependency Injection
+
+- Depend on interfaces or narrow service contracts, not framework globals.
+- Pass collaborators through constructors so services are testable without service-locator lookups.
+
+## Boundaries
+
+- Isolate ORM models from domain decisions when the model layer is doing more than persistence.
+- Wrap third-party SDKs behind small adapters so the rest of the codebase depends on your contract, not theirs.
+
+## Reference
+
+See skill: `api-design` for endpoint conventions and response-shape guidance.
+See skill: `laravel-patterns` for Laravel-specific architecture guidance.

package/resources/ecc/rules/php/security.md

@@ -0,0 +1,37 @@
+---
+paths:
+  - "**/*.php"
+  - "**/composer.lock"
+  - "**/composer.json"
+---
+# PHP Security
+
+> This file extends [common/security.md](../common/security.md) with PHP specific content.
+
+## Input and Output
+
+- Validate request input at the framework boundary (`FormRequest`, Symfony Validator, or explicit DTO validation).
+- Escape output in templates by default; treat raw HTML rendering as an exception that must be justified.
+- Never trust query params, cookies, headers, or uploaded file metadata without validation.
+
+## Database Safety
+
+- Use prepared statements (`PDO`, Doctrine, Eloquent query builder) for all dynamic queries.
+- Avoid string-building SQL in controllers/views.
+- Scope ORM mass-assignment carefully and whitelist writable fields.
+
+## Secrets and Dependencies
+
+- Load secrets from environment variables or a secret manager, never from committed config files.
+- Run `composer audit` in CI and review new package maintainer trust before adding dependencies.
+- Pin major versions deliberately and remove abandoned packages quickly.
+
+## Auth and Session Safety
+
+- Use `password_hash()` / `password_verify()` for password storage.
+- Regenerate session identifiers after authentication and privilege changes.
+- Enforce CSRF protection on state-changing web requests.
+
+## Reference
+
+See skill: `laravel-security` for Laravel-specific security guidance.

package/resources/ecc/rules/php/testing.md

@@ -0,0 +1,39 @@
+---
+paths:
+  - "**/*.php"
+  - "**/phpunit.xml"
+  - "**/phpunit.xml.dist"
+  - "**/composer.json"
+---
+# PHP Testing
+
+> This file extends [common/testing.md](../common/testing.md) with PHP specific content.
+
+## Framework
+
+Use **PHPUnit** as the default test framework. If **Pest** is configured in the project, prefer Pest for new tests and avoid mixing frameworks.
+
+## Coverage
+
+```bash
+vendor/bin/phpunit --coverage-text
+# or
+vendor/bin/pest --coverage
+```
+
+Prefer **pcov** or **Xdebug** in CI, and keep coverage thresholds in CI rather than as tribal knowledge.
+
+## Test Organization
+
+- Separate fast unit tests from framework/database integration tests.
+- Use factory/builders for fixtures instead of large hand-written arrays.
+- Keep HTTP/controller tests focused on transport and validation; move business rules into service-level tests.
+
+## Inertia
+
+If the project uses Inertia.js, prefer `assertInertia` with `AssertableInertia` to verify component names and props instead of raw JSON assertions.
+
+## Reference
+
+See skill: `tdd-workflow` for the repo-wide RED -> GREEN -> REFACTOR loop.
+See skill: `laravel-tdd` for Laravel-specific testing patterns (PHPUnit and Pest).

package/resources/ecc/rules/{python-coding-style.md → python/coding-style.md}

@@ -1,11 +1,11 @@
 ---
-description: "Python coding style extending common rules"
-globs: ["**/*.py", "**/*.pyi"]
-alwaysApply: false
+paths:
+  - "**/*.py"
+  - "**/*.pyi"
 ---
 # Python Coding Style
 
-> This file extends the common coding style rule with Python specific content.
+> This file extends [common/coding-style.md](../common/coding-style.md) with Python specific content.
 
 ## Standards
 

package/resources/ecc/rules/python/fastapi.md

@@ -0,0 +1,58 @@
+---
+paths:
+  - "**/app/**/*.py"
+  - "**/fastapi/**/*.py"
+  - "**/*_api.py"
+---
+# FastAPI Rules
+
+Use these rules for FastAPI projects alongside the general Python rules.
+
+## Structure
+
+- Put app construction in `create_app()`.
+- Keep routers thin; move persistence and business behavior into services or CRUD helpers.
+- Keep request schemas, update schemas, and response schemas separate.
+- Keep database sessions and auth in dependencies.
+
+## Async
+
+- Use `async def` for endpoints that perform I/O.
+- Use async database and HTTP clients from async endpoints.
+- Do not call `requests`, sync SQLAlchemy sessions, or blocking file/network operations from async routes.
+
+## Dependency Injection
+
+```python
+@router.get("/users/{user_id}")
+async def get_user(
+    user_id: str,
+    db: AsyncSession = Depends(get_db),
+    current_user: User = Depends(get_current_user),
+):
+    ...
+```
+
+Do not create `SessionLocal()` or long-lived clients inside route handlers.
+
+## Schemas
+
+- Never include passwords, password hashes, access tokens, refresh tokens, or internal auth state in response models.
+- Use `response_model` on endpoints that return application data.
+- Use field constraints instead of hand-written validation when Pydantic can express the rule.
+
+## Security
+
+- Keep CORS origins environment-specific.
+- Do not combine wildcard origins with credentialed CORS.
+- Validate JWT expiry, issuer, audience, and algorithm.
+- Rate-limit auth and write-heavy endpoints.
+- Redact credentials, cookies, authorization headers, and tokens from logs.
+
+## Testing
+
+- Override the exact dependency used by `Depends`.
+- Clear `app.dependency_overrides` after tests.
+- Prefer async test clients for async applications.
+
+See skill: `fastapi-patterns`.

package/resources/ecc/rules/{python-hooks.md → python/hooks.md}

@@ -1,11 +1,11 @@
 ---
-description: "Python hooks extending common rules"
-globs: ["**/*.py", "**/*.pyi"]
-alwaysApply: false
+paths:
+  - "**/*.py"
+  - "**/*.pyi"
 ---
 # Python Hooks
 
-> This file extends the common hooks rule with Python specific content.
+> This file extends [common/hooks.md](../common/hooks.md) with Python specific content.
 
 ## PostToolUse Hooks
 

package/resources/ecc/rules/{python-patterns.md → python/patterns.md}

@@ -1,11 +1,11 @@
 ---
-description: "Python patterns extending common rules"
-globs: ["**/*.py", "**/*.pyi"]
-alwaysApply: false
+paths:
+  - "**/*.py"
+  - "**/*.pyi"
 ---
 # Python Patterns
 
-> This file extends the common patterns rule with Python specific content.
+> This file extends [common/patterns.md](../common/patterns.md) with Python specific content.
 
 ## Protocol (Duck Typing)
 

package/resources/ecc/rules/{python-security.md → python/security.md}

@@ -1,11 +1,11 @@
 ---
-description: "Python security extending common rules"
-globs: ["**/*.py", "**/*.pyi"]
-alwaysApply: false
+paths:
+  - "**/*.py"
+  - "**/*.pyi"
 ---
 # Python Security
 
-> This file extends the common security rule with Python specific content.
+> This file extends [common/security.md](../common/security.md) with Python specific content.
 
 ## Secret Management
 

package/resources/ecc/rules/{python-testing.md → python/testing.md}

@@ -1,11 +1,11 @@
 ---
-description: "Python testing extending common rules"
-globs: ["**/*.py", "**/*.pyi"]
-alwaysApply: false
+paths:
+  - "**/*.py"
+  - "**/*.pyi"
 ---
 # Python Testing
 
-> This file extends the common testing rule with Python specific content.
+> This file extends [common/testing.md](../common/testing.md) with Python specific content.
 
 ## Framework
 

package/resources/ecc/rules/ruby/coding-style.md

@@ -0,0 +1,46 @@
+---
+paths:
+  - "**/*.rb"
+  - "**/*.rake"
+  - "**/Gemfile"
+  - "**/*.gemspec"
+  - "**/config.ru"
+---
+# Ruby Coding Style
+
+> This file extends [common/coding-style.md](../common/coding-style.md) with Ruby and Rails specific content.
+
+## Standards
+
+- Target **Ruby 3.3+** for new Rails work unless the project already pins an older supported runtime.
+- Enable **YJIT** in production only after measuring boot time, memory, and request/job throughput.
+- Add `# frozen_string_literal: true` to new Ruby files when the project uses that convention.
+- Prefer clear Ruby over clever metaprogramming; isolate DSL-heavy code behind narrow, tested boundaries.
+
+## Formatting And Linting
+
+- Use the project's checked-in RuboCop config. For Rails 8+ apps, start from `rubocop-rails-omakase` and customize only where the codebase has a real convention.
+- Keep formatter/linter commands behind binstubs or scripts so CI and local runs match:
+
+```bash
+bundle exec rubocop
+bundle exec rubocop -A
+```
+
+- Do not silence cops inline unless the exception is narrow, documented, and harder to express cleanly in code.
+
+## Rails Style
+
+- Follow Rails naming and directory conventions before adding custom structure.
+- Keep controllers transport-focused: authentication, authorization, parameter handling, response shape.
+- Put reusable domain behavior in models, concerns, service objects, query objects, or form objects based on actual complexity, not as default ceremony.
+- Prefer `bin/rails`, `bin/rake`, and checked-in binstubs over globally installed commands.
+
+## Error Handling
+
+- Rescue specific exceptions. Avoid broad `rescue StandardError` blocks unless they re-raise or preserve enough context for operators.
+- Use `ActiveSupport::Notifications` or the app's logger for operational events; do not leave `puts`, `pp`, or `debugger` in committed application code.
+
+## Reference
+
+See skill: `backend-patterns` for broader service/repository layering guidance.

package/resources/ecc/rules/ruby/hooks.md

@@ -0,0 +1,37 @@
+---
+paths:
+  - "**/*.rb"
+  - "**/*.rake"
+  - "**/Gemfile"
+  - "**/Gemfile.lock"
+  - "**/config/routes.rb"
+---
+# Ruby Hooks
+
+> This file extends [common/hooks.md](../common/hooks.md) with Ruby and Rails specific content.
+
+## PostToolUse Hooks
+
+Configure project-local hooks to prefer binstubs and checked-in tooling:
+
+- **RuboCop**: run `bundle exec rubocop -A <file>` or the project's safer formatter command after Ruby edits.
+- **Brakeman**: run `bundle exec brakeman --no-pager` after security-sensitive Rails changes.
+- **Tests**: run the narrowest matching `bin/rails test ...` or `bundle exec rspec ...` command for touched files.
+- **Bundler audit**: run `bundle exec bundle-audit check --update` when `Gemfile` or `Gemfile.lock` changes and the project has bundler-audit installed.
+
+## Warnings
+
+- Warn on committed `debugger`, `binding.irb`, `binding.pry`, `puts`, `pp`, or `p` calls in application code.
+- Warn when an edit disables CSRF protection, expands mass-assignment, or adds raw SQL without parameterization.
+- Warn when a migration changes data destructively without a reversible path or documented rollout plan.
+
+## CI Gate Suggestions
+
+```bash
+bundle exec rubocop
+bundle exec brakeman --no-pager
+bin/rails test
+bundle exec rspec
+```
+
+Use only the commands that are present in the project; do not install new hook dependencies without maintainer approval.

package/resources/ecc/rules/ruby/patterns.md

@@ -0,0 +1,44 @@
+---
+paths:
+  - "**/*.rb"
+  - "**/*.rake"
+  - "**/Gemfile"
+  - "**/app/**/*.erb"
+  - "**/config/routes.rb"
+---
+# Ruby Patterns
+
+> This file extends [common/patterns.md](../common/patterns.md) with Ruby and Rails specific content.
+
+## Rails Way First
+
+- Start with plain Rails MVC and Active Record conventions for small and medium features.
+- Introduce service objects, query objects, form objects, decorators, or presenters when the model/controller boundary is carrying multiple responsibilities.
+- Name extracted objects after the business operation they perform, not after generic layers like `Manager` or `Processor`.
+
+## Persistence
+
+- Prefer PostgreSQL for multi-host production Rails apps unless the existing platform has a clear reason for MySQL or SQLite.
+- Treat Rails 8 SQLite-backed defaults as viable for single-host or modest deployments, not as an automatic fit for shared multi-service systems.
+- Keep raw SQL behind query objects or model scopes and parameterize every dynamic value.
+
+## Background Jobs And Runtime Services
+
+- Use **Solid Queue** for greenfield Rails 8 apps with modest throughput and simple deployment needs.
+- Use **Sidekiq** when the app needs mature observability, high throughput, existing Redis infrastructure, or Pro/Enterprise features.
+- Use **Solid Cache** and **Solid Cable** when their deployment model matches the app; use Redis when shared cross-service behavior, high fanout, or advanced data structures matter.
+
+## Frontend
+
+- Prefer **Hotwire** with Turbo, Stimulus, Importmap, and Propshaft for server-rendered Rails apps.
+- Use React, Vue, Inertia.js, or a separate SPA when interaction complexity, existing product architecture, or team ownership justifies the extra client surface.
+- Keep view components, partials, and presenters focused on rendering decisions; keep persistence and authorization out of templates.
+
+## Authentication
+
+- Use the Rails 8 authentication generator for straightforward session auth and password reset needs.
+- Use Devise or another established auth system when requirements include OAuth, MFA, confirmable/lockable flows, multi-model auth, or a large existing Devise footprint.
+
+## Reference
+
+See skill: `backend-patterns` for service boundaries and adapter patterns.

package/resources/ecc/rules/ruby/security.md

@@ -0,0 +1,51 @@
+---
+paths:
+  - "**/*.rb"
+  - "**/*.rake"
+  - "**/Gemfile"
+  - "**/Gemfile.lock"
+  - "**/config/routes.rb"
+  - "**/config/credentials*.yml.enc"
+---
+# Ruby Security
+
+> This file extends [common/security.md](../common/security.md) with Ruby and Rails specific content.
+
+## Rails Defaults
+
+- Keep CSRF protection enabled for state-changing browser requests.
+- Use strong parameters or typed boundary objects before mass assignment.
+- Store secrets in Rails credentials, environment variables, or a secret manager. Never commit plaintext keys, tokens, private credentials, or copied `.env` values.
+
+## SQL And Active Record
+
+- Prefer Active Record query APIs and parameterized SQL.
+- Never interpolate request, cookie, header, job, or webhook values into SQL strings.
+- Scope model callbacks carefully; security-sensitive side effects should be explicit and covered by tests.
+
+## Authentication And Sessions
+
+- Use the Rails 8 authentication generator for simple session auth, or Devise when OAuth, MFA, confirmable, lockable, multi-model auth, or existing Devise conventions are required.
+- Rotate sessions after sign-in and privilege changes.
+- Protect account recovery flows with expiry, single-use tokens, rate limiting, and audit logging.
+
+## Dependencies
+
+- Run dependency checks when the lockfile changes:
+
+```bash
+bundle audit check --update
+bundle exec brakeman --no-pager
+```
+
+- Review new gems for maintainer activity, native extension risk, transitive dependencies, and whether the same behavior can be implemented with Rails core.
+
+## Web Safety
+
+- Escape template output by default. Treat `html_safe`, `raw`, and custom sanitizers as security-sensitive code.
+- Validate file uploads by content type, extension, size, and storage destination.
+- Treat background jobs, webhooks, Action Cable messages, and Turbo Stream inputs as untrusted boundaries.
+
+## Reference
+
+See skill: `security-review` for secure-by-default review patterns.

package/resources/ecc/rules/ruby/testing.md

@@ -0,0 +1,51 @@
+---
+paths:
+  - "**/*.rb"
+  - "**/*.rake"
+  - "**/Gemfile"
+  - "**/test/**/*.rb"
+  - "**/spec/**/*.rb"
+  - "**/config/routes.rb"
+---
+# Ruby Testing
+
+> This file extends [common/testing.md](../common/testing.md) with Ruby and Rails specific content.
+
+## Framework
+
+- Use **Minitest** when the Rails app follows the default Rails test stack.
+- Use **RSpec** when it is already established in the project or the team has explicit production conventions around it.
+- Do not mix Minitest and RSpec inside the same feature area without a migration reason.
+
+## Test Pyramid
+
+- Put fast domain behavior in model, service, query, policy, and job tests.
+- Use request/controller tests for HTTP contracts, auth behavior, redirects, status codes, and response shapes.
+- Use system tests with Capybara for browser-critical flows only; keep them focused and stable.
+- Cover background jobs with unit tests for behavior and integration tests for queue/enqueue contracts.
+
+## Fixtures And Factories
+
+- Use Rails fixtures when they are the project default and the data graph is small.
+- Use `factory_bot` when scenarios need explicit object construction or complex traits.
+- Keep test data close to the behavior being asserted; avoid global fixtures that hide setup cost.
+
+## Commands
+
+Prefer project-local commands:
+
+```bash
+bin/rails test
+bin/rails test test/models/user_test.rb
+bundle exec rspec
+bundle exec rspec spec/models/user_spec.rb
+```
+
+## Coverage
+
+- Use SimpleCov when coverage is enforced; keep thresholds in CI and avoid gaming branch coverage with low-value tests.
+- Add regression tests for bug fixes before changing production code.
+
+## Reference
+
+See skill: `tdd-workflow` for the repo-wide RED -> GREEN -> REFACTOR loop.