@heyai-rules/pilo-masterkit 1.2.2 → 3.1.0

package/.agent/skills/perl-testing/SKILL.md

@@ -0,0 +1,475 @@
+---
+name: perl-testing
+description: Perl testing patterns using Test2::V0, Test::More, prove runner, mocking, coverage with Devel::Cover, and TDD methodology.
+origin: ECC
+---
+
+# Perl Testing Patterns
+
+Comprehensive testing strategies for Perl applications using Test2::V0, Test::More, prove, and TDD methodology.
+
+## When to Activate
+
+- Writing new Perl code (follow TDD: red, green, refactor)
+- Designing test suites for Perl modules or applications
+- Reviewing Perl test coverage
+- Setting up Perl testing infrastructure
+- Migrating tests from Test::More to Test2::V0
+- Debugging failing Perl tests
+
+## TDD Workflow
+
+Always follow the RED-GREEN-REFACTOR cycle.
+
+```perl
+# Step 1: RED — Write a failing test
+# t/unit/calculator.t
+use v5.36;
+use Test2::V0;
+
+use lib 'lib';
+use Calculator;
+
+subtest 'addition' => sub {
+    my $calc = Calculator->new;
+    is($calc->add(2, 3), 5, 'adds two numbers');
+    is($calc->add(-1, 1), 0, 'handles negatives');
+};
+
+done_testing;
+
+# Step 2: GREEN — Write minimal implementation
+# lib/Calculator.pm
+package Calculator;
+use v5.36;
+use Moo;
+
+sub add($self, $a, $b) {
+    return $a + $b;
+}
+
+1;
+
+# Step 3: REFACTOR — Improve while tests stay green
+# Run: prove -lv t/unit/calculator.t
+```
+
+## Test::More Fundamentals
+
+The standard Perl testing module — widely used, ships with core.
+
+### Basic Assertions
+
+```perl
+use v5.36;
+use Test::More;
+
+# Plan upfront or use done_testing
+# plan tests => 5;  # Fixed plan (optional)
+
+# Equality
+is($result, 42, 'returns correct value');
+isnt($result, 0, 'not zero');
+
+# Boolean
+ok($user->is_active, 'user is active');
+ok(!$user->is_banned, 'user is not banned');
+
+# Deep comparison
+is_deeply(
+    $got,
+    { name => 'Alice', roles => ['admin'] },
+    'returns expected structure'
+);
+
+# Pattern matching
+like($error, qr/not found/i, 'error mentions not found');
+unlike($output, qr/password/, 'output hides password');
+
+# Type check
+isa_ok($obj, 'MyApp::User');
+can_ok($obj, 'save', 'delete');
+
+done_testing;
+```
+
+### SKIP and TODO
+
+```perl
+use v5.36;
+use Test::More;
+
+# Skip tests conditionally
+SKIP: {
+    skip 'No database configured', 2 unless $ENV{TEST_DB};
+
+    my $db = connect_db();
+    ok($db->ping, 'database is reachable');
+    is($db->version, '15', 'correct PostgreSQL version');
+}
+
+# Mark expected failures
+TODO: {
+    local $TODO = 'Caching not yet implemented';
+    is($cache->get('key'), 'value', 'cache returns value');
+}
+
+done_testing;
+```
+
+## Test2::V0 Modern Framework
+
+Test2::V0 is the modern replacement for Test::More — richer assertions, better diagnostics, and extensible.
+
+### Why Test2?
+
+- Superior deep comparison with hash/array builders
+- Better diagnostic output on failures
+- Subtests with cleaner scoping
+- Extensible via Test2::Tools::* plugins
+- Backward-compatible with Test::More tests
+
+### Deep Comparison with Builders
+
+```perl
+use v5.36;
+use Test2::V0;
+
+# Hash builder — check partial structure
+is(
+    $user->to_hash,
+    hash {
+        field name  => 'Alice';
+        field email => match(qr/\@example\.com$/);
+        field age   => validator(sub { $_ >= 18 });
+        # Ignore other fields
+        etc();
+    },
+    'user has expected fields'
+);
+
+# Array builder
+is(
+    $result,
+    array {
+        item 'first';
+        item match(qr/^second/);
+        item DNE();  # Does Not Exist — verify no extra items
+    },
+    'result matches expected list'
+);
+
+# Bag — order-independent comparison
+is(
+    $tags,
+    bag {
+        item 'perl';
+        item 'testing';
+        item 'tdd';
+    },
+    'has all required tags regardless of order'
+);
+```
+
+### Subtests
+
+```perl
+use v5.36;
+use Test2::V0;
+
+subtest 'User creation' => sub {
+    my $user = User->new(name => 'Alice', email => 'alice@example.com');
+    ok($user, 'user object created');
+    is($user->name, 'Alice', 'name is set');
+    is($user->email, 'alice@example.com', 'email is set');
+};
+
+subtest 'User validation' => sub {
+    my $warnings = warns {
+        User->new(name => '', email => 'bad');
+    };
+    ok($warnings, 'warns on invalid data');
+};
+
+done_testing;
+```
+
+### Exception Testing with Test2
+
+```perl
+use v5.36;
+use Test2::V0;
+
+# Test that code dies
+like(
+    dies { divide(10, 0) },
+    qr/Division by zero/,
+    'dies on division by zero'
+);
+
+# Test that code lives
+ok(lives { divide(10, 2) }, 'division succeeds') or note($@);
+
+# Combined pattern
+subtest 'error handling' => sub {
+    ok(lives { parse_config('valid.json') }, 'valid config parses');
+    like(
+        dies { parse_config('missing.json') },
+        qr/Cannot open/,
+        'missing file dies with message'
+    );
+};
+
+done_testing;
+```
+
+## Test Organization and prove
+
+### Directory Structure
+
+```text
+t/
+├── 00-load.t              # Verify modules compile
+├── 01-basic.t             # Core functionality
+├── unit/
+│   ├── config.t           # Unit tests by module
+│   ├── user.t
+│   └── util.t
+├── integration/
+│   ├── database.t
+│   └── api.t
+├── lib/
+│   └── TestHelper.pm      # Shared test utilities
+└── fixtures/
+    ├── config.json        # Test data files
+    └── users.csv
+```
+
+### prove Commands
+
+```bash
+# Run all tests
+prove -l t/
+
+# Verbose output
+prove -lv t/
+
+# Run specific test
+prove -lv t/unit/user.t
+
+# Recursive search
+prove -lr t/
+
+# Parallel execution (8 jobs)
+prove -lr -j8 t/
+
+# Run only failing tests from last run
+prove -l --state=failed t/
+
+# Colored output with timer
+prove -l --color --timer t/
+
+# TAP output for CI
+prove -l --formatter TAP::Formatter::JUnit t/ > results.xml
+```
+
+### .proverc Configuration
+
+```text
+-l
+--color
+--timer
+-r
+-j4
+--state=save
+```
+
+## Fixtures and Setup/Teardown
+
+### Subtest Isolation
+
+```perl
+use v5.36;
+use Test2::V0;
+use File::Temp qw(tempdir);
+use Path::Tiny;
+
+subtest 'file processing' => sub {
+    # Setup
+    my $dir = tempdir(CLEANUP => 1);
+    my $file = path($dir, 'input.txt');
+    $file->spew_utf8("line1\nline2\nline3\n");
+
+    # Test
+    my $result = process_file("$file");
+    is($result->{line_count}, 3, 'counts lines');
+
+    # Teardown happens automatically (CLEANUP => 1)
+};
+```
+
+### Shared Test Helpers
+
+Place reusable helpers in `t/lib/TestHelper.pm` and load with `use lib 't/lib'`. Export factory functions like `create_test_db()`, `create_temp_dir()`, and `fixture_path()` via `Exporter`.
+
+## Mocking
+
+### Test::MockModule
+
+```perl
+use v5.36;
+use Test2::V0;
+use Test::MockModule;
+
+subtest 'mock external API' => sub {
+    my $mock = Test::MockModule->new('MyApp::API');
+
+    # Good: Mock returns controlled data
+    $mock->mock(fetch_user => sub ($self, $id) {
+        return { id => $id, name => 'Mock User', email => 'mock@test.com' };
+    });
+
+    my $api = MyApp::API->new;
+    my $user = $api->fetch_user(42);
+    is($user->{name}, 'Mock User', 'returns mocked user');
+
+    # Verify call count
+    my $call_count = 0;
+    $mock->mock(fetch_user => sub { $call_count++; return {} });
+    $api->fetch_user(1);
+    $api->fetch_user(2);
+    is($call_count, 2, 'fetch_user called twice');
+
+    # Mock is automatically restored when $mock goes out of scope
+};
+
+# Bad: Monkey-patching without restoration
+# *MyApp::API::fetch_user = sub { ... };  # NEVER — leaks across tests
+```
+
+For lightweight mock objects, use `Test::MockObject` to create injectable test doubles with `->mock()` and verify calls with `->called_ok()`.
+
+## Coverage with Devel::Cover
+
+### Running Coverage
+
+```bash
+# Basic coverage report
+cover -test
+
+# Or step by step
+perl -MDevel::Cover -Ilib t/unit/user.t
+cover
+
+# HTML report
+cover -report html
+open cover_db/coverage.html
+
+# Specific thresholds
+cover -test -report text | grep 'Total'
+
+# CI-friendly: fail under threshold
+cover -test && cover -report text -select '^lib/' \
+  | perl -ne 'if (/Total.*?(\d+\.\d+)/) { exit 1 if $1 < 80 }'
+```
+
+### Integration Testing
+
+Use in-memory SQLite for database tests, mock HTTP::Tiny for API tests.
+
+```perl
+use v5.36;
+use Test2::V0;
+use DBI;
+
+subtest 'database integration' => sub {
+    my $dbh = DBI->connect('dbi:SQLite:dbname=:memory:', '', '', {
+        RaiseError => 1,
+    });
+    $dbh->do('CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)');
+
+    $dbh->prepare('INSERT INTO users (name) VALUES (?)')->execute('Alice');
+    my $row = $dbh->selectrow_hashref('SELECT * FROM users WHERE name = ?', undef, 'Alice');
+    is($row->{name}, 'Alice', 'inserted and retrieved user');
+};
+
+done_testing;
+```
+
+## Best Practices
+
+### DO
+
+- **Follow TDD**: Write tests before implementation (red-green-refactor)
+- **Use Test2::V0**: Modern assertions, better diagnostics
+- **Use subtests**: Group related assertions, isolate state
+- **Mock external dependencies**: Network, database, file system
+- **Use `prove -l`**: Always include lib/ in `@INC`
+- **Name tests clearly**: `'user login with invalid password fails'`
+- **Test edge cases**: Empty strings, undef, zero, boundary values
+- **Aim for 80%+ coverage**: Focus on business logic paths
+- **Keep tests fast**: Mock I/O, use in-memory databases
+
+### DON'T
+
+- **Don't test implementation**: Test behavior and output, not internals
+- **Don't share state between subtests**: Each subtest should be independent
+- **Don't skip `done_testing`**: Ensures all planned tests ran
+- **Don't over-mock**: Mock boundaries only, not the code under test
+- **Don't use `Test::More` for new projects**: Prefer Test2::V0
+- **Don't ignore test failures**: All tests must pass before merge
+- **Don't test CPAN modules**: Trust libraries to work correctly
+- **Don't write brittle tests**: Avoid over-specific string matching
+
+## Quick Reference
+
+| Task | Command / Pattern |
+|---|---|
+| Run all tests | `prove -lr t/` |
+| Run one test verbose | `prove -lv t/unit/user.t` |
+| Parallel test run | `prove -lr -j8 t/` |
+| Coverage report | `cover -test && cover -report html` |
+| Test equality | `is($got, $expected, 'label')` |
+| Deep comparison | `is($got, hash { field k => 'v'; etc() }, 'label')` |
+| Test exception | `like(dies { ... }, qr/msg/, 'label')` |
+| Test no exception | `ok(lives { ... }, 'label')` |
+| Mock a method | `Test::MockModule->new('Pkg')->mock(m => sub { ... })` |
+| Skip tests | `SKIP: { skip 'reason', $count unless $cond; ... }` |
+| TODO tests | `TODO: { local $TODO = 'reason'; ... }` |
+
+## Common Pitfalls
+
+### Forgetting `done_testing`
+
+```perl
+# Bad: Test file runs but doesn't verify all tests executed
+use Test2::V0;
+is(1, 1, 'works');
+# Missing done_testing — silent bugs if test code is skipped
+
+# Good: Always end with done_testing
+use Test2::V0;
+is(1, 1, 'works');
+done_testing;
+```
+
+### Missing `-l` Flag
+
+```bash
+# Bad: Modules in lib/ not found
+prove t/unit/user.t
+# Can't locate MyApp/User.pm in @INC
+
+# Good: Include lib/ in @INC
+prove -l t/unit/user.t
+```
+
+### Over-Mocking
+
+Mock the *dependency*, not the code under test. If your test only verifies that a mock returns what you told it to, it tests nothing.
+
+### Test Pollution
+
+Use `my` variables inside subtests — never `our` — to prevent state leaking between tests.
+
+**Remember**: Tests are your safety net. Keep them fast, focused, and independent. Use Test2::V0 for new projects, prove for running, and Devel::Cover for accountability.

