ultimate-pi 0.18.0 → 0.19.0

package/.pi/skills/architecture/service-mesh/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: service-mesh
+description: "Use when applying the service mesh pattern to service architectures: move cross-cutting network concerns such as retries, mTLS, routing, observability, policy, and traffic shaping out of service code while preserving domain ownership."
+---
+
+# Service Mesh Pattern
+
+Use this skill when cross-service networking concerns are polluting service code or need centralized policy.
+
+## Fit
+
+Use with multiple networked services that need consistent traffic policy, mTLS, observability, retries, or progressive delivery.
+Avoid for small systems where a mesh would add platform complexity without clear benefit.
+
+## Agent Workflow
+
+1. Read `graphify-out/GRAPH_REPORT.md`.
+2. Run `graphify query "service mesh pattern microservices network policy observability"`.
+3. Identify cross-cutting network behavior embedded in services.
+4. Decide what belongs in mesh/platform versus application code.
+5. Remove one cross-cutting concern from service code safely.
+6. Add tests/config checks for equivalent behavior.
+
+## Target Shape
+
+```text
+services/<service>/code/     # domain/application code without mesh vendor logic
+platform/mesh/
+  policies/
+  routes/
+  telemetry/
+  security/
+```
+
+## Implementation Rules
+
+- Service code owns business behavior, data, and explicit dependency calls.
+- Mesh/platform owns mTLS, traffic routing, retries where safe, timeouts, telemetry, and policy.
+- Do not hide business retries or non-idempotent compensation in mesh config.
+- Timeout and retry budgets must align with application semantics.
+- Mesh config is versioned, reviewed, and tested like code.
+
+## Migration Steps
+
+1. Inventory duplicated network concerns in services.
+2. Pick one safe concern such as telemetry headers or mTLS policy.
+3. Add mesh/platform config with rollout guardrails.
+4. Remove redundant service code.
+5. Validate runtime behavior in tests or staging.
+6. Document ownership and rollback.
+
+## Verification
+
+- Use graphify to confirm service modules no longer depend on platform/mesh internals.
+- Test timeout/retry behavior for idempotent and non-idempotent calls.
+- Validate telemetry, route, and security policies with existing platform checks.
+
+## Output Contract
+
+Return: concern inventory, mesh/app ownership split, config/code patch, rollout plan, verification, and operational risks.

package/.pi/skills/architecture/space-based/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: space-based
+description: "Use when implementing space-based architecture: horizontally scalable processing units, in-memory/distributed state, partitioning, eventual persistence, backpressure, replication, and operational safeguards for high-volume systems."
+---
+
+# Space-Based Architecture
+
+Use this skill for systems where database bottlenecks and burst traffic dominate the design.
+
+## Fit
+
+Use for high-volume, bursty, low-latency workloads needing horizontal scaling and elastic processing.
+Avoid for ordinary CRUD systems; this pattern adds serious operational complexity.
+
+## Agent Workflow
+
+1. Read `graphify-out/GRAPH_REPORT.md`.
+2. Run `graphify query "space-based architecture processing units partitioning replication"`.
+3. Identify the scalability bottleneck and partition key.
+4. Isolate processing unit logic from persistence.
+5. Make state ownership, replication, and recovery explicit.
+6. Add load, failover, and backpressure checks.
+
+## Target Shape
+
+```text
+codebase/space/
+  processing-unit/    # stateless-ish compute plus owned partition state
+  partitioning        # keying and routing
+  state-store         # distributed/in-memory state port
+  persistence-sync    # async persistence/replication
+```
+
+## Implementation Rules
+
+- Choose a stable partition key before code changes.
+- Processing units own only their partition's hot state.
+- Persistence is asynchronous where possible; consistency must be stated.
+- Backpressure, retries, and overload behavior are part of the architecture.
+- Recovery must rebuild state from durable sources or snapshots.
+- Do not introduce distributed cache/state without observability.
+
+## Migration Steps
+
+1. Measure or identify the bottleneck.
+2. Extract hot-path processing into a processing-unit boundary.
+3. Add a state-store port with one implementation.
+4. Route requests/events by partition key.
+5. Add async persistence or snapshot/replay.
+6. Add load and failover tests around the boundary.
+
+## Verification
+
+- Use graphify to confirm hot path does not synchronously depend on the old bottleneck.
+- Test partition routing, duplicate processing, restart recovery, and overloaded dependencies.
+- Record latency/throughput assumptions in an ADR.
+
+## Output Contract
+
+Return: bottleneck, partition key, processing-unit patch, state/recovery model, verification, and operational risks.

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