@plaited/acp-harness 0.2.5

package/.claude/rules/accuracy.md

@@ -0,0 +1,43 @@
+# Accuracy and Confidence Standards
+
+**Confidence Threshold**: 95% - Report uncertainty rather than guess
+
+## Verification Protocol
+
+1. **Verification First**: Before stating any specific implementation detail (function signature, file path, API schema), use the `typescript-lsp` skill to verify types and signatures, then read the relevant file in real-time to verify accuracy.
+
+2. **Handling Uncertainty**: If you cannot verify information or find contradictions between instructions and live code, you must NOT provide speculative answers.
+   - **Action**: Clearly state you cannot answer with high confidence and explain the discrepancy.
+   - Example: "I cannot confirm [detail] because my instructions indicate [X], but the current file shows [Y]. My knowledge may be outdated."
+
+3. **Dynamic Exploration**:
+   - **PREFER typescript-lsp over Grep/Glob** for `.ts`, `.tsx`, `.js`, `.jsx` files
+   - Use `lsp-find` to search for symbols, types, and patterns across the workspace
+   - Use `lsp-references` to find all usages of a symbol
+   - Use `lsp-hover` to verify type signatures
+   - Only fall back to Grep/Glob for non-TypeScript files or when LSP is unavailable
+   - Use Read for other file types. Always prioritize live code over instructions.
+
+4. **Tool-Assisted Verification**: Use these skills to enhance verification accuracy:
+   - **`typescript-lsp` skill**: Use `lsp-hover` to verify type signatures, `lsp-references` to find all usages before modifying, `lsp-symbols` for file structure, and `lsp-find` to search for patterns across the workspace.
+   - **WebFetch**: Retrieve current documentation from authoritative sources (MDN Web Docs, WHATWG specs) when using web platform APIs.
+   - These skills complement (but do not replace) reading live code - always verify outputs against actual implementation.
+
+## Certainty Requirements
+
+You may only propose a specific change if you are **at least 95% certain** it is correct, based on direct comparison with current code.
+
+**When uncertain:**
+- Report the discrepancy clearly
+- State why you cannot confidently recommend a fix
+- Present the issue to the user for manual resolution
+- DO NOT invent solutions or infer changes
+
+## For Agent-Specific Applications
+
+Agents should apply these standards to their specific domain:
+
+- **Documentation agents**: Only update TSDoc if parameter names/types match current code
+- **Architecture agents**: Verify referenced patterns exist in current codebase
+- **Code review agents**: Read files before commenting on implementation details
+- **Pattern agents**: Confirm examples reflect actual usage in codebase

package/.claude/rules/bun-apis.md

@@ -0,0 +1,80 @@
+# Bun Platform APIs
+
+**IMPORTANT**: Prefer Bun's native APIs over Node.js equivalents when running in the Bun environment.
+
+## File System Operations
+
+- ✅ Use `Bun.file(path).exists()` instead of `fs.existsSync()`
+- ✅ Use `Bun.file(path)` API for reading/writing files
+- ✅ Use `Bun.write()` for efficient file writes
+
+```typescript
+// ✅ Good: Bun APIs
+const exists = await Bun.file('config.json').exists()
+const content = await Bun.file('data.txt').text()
+await Bun.write('output.json', JSON.stringify(data))
+
+// ❌ Avoid: Node.js equivalents
+import { existsSync, readFileSync, writeFileSync } from 'node:fs'
+const exists = existsSync('config.json')
+```
+
+## Shell Commands
+
+- ✅ Use `Bun.$` template literal for shell commands
+- ❌ Avoid `child_process.spawn()` or `child_process.exec()`
+
+```typescript
+// ✅ Good: Bun shell
+await Bun.$`npm install`
+const result = await Bun.$`git status`.text()
+
+// ❌ Avoid: Node.js child_process
+import { spawn } from 'node:child_process'
+spawn('npm', ['install'])
+```
+
+## Path Resolution
+
+- ✅ Use `Bun.resolveSync()` for module resolution
+- ✅ Use `import.meta.dir` for current directory
+- ⚠️ Keep `node:path` utilities for path manipulation (join, resolve, dirname)
+
+```typescript
+// ✅ Good: Bun + node:path combo
+import { join } from 'node:path'
+const configPath = join(import.meta.dir, 'config.json')
+const resolved = Bun.resolveSync('./module', import.meta.dir)
+```
+
+## Package Management
+
+- ✅ Use `Bun.which(cmd)` to check for executables
+- ⚠️ No programmatic package manager API yet - use CLI commands via `Bun.$`
+
+```typescript
+// ✅ Good: Check for executable
+const bunPath = Bun.which('bun')
+if (!bunPath) throw new Error('bun not found')
+
+// Install packages via shell
+await Bun.$`bun add zod`
+```
+
+## Environment Detection
+
+- ✅ Check `typeof Bun !== 'undefined'` for Bun runtime
+- ✅ Use `Bun.which('bun')` to verify bun executable exists
+
+## When to Use Node.js APIs
+
+- Interactive input (readline)
+- Complex path manipulation (prefer `node:path` utilities)
+- APIs without Bun equivalents
+
+## Documentation
+
+- Main docs: https://bun.sh/docs
+- Shell API: https://bun.sh/docs/runtime/shell
+- File I/O: https://bun.sh/docs/api/file-io
+- Runtime APIs: https://bun.sh/docs/runtime/bun-apis

