ultimate-pi 0.18.1 → 0.19.0

package/.pi/skills/ast-grep/SKILL.md

@@ -1,354 +1,73 @@
 ---
 name: ast-grep
-description: "Structural code search using AST patterns via the `sg` CLI. Use when searching for code patterns, finding all call sites, locating function/class definitions, matching import structures, or any task where code shape matters not just text. Triggers on: find all usages, where is X called, find functions that, pattern search, structural search, AST search, find imports of, find class definitions, find methods with, codemod, rewrite code, refactor pattern, sg, ast-grep."
+description: "Structural code search and replacement using the sg CLI. Use for function calls, imports, class/method definitions, call sites, and codemods. Prefer LSP for definitions/references/types; use sg for structural patterns; reserve grep for exact literals, comments, URLs, or non-code files."
 allowed-tools:
   - Bash(sg *)
   - Bash(npm install -g @ast-grep/cli)
 ---
 
-# ast-grep: Structural Code Search
+# ast-grep: Structural Code Search (sg CLI)
 
-Search code by structure, not text. `sg` uses tree-sitter to parse code into ASTs, then matches patterns against the tree. It understands code semantics — not just string matching.
+Search code by structure, not text. ast-grep parses code into ASTs and matches code shape.
 
-## Install
+**Harness policy:** use the **`sg` shell CLI only**. harness-lens does not expose `ast_grep_search` / `ast_grep_replace` pi tools.
+
+## Install CLI
 
 ```bash
 npm install -g @ast-grep/cli
+sg --version
 ```
 
-Verifies with `sg --version`.
+`/harness-setup` installs global `sg` on the machine. That is a harness dev tool — it does not imply every target repo uses ast-grep rules.
 
 ## When to Use
 
 | Task | Tool | Why |
 |------|------|-----|
-| Find code by structure/pattern | **ast-grep** (`sg`) | AST-aware — knows what is a function call vs a string |
-| Find code by concept/meaning | graphify / `ccc search` | Architecture (graphify) vs implementation chunks (`ccc`) |
-| Find exact literal string | `grep` | Only tool for non-code files or exact byte match |
-| Explore architecture | graphify | Call graph, community detection |
-
-**Rule:** For any code search involving patterns, signatures, or structure — use `sg` first. Reserve `grep` for exact literal strings in non-code files (configs, logs, markdown).
-
-## Pattern Syntax
-
-Patterns match code structure. Write code like you'd write it — `sg` parses it as AST.
-
-### Metavariables
-
-Prefix with `$` to match any expression, type, or identifier:
-
-| Pattern | Matches |
-|---------|---------|
-| `$X` | Any single expression, identifier, or type |
-| `$NAME` | Captures and names the match (use in rewrites) |
-| `...` | Matches zero or more of anything (statements, args, etc.) |
-| `$$...ARGS` | Captures multiple items as a list |
+| Definitions, references, hover/types, symbol navigation | LSP (`lsp_navigation`) | Language server code intelligence |
+| Type/error checks | LSP (`lsp_diagnostics`) | Active diagnostics |
+| Find code by structure/pattern | `sg -p 'pattern'` | AST-aware matching |
+| Safe structural replacement/codemod | `sg --rewrite` | Shape-preserving rewrites |
+| Find code by concept/meaning | graphify / `ccc search` | Architecture vs implementation chunks |
+| Architecture gate at review | Sentrux | Ship/promotion quality |
+| Find exact literal string | `grep` | Non-code, comments, logs, generated text |
 
-### Examples
+## Golden Rules
 
-```
-# Any function call to `fetch` with any arguments
-fetch($ARGS)
-
-# Any function definition named `handle`
-function handle($PARAMS) { ... }
-
-# Any import from `react`
-import $X from 'react'
-
-# Any method call on `console`
-console.$METHOD($ARGS)
-
-# Any try-catch block
-try { ... } catch ($ERR) { ... }
-
-# Any class extending something
-class $NAME extends $BASE { ... }
-```
+1. **Be specific** — `fetchMetrics($ARGS)` or `fetchMetrics($$$ARGS)`, not bare `fetchMetrics`.
+2. **Scope it** — pass a directory or file to `sg` whenever possible.
+3. **Retry once on zero matches** — simplify the pattern; then grep only if still empty.
+4. **Dry-run replacements** — use `--dry-run` before applying rewrites.
+5. **Valid code patterns** — `function $NAME($$$ARGS) { $$$BODY }`, not incomplete fragments.
 
