ctxora 6.2.2 → 6.3.0

package/src/harness_context/skills/ecc/perl-testing/SKILL.md

@@ -0,0 +1,476 @@
+---
+name: perl-testing
+description: Perl testing patterns using Test2::V0, Test::More, prove runner, mocking, coverage with Devel::Cover, and TDD methodology. Use when writing Perl tests with Test2::V0 or Test::More, or measuring coverage.
+metadata:
+  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/src/harness_context/skills/ecc/plan-canvas/LICENSE.ecc

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Affaan Mustafa
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/src/harness_context/skills/ecc/plan-canvas/SKILL.md

@@ -0,0 +1,196 @@
+---
+name: plan-canvas
+description: Open plans and HTML artifacts in a local browser canvas where the human annotates elements, chats, and approves or requests changes without leaving the page. Use when presenting a plan for review, or when feedback like "move this, change that" is easier pointed at than typed.
+metadata:
+  version: "1.0.0"
+  origin: ECC
+---
+
+# Plan Canvas
+
+Review loop for plans and visual artifacts: you write the artifact, the human
+reviews it in the browser — annotating the exact element they mean, chatting,
+and delivering an **Approve plan / Request changes** verdict — while you block
+on a single CLI call that returns their feedback as JSON.
+
+Inspired by [lavish-axi](https://github.com/kunchenguid/lavish-axi); rebuilt
+ECC-native around the `/plan` confirmation gate, with zero dependencies.
+
+## When to Use
+
+- You just wrote a plan artifact (`.claude/plans/*.plan.md` from `/plan`) and
+  need the CONFIRM/approve decision — the canvas verdict replaces a typed
+  "yes/proceed".
+- The user should *point at* what to change: reviewing designs, comparisons,
+  reports, or any local `.md` / `.html` artifact.
+- The user asks for `/plan-canvas`, a visual review, or "open it in the browser".
+
+Do NOT use for: code review of diffs (`/code-review`), running web apps, or
+remote URLs. The canvas serves local artifact files only.
+
+## How It Works
+
+Invoke the CLI as `ecc-plan-canvas` — the bin shipped by the `ecc-universal`
+package (on PATH after a global/plugin install; `node "$CLAUDE_PLUGIN_ROOT/scripts/plan-canvas.js"`
+also works for plugin installs). Run it from the project you are reviewing in;
+it works from any working directory. It manages a detached loopback server
+(`127.0.0.1:4517`) shared by all sessions, keyed by artifact path — no session
+ids to track.
+
+The workflow is a plain CLI-plus-JSON loop, so it is model- and harness-agnostic:
+any agent that can run a shell command and read stdout drives it the same way
+(Claude Code, Codex, Cursor, Gemini, OpenCode, Copilot). Trigger it however your
+harness surfaces skills — e.g. `/plan-canvas` in Claude Code, `$plan-canvas` in
+Codex — or just run the `ecc-plan-canvas` commands directly.
+
+```bash
+# 1. Open the artifact in the user's browser (returns immediately)
+ecc-plan-canvas open .claude/plans/feature.plan.md
+
+# 2. Block until the human responds. Leave running; re-run if interrupted:
+#    queued feedback is never lost.
+ecc-plan-canvas await .claude/plans/feature.plan.md
+```
+
+### Stay listening, or the human talks to an empty chair
+
+Feedback only reaches you while an `await` is actually parked on the session.
+If your turn ends with nothing listening, the message sits in the queue and,
+from the human's side of the glass, sending appears to do nothing at all.
+
+So **run `await` as a background task** when your harness supports one (in
+Claude Code, a Bash call with `run_in_background: true`). It exits the moment
+feedback arrives and the harness hands you the JSON, which keeps the loop alive
+across turns instead of dying with the foreground call. A foreground `await`
+works too, but only until the harness time-limits it.
+
+Two backstops exist, and neither is an excuse to skip the above:
+
+- `ecc-plan-canvas pending` lists feedback queued with no listener. Check it
+  whenever you are unsure whether you missed something.
+- The `stop:plan-canvas-pending` hook blocks your turn from ending while canvas
+  feedback is undelivered, and hands you the messages. If you are reading
+  feedback from that hook, you stopped listening too early.
+
+`await` prints JSON when the human acts:
+
+```json
+{
+  "status": "feedback",
+  "items": [
+    { "kind": "annotation", "text": "Split this into two phases",
+      "anchor": { "selector": "h2:nth-of-type(3)", "tag": "h2", "snippet": "Phase 2: Migration" } },
+    { "kind": "verdict", "verdict": "request-changes" }
+  ]
+}
+```
+
+- `kind: "chat"` — freeform message; answer in the canvas, not the terminal.
+- `kind: "annotation"` — feedback anchored to an element (`anchor.selector`,
+  `anchor.snippet` show what they pointed at; `anchor.textRange.text` when
+  they highlighted a passage).
+- `kind: "verdict"` — `approve` means the plan is CONFIRMED: stop polling,
+  end the session, and start implementing. `request-changes` means revise the
+  artifact (the canvas live-reloads it) and keep the loop going.
+
+**3. Always respond in the canvas**, then keep listening. One command does both:
+
+```bash
+ecc-plan-canvas await <file> --reply "Split Phase 2 as requested. Take a look."
+```
+
+Every human message gets a reply in the canvas, even a one-liner like
+"On it, rewriting the risk table now." Silence in the chat panel is
+indistinguishable from a broken canvas, which is exactly the failure this loop
+exists to prevent. Answer there, not only in the terminal.
+
+While you work, keep the chat honest with the activity indicator:
+
+```bash
+# animated "agent is thinking..." bubble; refresh it during long work
+ecc-plan-canvas typing <file> --state thinking
+# switch to "agent is typing..." just before a reply lands
+ecc-plan-canvas typing <file> --state typing
+```
+
+`await` sets `thinking` for you the moment it hands you a batch, and `--reply`
+clears it. Both states self-expire, so a crashed agent decays to an honest
+"queued" instead of leaving the human watching dots forever. Refresh `thinking`
+if a revision takes more than a minute.
+
+**4. End** when review concludes: `ecc-plan-canvas end <file>`.
+
+## Diagrams (Mermaid)
+
+When part of the plan is a flow, architecture, sequence, state machine, ER
+model, or dependency graph, author it as a fenced ` ```mermaid ` block instead
+of ASCII art or a wall of prose — the canvas renders it as a themed diagram the
+human can point at. Reach for it when a picture reads faster than a paragraph;
+skip it for simple lists or tables.
+
+````markdown
+```mermaid
+flowchart LR
+  A[Market resolves] --> B{Watchers?}
+  B -->|yes| C[Enqueue jobs] --> D[Fan-out worker]
+```
+````
+
+Diagrams render in the ECC dark theme with the accent palette. Mermaid loads in
+the browser from a pinned CDN; if that is unavailable (offline), the block
+degrades to showing its source, so the review is never blocked. Point a local
+mirror at `ECC_PLAN_CANVAS_MERMAID_URL` for air-gapped use.
+
+## Rules
+
+- Markdown artifacts render in ECC's plan template (including Mermaid blocks);
+  `.html` artifacts render as-is with the annotation layer injected. For HTML
+  authoring guidance use the `frontend-design-direction` and `artifact-design`
+  skills.
+- Edit the artifact file to revise — the canvas live-reloads on save. Never
+  re-run `open` to refresh.
+- `{"status": "ended", "endedBy": "user"}` (or `sessionEnded: true` on a
+  feedback batch) means the user closed the review: stop polling, deliver
+  remaining updates in chat, and do not reopen. A plain `open` on that
+  session is refused; pass `--reopen` only when the user asks to resume.
+- Sibling assets (images, CSS) must sit next to the artifact and be
+  referenced by relative path.
+- The server is loopback-only and exits after 30 idle minutes
+  (`ECC_PLAN_CANVAS_IDLE_MS`); `stop` shuts it down explicitly. State lives
+  in `~/.claude/plan-canvas/` (`ECC_PLAN_CANVAS_STATE_DIR`).
+
+## Examples
+
+**Plan approval flow** — `/plan` writes
+`.claude/plans/notifications.plan.md` and must WAIT for confirmation:
+
+```bash
+ecc-plan-canvas open .claude/plans/notifications.plan.md
+ecc-plan-canvas await .claude/plans/notifications.plan.md
+# → {"status":"feedback","items":[{"kind":"verdict","verdict":"approve"}]}
+ecc-plan-canvas end .claude/plans/notifications.plan.md
+# plan is confirmed — begin implementation
+```
+
+**Revision loop** — feedback arrives, you edit the file, reply, keep listening:
+
+```bash
+# await returned annotations → edit the .plan.md (canvas live-reloads)
+ecc-plan-canvas await <file> --reply "Reworked the risk table."
+# → blocks again until the next response
+```
+
+## Anti-Patterns
+
+- Polling with `--timeout-ms` in a loop. It exists for tests. Leave the plain
+  `await` running instead.
+- Ending your turn with no `await` listening while the review is still open.
+  That is the one failure the human experiences as "I sent a message and
+  nothing happened".
+- Reading the feedback but answering only in the terminal. The human is looking
+  at the canvas.
+- Reopening after a user-initiated end "just to show" something.
+- Pasting the whole plan into chat *and* opening a canvas — pick the canvas
+  and keep the terminal summary to one line.
+- Parsing the canvas chat from state files — everything you need arrives via
+  `await`.