package/.claude/rules/code-review.md

@@ -0,0 +1,254 @@
+# Code Review Standards
+
+The following standards are not automatically enforced by Biome but should be checked during code review.
+
+## Automated Validation
+
+Before completing a code review, run these validation scripts:
+
+### Plugin Skills Validation
+
+When changes touch `.claude/skills/`, validate against the AgentSkills spec by running:
+
+```
+/validate-skill
+```
+
+This checks:
+- SKILL.md exists and has required frontmatter
+- Scripts have proper structure
+- References are valid markdown files
+
+## TypeScript Style Conventions
+
+### Prefer `type` Over `interface`
+
+Use type aliases instead of interfaces for better consistency and flexibility:
+
+```typescript
+// ✅ Good
+type User = {
+  name: string
+  email: string
+}
+
+// ❌ Avoid
+interface User {
+  name: string
+  email: string
+}
+```
+
+**Rationale:** Type aliases are more flexible (unions, intersections, mapped types) and provide consistent syntax across the codebase.
+
+### No `any` Types
+
+Always use proper types; use `unknown` if type is truly unknown and add type guards:
+
+```typescript
+// ✅ Good
+const process = (data: unknown) => {
+  if (typeof data === 'string') {
+    return data.toUpperCase()
+  }
+}
+
+// ❌ Avoid
+const process = (data: any) => {
+  return data.toUpperCase()
+}
+```
+
+### PascalCase for Types and Schemas
+
+All type names use PascalCase. Zod schema names use `PascalCaseSchema` suffix:
+
+```typescript
+// ✅ Good
+type UserConfig = { /* ... */ }
+const UserConfigSchema = z.object({ /* ... */ })
+
+// ❌ Avoid
+type userConfig = { /* ... */ }
+const zUserConfig = z.object({ /* ... */ })  // Don't use z-prefix
+```
+
+### Arrow Functions Preferred
+
+```typescript
+// ✅ Good
+const greet = (name: string) => `Hello, ${name}!`
+
+// ❌ Avoid
+function greet(name: string) {
+  return `Hello, ${name}!`
+}
+```
+
+### Object Parameter Pattern
+
+For functions with more than two parameters, use a single object parameter:
+
+```typescript
+// ✅ Good: Object parameter pattern
+const createClient = ({
+  command,
+  timeout,
+  cwd,
+}: {
+  command: string[]
+  timeout: number
+  cwd?: string
+}): ACPClient => { /* ... */ }
+
+// ❌ Avoid: Multiple positional parameters
+const createClient = (
+  command: string[],
+  timeout: number,
+  cwd?: string
+): ACPClient => { /* ... */ }
+```
+
+## TypeScript Comment Directives
+
+### `@ts-ignore` Requires Description
+
+- When using `@ts-ignore`, always include a description explaining why the type error is being suppressed
+- This helps future maintainers understand the reasoning
+- Example:
+  ```typescript
+  // @ts-ignore - TypeScript incorrectly infers this as string when it's actually a number from the API
+  const value = response.data
+  ```
+
+**Rationale:** Lost TypeScript-ESLint rule `ban-ts-comment` with `allow-with-description` option during Biome migration
+
+## Expression Statements
+
+### Allow Short-Circuit and Ternary Expressions
+
+- Short-circuit evaluation is acceptable: `condition && doSomething()`
+- Ternary expressions are acceptable: `condition ? doThis() : doThat()`
+- These patterns are idiomatic and improve code readability
+
+**Rationale:** Lost TypeScript-ESLint rule `no-unused-expressions` with `allowShortCircuit` and `allowTernary` options during Biome migration
+
+## Empty Object Types
+
+### Allow Empty Object Types When Extending a Single Interface
+
+- Empty object types are acceptable when they extend exactly one other interface
+- This pattern is useful for creating branded types or extending third-party interfaces
+- Example:
+  ```typescript
+  // ✅ Acceptable: Extends single interface
+  interface CustomElement extends HTMLElement {}
+
+  // ❌ Avoid: Empty with no extends or multiple extends
+  interface Empty {}
+  interface Multi extends Foo, Bar {}
+  ```
+
+**Rationale:** Lost TypeScript-ESLint rule `no-empty-object-type` with `allowInterfaces: 'with-single-extends'` option during Biome migration
+
+## Modern JavaScript Standards
+
+### Prefer Private Fields Over `private` Keyword
+
+Use JavaScript private fields (`#field`) instead of TypeScript's `private` keyword:
+
+```typescript
+// ✅ Good: JavaScript private fields (ES2022+)
+class EventBus {
+  #listeners = new Map<string, Set<Function>>()
+  #count = 0
+
+  #emit(event: string) {
+    this.#count++
+    this.#listeners.get(event)?.forEach(fn => fn())
+  }
+}
+
+// ❌ Avoid: TypeScript private keyword
+class EventBus {
+  private listeners = new Map<string, Set<Function>>()
+  private count = 0
+
+  private emit(event: string) {
+    this.count++
+    this.listeners.get(event)?.forEach(fn => fn())
+  }
+}
+```
+
+**Rationale:** JavaScript private fields are a runtime feature (ES2022) providing true encapsulation. TypeScript's `private` is erased at compile time and can be bypassed. Prefer platform standards over TypeScript-only features
+
+### JSON Import Attributes
+
+Use import attributes when importing JSON files. This is required because the tsconfig uses `verbatimModuleSyntax: true` without `resolveJsonModule`:
+
+```typescript
+// ✅ Good: Import attribute for JSON
+import { version } from '../package.json' with { type: 'json' }
+import config from './config.json' with { type: 'json' }
+
+// ❌ Avoid: Missing import attribute
+import { version } from '../package.json'
+import config from './config.json'
+```
+
+**Rationale:** Import attributes (ES2025) explicitly declare module types to the runtime. The `with { type: 'json' }` syntax is the standard (replacing the deprecated `assert` keyword). This provides runtime enforcement—if the file isn't valid JSON, the import fails.
+
+## Module Organization
+
+Organize module exports into separate files by category:
+
+```
+module/
+├── module.types.ts      # Type definitions only
+├── module.schemas.ts    # Zod schemas and schema-inferred types
+├── module.constants.ts  # Constants and enum-like objects
+├── module-client.ts     # Implementation
+└── index.ts             # Public API exports (barrel file)
+```
+
+### Key Principles
+
+- **Types file**: Contains only type definitions, does NOT re-export from sibling files
+- **Schemas file**: Contains Zod schemas and their inferred types, does NOT export constants
+- **Constants file**: Contains all constant values (error codes, method names, defaults)
+- **Barrel file**: Uses wildcard exports; non-public files are simply not included
+
+```typescript
+// ✅ Good: Direct imports from specific files
+import type { Config } from './module.types.ts'
+import { ConfigSchema } from './module.schemas.ts'
+import { METHODS, ERROR_CODES } from './module.constants.ts'
+
+// ❌ Avoid: Expecting types file to re-export everything
+import { Config, ConfigSchema, METHODS } from './module.types.ts'
+```
+
+**Rationale:** Prevents circular dependencies, makes dependencies explicit, improves tree-shaking.
+
+## Documentation Standards
+
+### Mermaid Diagrams Only
+
+Use [mermaid](https://mermaid.js.org/) syntax for all diagrams in markdown files:
+
+```markdown
+\```mermaid
+flowchart TD
+    A[Start] --> B[Process]
+    B --> C[End]
+\```
+```
+
+**Avoid**: ASCII box-drawing characters (`┌`, `│`, `└`, `─`, etc.)
+
+**Rationale:** Token efficiency, clearer semantic meaning, easier maintenance.
+
+### No `@example` Sections in TSDoc
+
+Tests serve as living examples. Do not add `@example` sections to TSDoc comments.

package/.claude/rules/git-workflow.md

@@ -0,0 +1,37 @@
+# Git Workflow
+
+## Commit Message Format
+
+When creating commits with multi-line messages, use single-quoted strings instead of heredocs. The sandbox environment restricts temp file creation needed for heredocs.
+
+```bash
+# ✅ CORRECT: Single-quoted multi-line string
+git commit -m 'refactor: description here
+
+Additional context on second line.
+
+🤖 Generated with [Claude Code](https://claude.com/claude-code)
+
+Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>'
+
+# ❌ WRONG: Heredoc syntax (fails in sandbox)
+git commit -m "$(cat <<'EOF'
+refactor: description here
+EOF
+)"
+```
+
+The heredoc approach fails with:
+```
+(eval):1: can't create temp file for here document: operation not permitted
+```
+
+## Commit Conventions
+
+This project follows conventional commits:
+- `feat:` - New features
+- `fix:` - Bug fixes
+- `refactor:` - Code changes that neither fix bugs nor add features
+- `docs:` - Documentation only changes
+- `chore:` - Maintenance tasks
+- `test:` - Adding or updating tests

package/.claude/rules/github.md

@@ -0,0 +1,154 @@
+# GitHub Integration
+
+## Prefer GitHub CLI Over Web Fetch
+
+When given GitHub URLs (PRs, issues, repos), use the `gh` CLI instead of WebFetch for more reliable and complete data access.
+
+### PR Information
+
+```bash
+# Get PR details with comments and reviews (comprehensive)
+gh pr view <number> --repo <owner>/<repo> --json title,body,comments,reviews,reviewRequests,state,author,additions,deletions,changedFiles
+
+# Get PR diff
+gh pr diff <number> --repo <owner>/<repo>
+
+# Get PR files changed
+gh pr view <number> --repo <owner>/<repo> --json files
+
+# Get PR checks status
+gh pr checks <number> --repo <owner>/<repo>
+```
+
+### Complete PR Evaluation Workflow
+
+When asked to evaluate PR feedback, you MUST fetch **all** feedback sources. Do not just fetch comments/reviews - also check security alerts and inline code comments.
+
+**Step 1: Fetch PR comments and reviews**
+```bash
+gh pr view <number> --repo <owner>/<repo> --json title,body,comments,reviews,state
+```
+
+**Step 2: Fetch code scanning alerts (security vulnerabilities)**
+```bash
+gh api repos/<owner>/<repo>/code-scanning/alerts --jq '
+  .[] | select(.state == "open") | {
+    number: .number,
+    rule: .rule.description,
+    severity: .rule.severity,
+    file: .most_recent_instance.location.path,
+    line: .most_recent_instance.location.start_line
+  }
+'
+```
+
+**Step 3: Fetch inline review comments (code quality, suggestions)**
+```bash
+gh api repos/<owner>/<repo>/pulls/<number>/comments --jq '
+  .[] | {
+    id: .id,
+    user: .user.login,
+    file: .path,
+    line: .line,
+    body: .body
+  }
+'
+```
+
+**Step 4: Address ALL feedback**
+Create a checklist and address each item:
+- [ ] Human reviewer comments
+- [ ] Claude Code review comments
+- [ ] GitHub Advanced Security alerts (ReDoS, injection, etc.)
+- [ ] GitHub Code Quality comments (dead code, useless assignments)
+- [ ] Inline review suggestions
+
+### Comment Sources
+
+| Source | API/Location | Description |
+|--------|--------------|-------------|
+| Human reviewers | `gh pr view --json reviews` | Code owners, team members |
+| Claude Code | `gh pr view --json comments` | AI-generated review (login: `claude`) |
+| GitHub Advanced Security | `gh api .../code-scanning/alerts` | Security vulnerabilities (ReDoS, injection) |
+| GitHub Code Quality | `gh api .../pulls/.../comments` | Code quality issues (login: `github-code-quality[bot]`) |
+| Inline suggestions | `gh api .../pulls/.../comments` | Line-specific review comments |
+
+### Filtering by Author
+
+```bash
+# Get all automated reviews from PR
+gh pr view <number> --repo <owner>/<repo> --json reviews --jq '
+  .reviews[] | select(.author.login | test("github-|claude")) | {author: .author.login, state: .state}
+'
+
+# Get specific inline comment by ID
+gh api repos/<owner>/<repo>/pulls/<number>/comments --jq '
+  .[] | select(.id == <comment_id>)
+'
+```
+
+### URL Patterns for Specific Feedback
+
+| URL Pattern | How to Fetch |
+|-------------|--------------|
+| `.../pull/<n>#issuecomment-<id>` | `gh pr view <n> --json comments` |
+| `.../pull/<n>#discussion_r<id>` | `gh api repos/.../pulls/<n>/comments` |
+| `.../security/code-scanning/<id>` | `gh api repos/.../code-scanning/alerts/<id>` |
+
+### Review States
+- `APPROVED` - Reviewer approved changes
+- `CHANGES_REQUESTED` - Reviewer requested changes
+- `COMMENTED` - Review with comments only
+- `PENDING` - Review not yet submitted
+
+### Issue Information
+
+```bash
+# Get issue details
+gh issue view <number> --repo <owner>/<repo> --json title,body,comments,state,author
+
+# List issues
+gh issue list --repo <owner>/<repo> --json number,title,state
+```
+
+### Repository Information
+
+```bash
+# Get repo info
+gh repo view <owner>/<repo> --json name,description,url
+
+# List workflows
+gh workflow list --repo <owner>/<repo>
+
+# View run logs
+gh run view <run-id> --repo <owner>/<repo> --log
+```
+
+### URL Parsing
+
+When given a GitHub URL, extract the components:
+
+| URL Pattern | Command |
+|-------------|---------|
+| `github.com/<owner>/<repo>/pull/<number>` | `gh pr view <number> --repo <owner>/<repo>` |
+| `github.com/<owner>/<repo>/issues/<number>` | `gh issue view <number> --repo <owner>/<repo>` |
+| `github.com/<owner>/<repo>` | `gh repo view <owner>/<repo>` |
+| `github.com/<owner>/<repo>/actions/runs/<id>` | `gh run view <id> --repo <owner>/<repo>` |
+
+### JSON Output Fields
+
+Common useful JSON fields for PRs:
+- `title`, `body`, `state`, `author`
+- `comments` - PR comments
+- `reviews` - Review comments and approvals
+- `additions`, `deletions`, `changedFiles`
+- `files` - List of changed files
+- `commits` - Commit history
+
+### Benefits Over WebFetch
+
+1. **Complete data** - Access to all comments, reviews, and metadata
+2. **Authentication** - Uses configured GitHub credentials
+3. **Structured output** - JSON format for reliable parsing
+4. **No rate limiting issues** - Authenticated requests have higher limits
+5. **Access to private repos** - Works with repos you have access to