-### Language Specification
-
-`sg` auto-detects language from file extensions. Override explicitly:
+## CLI Quick Reference
 
 ```bash
-sg -p 'pattern' -l ts      # TypeScript
-sg -p 'pattern' -l python  # Python
-sg -p 'pattern' -l go      # Go
-sg -p 'pattern' -l rust    # Rust
-sg -p 'pattern' -l java    # Java
-sg -p 'pattern' -l cpp     # C++
-```
-
-Supported languages: TypeScript, JavaScript, Python, Go, Rust, Java, C, C++, C#, Ruby, Swift, Kotlin, Scala, PHP, HTML, CSS, JSON, YAML, and more (full tree-sitter grammar set).
-
-## Quick Reference
-
-```bash
-# Search by pattern (auto-detects language)
-sg -p 'pattern'
-
-# Search with language explicit
-sg -p 'pattern' -l ts
-
-# Search specific directory
-sg -p 'pattern' src/
-
-# Search with glob filter
-sg -p 'pattern' --include '*.ts'
-
-# Show context lines
-sg -p 'pattern' -A 3    # 3 lines after
-sg -p 'pattern' -B 3    # 3 lines before
-sg -p 'pattern' -C 3    # 3 lines before and after
-
-# List matching files only
-sg -p 'pattern' --json | jq -r '.[].file' | sort -u
-
-# Count matches
-sg -p 'pattern' | wc -l
-
-# Interactive selection (fuzzy picker)
-sg -p 'pattern' --interactive
-```
-
-## Common Patterns
-
-### Find all call sites of a function
-
-```bash
-# Who calls `processPayment`?
-sg -p 'processPayment($ARGS)'
-
-# Who calls `console.log`?
-sg -p 'console.log($ARGS)'
-
-# Who calls any method on `db`?
-sg -p 'db.$METHOD($ARGS)'
-```
-
-### Find function/method definitions
-
-```bash
-# All async function definitions
-sg -p 'async function $NAME($PARAMS) { ... }'
-
-# All method definitions in a class (TS)
-sg -p '$VISIBILITY $NAME($PARAMS) { ... }' -l ts
-
-# All arrow functions assigned to const
-sg -p 'const $NAME = ($PARAMS) => $BODY'
-```
-
-### Find imports
-
-```bash
-# Default import from specific module
-sg -p 'import $X from "lodash"'
-
-# Named imports
-sg -p 'import { $NAMES } from "react"'
-
-# Any import from a module
-sg -p 'import * from "axios"'
-
-# Dynamic imports
-sg -p 'import($MODULE)'
-```
-
-### Find class definitions
-
-```bash
-# All class definitions
-sg -p 'class $NAME { ... }'
-
-# Classes extending a specific base
-sg -p 'class $NAME extends Error { ... }'
-
-# Classes with specific decorator
-sg -p '@$DECORATOR(...) class $NAME { ... }'
-```
-
-### Find specific patterns
-
-```bash
-# All try-catch blocks
-sg -p 'try { ... } catch ($E) { ... }'
-
-# All useEffect calls (React)
-sg -p 'useEffect(() => { ... }, [$DEPS])'
-
-# All await expressions
-sg -p 'await $EXPR'
-
-# All error throws
-sg -p 'throw new $ERR($ARGS)'
-
-# All object destructuring
-sg -p 'const { $PROPS } = $OBJ'
-```
-
-### Find and replace (codemods)
-
-```bash
-# Preview rewrite (dry run)
-sg -p 'oldPattern($X)' --rewrite 'newPattern($X)' --dry-run
-
-# Execute rewrite
-sg -p 'oldPattern($X)' --rewrite 'newPattern($X)'
-
-# Rewrite with language explicit
-sg -p 'console.log($MSG)' --rewrite 'logger.info($MSG)' -l ts
-
-# Rewrite across project using rules (see sgconfig.yml below)
-sg scan
-```
-
-## Project Rules with sgconfig.yml
-
-For project-wide pattern enforcement, create `sgconfig.yml` at project root:
-
-```yaml
-# sgconfig.yml
-ruleDirs:
-  - .sg/rules
-```
-
-Then create rule files in `.sg/rules/`:
-
-```yaml
-# .sg/rules/no-console-log.yml
-id: no-console-log
-language: TypeScript
-severity: warning
-rule:
-  pattern: console.log($ARGS)
-fix: logger.debug($ARGS)
-message: "Use logger.debug instead of console.log"
-```
-
-```yaml
-# .sg/rules/require-await.yml
-id: no-floating-promises
-language: TypeScript
-severity: error
-rule:
-  pattern: $FUNC($ARGS)
-  not:
-    pattern: await $FUNC($ARGS)
-  inside:
-    kind: function_declaration
-    stopBy: end
-message: "Promise returned by $FUNC is not awaited"
-```
-
-```yaml
-# .sg/rules/no-any.yml
-id: no-explicit-any
-language: TypeScript
-severity: warning
-rule:
-  pattern: any
-message: "Avoid using 'any' type — use unknown or a specific type"
-```
-
-Run rules:
-
-```bash
-# Scan all rules in sgconfig.yml
-sg scan
-
-# Scan specific rule
-sg scan --rule .sg/rules/no-console-log.yml
-
-# Scan specific directory
-sg scan src/
-```
-
-### Rule Structure
-
-Every rule file is YAML with these fields:
-
-| Field | Required | Purpose |
-|-------|----------|---------|
-| `id` | Yes | Unique rule identifier (kebab-case) |
-| `language` | Yes | Language to match (TypeScript, Python, Go, etc.) |
-| `severity` | Yes | `error`, `warning`, `hint`, `info` |
-| `rule` | Yes | The pattern to match (supports `pattern`, `not`, `inside`, `has`, `follows`, `all`, `any`) |
-| `message` | Yes | Human-readable explanation |
-| `fix` | No | Rewrite template (uses same metavariables) |
-
-### Composite Rule Matchers
-
-```yaml
-# Match ALL conditions
-rule:
-  all:
-    - pattern: console.log($X)
-    - inside:
-        kind: function_declaration
-
-# Match ANY condition
-rule:
-  any:
-    - pattern: console.log($X)
-    - pattern: console.warn($X)
-
-# Exclude matches
-rule:
-  pattern: fetch($URL)
-  not:
-    pattern: fetch($URL, { init: $INIT })
-
-# Must be inside specific AST node
-rule:
-  pattern: $CALL($ARGS)
-  inside:
-    kind: try_statement
-
-# Must follow another pattern
-rule:
-  pattern: $X.close()
-  follows:
-    pattern: $X.open()
+sg -p 'console.log($$$ARGS)' -l ts src/
+sg -p 'import { $NAMES } from $PATH' -l go
+sg -p 'pattern' --rewrite 'replacement' --dry-run
+sg scan   # only when the target repo defines sg rules (not a harness default)
 ```
 
 ## Search Decision Flow
 