package/.agent/skills/plankton-code-quality/SKILL.md

@@ -0,0 +1,236 @@
+---
+name: plankton-code-quality
+description: "Write-time code quality enforcement using Plankton — auto-formatting, linting, and Claude-powered fixes on every file edit via hooks."
+origin: community
+---
+
+# Plankton Code Quality Skill
+
+Integration reference for Plankton (credit: @alxfazio), a write-time code quality enforcement system for Claude Code. Plankton runs formatters and linters on every file edit via PostToolUse hooks, then spawns Claude subprocesses to fix violations the agent didn't catch.
+
+## When to Use
+
+- You want automatic formatting and linting on every file edit (not just at commit time)
+- You need defense against agents modifying linter configs to pass instead of fixing code
+- You want tiered model routing for fixes (Haiku for simple style, Sonnet for logic, Opus for types)
+- You work with multiple languages (Python, TypeScript, Shell, YAML, JSON, TOML, Markdown, Dockerfile)
+
+## How It Works
+
+### Three-Phase Architecture
+
+Every time Claude Code edits or writes a file, Plankton's `multi_linter.sh` PostToolUse hook runs:
+
+```
+Phase 1: Auto-Format (Silent)
+├─ Runs formatters (ruff format, biome, shfmt, taplo, markdownlint)
+├─ Fixes 40-50% of issues silently
+└─ No output to main agent
+
+Phase 2: Collect Violations (JSON)
+├─ Runs linters and collects unfixable violations
+├─ Returns structured JSON: {line, column, code, message, linter}
+└─ Still no output to main agent
+
+Phase 3: Delegate + Verify
+├─ Spawns claude -p subprocess with violations JSON
+├─ Routes to model tier based on violation complexity:
+│   ├─ Haiku: formatting, imports, style (E/W/F codes) — 120s timeout
+│   ├─ Sonnet: complexity, refactoring (C901, PLR codes) — 300s timeout
+│   └─ Opus: type system, deep reasoning (unresolved-attribute) — 600s timeout
+├─ Re-runs Phase 1+2 to verify fixes
+└─ Exit 0 if clean, Exit 2 if violations remain (reported to main agent)
+```
+
+### What the Main Agent Sees
+
+| Scenario | Agent sees | Hook exit |
+|----------|-----------|-----------|
+| No violations | Nothing | 0 |
+| All fixed by subprocess | Nothing | 0 |
+| Violations remain after subprocess | `[hook] N violation(s) remain` | 2 |
+| Advisory (duplicates, old tooling) | `[hook:advisory] ...` | 0 |
+
+The main agent only sees issues the subprocess couldn't fix. Most quality problems are resolved transparently.
+
+### Config Protection (Defense Against Rule-Gaming)
+
+LLMs will modify `.ruff.toml` or `biome.json` to disable rules rather than fix code. Plankton blocks this with three layers:
+
+1. **PreToolUse hook** — `protect_linter_configs.sh` blocks edits to all linter configs before they happen
+2. **Stop hook** — `stop_config_guardian.sh` detects config changes via `git diff` at session end
+3. **Protected files list** — `.ruff.toml`, `biome.json`, `.shellcheckrc`, `.yamllint`, `.hadolint.yaml`, and more
+
+### Package Manager Enforcement
+
+A PreToolUse hook on Bash blocks legacy package managers:
+- `pip`, `pip3`, `poetry`, `pipenv` → Blocked (use `uv`)
+- `npm`, `yarn`, `pnpm` → Blocked (use `bun`)
+- Allowed exceptions: `npm audit`, `npm view`, `npm publish`
+
+## Setup
+
+### Quick Start
+
+> **Note:** Plankton requires manual installation from its repository. Review the code before installing.
+
+```bash
+# Install core dependencies
+brew install jaq ruff uv
+
+# Install Python linters
+uv sync --all-extras
+
+# Start Claude Code — hooks activate automatically
+claude
+```
+
+No install command, no plugin config. The hooks in `.claude/settings.json` are picked up automatically when you run Claude Code in the Plankton directory.
+
+### Per-Project Integration
+
+To use Plankton hooks in your own project:
+
+1. Copy `.claude/hooks/` directory to your project
+2. Copy `.claude/settings.json` hook configuration
+3. Copy linter config files (`.ruff.toml`, `biome.json`, etc.)
+4. Install the linters for your languages
+
+### Language-Specific Dependencies
+
+| Language | Required | Optional |
+|----------|----------|----------|
+| Python | `ruff`, `uv` | `ty` (types), `vulture` (dead code), `bandit` (security) |
+| TypeScript/JS | `biome` | `oxlint`, `semgrep`, `knip` (dead exports) |
+| Shell | `shellcheck`, `shfmt` | — |
+| YAML | `yamllint` | — |
+| Markdown | `markdownlint-cli2` | — |
+| Dockerfile | `hadolint` (>= 2.12.0) | — |
+| TOML | `taplo` | — |
+| JSON | `jaq` | — |
+
+## Pairing with ECC
+
+### Complementary, Not Overlapping
+
+| Concern | ECC | Plankton |
+|---------|-----|----------|
+| Code quality enforcement | PostToolUse hooks (Prettier, tsc) | PostToolUse hooks (20+ linters + subprocess fixes) |
+| Security scanning | AgentShield, security-reviewer agent | Bandit (Python), Semgrep (TypeScript) |
+| Config protection | — | PreToolUse blocks + Stop hook detection |
+| Package manager | Detection + setup | Enforcement (blocks legacy PMs) |
+| CI integration | — | Pre-commit hooks for git |
+| Model routing | Manual (`/model opus`) | Automatic (violation complexity → tier) |
+
+### Recommended Combination
+
+1. Install ECC as your plugin (agents, skills, commands, rules)
+2. Add Plankton hooks for write-time quality enforcement
+3. Use AgentShield for security audits
+4. Use ECC's verification-loop as a final gate before PRs
+
+### Avoiding Hook Conflicts
+
+If running both ECC and Plankton hooks:
+- ECC's Prettier hook and Plankton's biome formatter may conflict on JS/TS files
+- Resolution: disable ECC's Prettier PostToolUse hook when using Plankton (Plankton's biome is more comprehensive)
+- Both can coexist on different file types (ECC handles what Plankton doesn't cover)
+
+## Configuration Reference
+
+Plankton's `.claude/hooks/config.json` controls all behavior:
+
+```json
+{
+  "languages": {
+    "python": true,
+    "shell": true,
+    "yaml": true,
+    "json": true,
+    "toml": true,
+    "dockerfile": true,
+    "markdown": true,
+    "typescript": {
+      "enabled": true,
+      "js_runtime": "auto",
+      "biome_nursery": "warn",
+      "semgrep": true
+    }
+  },
+  "phases": {
+    "auto_format": true,
+    "subprocess_delegation": true
+  },
+  "subprocess": {
+    "tiers": {
+      "haiku":  { "timeout": 120, "max_turns": 10 },
+      "sonnet": { "timeout": 300, "max_turns": 10 },
+      "opus":   { "timeout": 600, "max_turns": 15 }
+    },
+    "volume_threshold": 5
+  }
+}
+```
+
+**Key settings:**
+- Disable languages you don't use to speed up hooks
+- `volume_threshold` — violations > this count auto-escalate to a higher model tier
+- `subprocess_delegation: false` — skip Phase 3 entirely (just report violations)
+
+## Environment Overrides
+
+| Variable | Purpose |
+|----------|---------|
+| `HOOK_SKIP_SUBPROCESS=1` | Skip Phase 3, report violations directly |
+| `HOOK_SUBPROCESS_TIMEOUT=N` | Override tier timeout |
+| `HOOK_DEBUG_MODEL=1` | Log model selection decisions |
+| `HOOK_SKIP_PM=1` | Bypass package manager enforcement |
+
+## References
+
+- Plankton (credit: @alxfazio)
+- Plankton REFERENCE.md — Full architecture documentation (credit: @alxfazio)
+- Plankton SETUP.md — Detailed installation guide (credit: @alxfazio)
+
+## ECC v1.8 Additions
+
+### Copyable Hook Profile
+
+Set strict quality behavior:
+
+```bash
+export ECC_HOOK_PROFILE=strict
+export ECC_QUALITY_GATE_FIX=true
+export ECC_QUALITY_GATE_STRICT=true
+```
+
+### Language Gate Table
+
+- TypeScript/JavaScript: Biome preferred, Prettier fallback
+- Python: Ruff format/check
+- Go: gofmt
+
+### Config Tamper Guard
+
+During quality enforcement, flag changes to config files in same iteration:
+
+- `biome.json`, `.eslintrc*`, `prettier.config*`, `tsconfig.json`, `pyproject.toml`
+
+If config is changed to suppress violations, require explicit review before merge.
+
+### CI Integration Pattern
+
+Use the same commands in CI as local hooks:
+
+1. run formatter checks
+2. run lint/type checks
+3. fail fast on strict mode
+4. publish remediation summary
+
+### Health Metrics
+
+Track:
+- edits flagged by gates
+- average remediation time
+- repeat violations by category
+- merge blocks due to gate failures