-```
+```text
 Need to find code
-  ├─ Structural pattern (function calls, imports, classes)? → sg -p 'pattern'
-  ├─ Rewrite/codemod needed? → sg -p 'old' --rewrite 'new'
-  ├─ Project-wide lint rule? → sg scan (with sgconfig.yml)
-  ├─ Conceptual/semantic search? → graphify query (architecture) or ccc search (implementation)
-  ├─ Explore architecture? → graphify
-  └─ Exact literal string in non-code? → grep
+  ├─ Definition, references, type, symbol? → lsp_navigation
+  ├─ Diagnostics? → lsp_diagnostics
+  ├─ Structural pattern? → sg -p 'pattern'
+  ├─ Rewrite/codemod? → sg --rewrite
+  ├─ Conceptual search? → graphify query or ccc search
+  ├─ Architecture gate? → Sentrux
+  └─ Exact literal in logs/text? → grep
 ```
 
-## Output Formats
-
-```bash
-# Default (grep-compatible): file:line:column: match
-sg -p 'pattern'
-
-# JSON (for piping/automation)
-sg -p 'pattern' --json
-
-# Only file paths (deduplicated)
-sg -p 'pattern' --json | jq -r '.[].file' | sort -u
-```
-
-## Tips
-
-- **Metavariables are greedy by default.** `$X` matches the smallest valid AST node. Use `$$$X` to match multiple nodes.
-- **`...` matches zero or more.** Inside function body `{ ... }` matches any statements. In call args `fn(...)` matches any number of arguments.
-- **Pattern must be valid code for the target language.** `sg` parses the pattern itself as AST.
-- **Use `--json` for automation.** Parse results programmatically instead of grepping output.
-- **Combine with find for scoped searches.** `find src/ -name '*.ts' -exec sg -p 'pattern' {} +`
-- **Rules compose.** Multiple rules in `sgconfig.yml` run together with `sg scan`.
-
 ## Integration with Pi Workflow
 
-1. **Before grep on code files** — consider if `sg -p` would be more precise.
-2. **After graphify identifies a node** — use `sg` to find all call sites or definitions.
-3. **For refactoring tasks** — use `sg -p ... --rewrite ...` for safe structural rewrites.
-4. **For code review** — run `sg scan` with project rules to catch anti-patterns.
+1. **Graph before grep** — graphify for architecture first.
+2. **LSP before sg for code intelligence** — definitions, references, types.
+3. **sg before grep on code** — structural patterns use AST matching.
+4. **Project rules live in the target repo** — do not assume `.sg/rules/` from harness setup; Sentrux + project linters own gates.
+
+Debug patterns: https://ast-grep.github.io/playground.html

package/.pi/skills/delivery/debugging-discipline/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: debugging-discipline
+description: Debug systematically instead of guessing. Use when fixing bugs, failing tests, flaky behavior, runtime errors, regressions, or unexpected output. Guides reproduction, isolation, hypotheses, evidence, one-variable changes, root cause, and regression tests.
+---
+
+# Debugging Discipline
+
+Use this skill for bug-fix tasks and failing verification.
+
+## Workflow
+
+1. Reproduce or precisely describe the failure.
+2. Capture the expected behavior and actual behavior.
+3. Identify the smallest failing path or input.
+4. Form one hypothesis from evidence.
+5. Inspect code/data/logs that can confirm or reject the hypothesis.
+6. Change one variable at a time.
+7. Fix root cause, not just the visible symptom.
+8. Add a regression test or equivalent guard.
+9. Re-run the failing check and relevant adjacent checks.
+
+## Evidence to collect
+
+- failing assertion or error
+- inputs and state
+- recent changes
+- boundary/edge conditions
+- logs with sensitive data redacted
+- dependency/environment differences
+
+## Avoid
+
+- Random edits before reproduction.
+- Explaining away failures without evidence.
+- Masking errors by broad catch/ignore logic.
+- Declaring fixed without rerunning the failing path.

package/.pi/skills/delivery/documentation-update/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: documentation-update
+description: Update documentation only where it helps future work. Use when behavior, setup, contracts, commands, architecture decisions, operational procedures, or user-facing workflows change. Avoids redundant comments while capturing decisions, invariants, examples, and caveats near the relevant surface.
+---
+
+# Documentation Update
+
+Use this skill when code changes affect how people or agents should use, operate, or maintain the system.
+
+## What to document
+
+- public contracts and compatibility notes
+- behavior changes and examples
+- setup/configuration changes
+- operational caveats and failure modes
+- invariants not obvious from code
+- design decisions and rejected alternatives
+- migration or rollback procedures
+
+## Workflow
+
+1. Identify who needs the documentation: user, maintainer, operator, integrator, or future agent.
+2. Update the nearest authoritative doc rather than creating duplicates.
+3. Keep examples current and minimal.
+4. Remove or correct stale docs when behavior changes.
+5. Prefer comments for local non-obvious why; prefer docs for broader usage or process.
+6. Verify links, commands, and paths when practical.
+
+## Avoid
+
+- Comments that merely restate obvious code.
+- New docs that duplicate existing sources of truth.
+- Documentation promises not enforced by tests or code.

package/.pi/skills/delivery/requirements-to-implementation/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: requirements-to-implementation
+description: Translate vague or high-level requests into safe implementation steps. Use before coding features, bug fixes, refactors, or ambiguous tasks. Extracts requirements, constraints, done criteria, non-goals, risk, and the smallest viable implementation path.
+---
+
+# Requirements to Implementation
+
+Use this skill to prevent solving the wrong problem.
+
+## Workflow
+
+1. Restate the user objective in concrete behavior terms.
+2. Separate explicit requirements from assumptions.
+3. Inspect repo conventions and relevant existing behavior before choosing an approach.
+4. Identify constraints: compatibility, data, security, performance, architecture, tests, and delivery risk.
+5. Define done criteria and non-goals.
+6. Pick the smallest implementation path that satisfies the request.
+7. Ask the user when scope, risk, destructive action, or irreversible behavior is ambiguous.
+
+## Implementation prompt
+
+Before editing, answer:
+
+- What behavior changes?
+- What behavior must not change?
+- Which files/contracts are likely affected?
+- What verification proves completion?
+- What would be overreach?
+
+## Avoid
+
+- Treating examples as exhaustive requirements without checking.
+- Inventing product behavior not requested or present in code.
+- Starting with a broad redesign when a local change suffices.

package/.pi/skills/delivery/risk-based-verification/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: risk-based-verification
+description: Match verification depth to change risk. Use after code, test, config, dependency, data, or docs changes. Helps agents choose targeted checks for low risk, broader checks for medium/high risk, and report unverified residual risk clearly.
+---
+
+# Risk-Based Verification
+
+Use this skill to verify enough without wasting effort or claiming false confidence.
+
+## Risk levels
+
+Low risk:
+- small local change
+- no public contract or data change
+- existing tests cover area
+- reversible
+
+Medium risk:
+- multiple files or boundaries
+- new branch/error path
+- test coverage uncertain
+- behavior visible to users or other modules
+
+High risk:
+- data migration or destructive operation
+- security/privacy/auth change
+- dependency/runtime upgrade
+- concurrency/distributed behavior
+- public contract or compatibility change
+
+## Verification choices
+
+- Low: targeted unit test, focused lint/type/build check, or direct script/example.
+- Medium: affected test suite, integration/contract check, diff review, edge-case tests.
+- High: broad test suite, migration/rollback validation, security review, performance check, manual approval when needed.
+
+## Final report
+
+Always state:
+
+- checks run
+- checks not run
+- why verification is sufficient or what risk remains

package/.pi/skills/delivery/tradeoff-analysis/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: tradeoff-analysis
+description: Make engineering tradeoffs explicit before choosing an implementation. Use when multiple viable approaches exist or when simplicity, maintainability, performance, reliability, compatibility, security, and delivery speed conflict. Chooses the least-worst option with rationale.
+---
+
+# Tradeoff Analysis
+
+Use this skill when there is no single obviously best approach.
+
+## Workflow
+
+1. State the decision to make.
+2. List forces: correctness, simplicity, maintainability, performance, reliability, scalability, security, compatibility, cost, delivery speed, and operability.
+3. Identify two or three realistic options.
+4. Compare each option against the forces and project constraints.
+5. Choose the least-worst option for the current context.
+6. Record why rejected options were not chosen when the decision matters.
+7. Keep the implementation aligned with the chosen tradeoff.
+
+## Output shape
+
+- Decision:
+- Constraints:
+- Options:
+- Chosen approach:
+- Why:
+- Risks:
+- Verification:
+
+## Avoid
+
+- Generic best-practice claims without project context.
+- Optimizing for future scale without evidence.
+- Choosing complexity because it feels more professional.

package/.pi/skills/engineering/api-contract-design/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: api-contract-design
+description: Design stable contracts for modules, services, commands, events, plugins, CLIs, and public interfaces. Use when adding or changing any boundary that other code or people depend on. Focuses on minimal contracts, compatibility, versioning, errors, idempotency, and documentation.
+---
+
+# API and Contract Design
+
+Use this skill for any boundary with callers or consumers.
+
+## Contract elements
+
+Define:
+
+- purpose and owner
+- inputs and validation rules
+- outputs and guarantees
+- error cases
+- idempotency and ordering expectations
+- compatibility/versioning expectations
+- security and privacy constraints
+- observability expectations
+
+## Workflow
+
+1. Identify consumers and their real needs.
+2. Keep the contract smaller than the implementation model.
+3. Separate public contract from internal representation.
+4. Make defaults and optional fields explicit.
+5. Preserve backward compatibility unless a breaking change is approved.
+6. Add contract tests or examples for important cases.
+7. Document semantics near the contract surface.
+
+## Review questions
+
+- Can the implementation change without breaking consumers?
+- Are failure modes part of the contract?
+- Is the contract stable enough to test?
+- Are names domain-specific and unambiguous?

package/.pi/skills/engineering/cohesion-coupling/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: cohesion-coupling
+description: Improve code-level modularity by increasing cohesion and reducing accidental coupling. Use when splitting files/components, moving logic, introducing boundaries, or reviewing dependency direction. Focuses on reason-to-change, dependency minimization, and cognitive load.
+---
+
+# Cohesion and Coupling
+
+Use this skill to make code easier to understand and change.
+
+## Cohesion checks
+
+Keep together code that:
+
+- changes for the same reason
+- enforces the same invariant
+- uses the same domain language
+- participates in the same workflow step
+- shares a stable lifecycle
+
+## Coupling checks
+
+Reduce dependencies that are:
+
+- unnecessary for the caller's purpose
+- pointed from stable code to volatile code
+- created only for convenience
+- transitive through broad utility modules
+- hidden through globals or ambient context
+
+## Workflow
+
+1. Identify the responsibility being changed.
+2. List current dependencies and call direction.
+3. Move behavior toward the concept that owns the rule.
+4. Expose a narrow facade instead of leaking internals.
+5. Remove dependency cycles or document why they cannot be removed now.
+6. Verify call sites still read clearly.
+
+## Avoid
+
+- Splitting code by technical layer when the change is domain-local.
+- Central helper modules that collect unrelated behavior.
+- Abstractions that reduce lines but increase conceptual coupling.