pi-dev-team 0.2.0

package/skills/semantic-duplication-scan/SKILL.md

@@ -0,0 +1,337 @@
+---
+name: semantic-duplication-scan
+description: >-
+  Detect business logic reimplemented in multiple architectural layers. Builds a
+  persistent computation-register.json by annotating non-trivial computation
+  functions with structured semantic descriptions, then clusters entries to
+  surface duplicate domain concepts. Runs in full-scan mode on first use,
+  incremental (git-diff-based) mode on subsequent runs. Use when the user wants
+  to find logical duplication that linters and diff-scoped review agents miss —
+  the same domain calculation independently reimplemented across layers.
+role: worker
+user-invocable: true
+---
+
+# Semantic Duplication Scan
+
+## Overview
+
+Detect business logic that has been reimplemented multiple times across different architectural layers. Unlike linters (which detect syntactic similarity) or `domain-review` (which catches single-instance layer violations), this skill detects semantic equivalence — the same domain calculation independently appearing in domain services, client adapters, and presentation components with different variable names and structure.
+
+## Annotation Prompt Version
+
+**promptVersion**: `1.0`
+
+When this version changes, any register entry with a different `promptVersion` is treated as stale and re-annotated on the next scan pass that touches that file.
+
+---
+
+## Pre-Filter Rules
+
+**Apply before any LLM call. No model invocation at this stage.**
+
+### Trivial Function Definition
+
+A function is **trivial** — and must be excluded from the register — if it meets ALL of the following:
+
+- Contains **no arithmetic operators**: `+`, `-`, `*`, `/`, `%`, `**`
+- Contains **no boolean logic operators**: `&&`, `||`, `!`, `not`, `and`, `or`
+- Contains **no branching constructs**: `if`, `else`, `switch`, `case`, `ternary` (`?:`), `match`
+- Contains **no assignments to variables outside its own scope** (no external state mutation)
+- Contains **no calls to higher-order collection operations**: `map`, `filter`, `reduce`, `flatMap`, `forEach`, `find`, `some`, `every`, or language equivalents
+
+Trivial patterns (always excluded):
+- Getters: read and return a field with no transformation
+- Pass-through delegators: call one function with the same arguments, return the result unchanged
+- Identity functions: return the input unchanged
+- Constructors / initializers that only assign parameters to instance fields
+
+If a file contains **only trivial functions**, output:
+
+```
+No computation units found to analyze
+```
+
+and do not create or modify the register.
+
+### File Exclusion Patterns
+
+Exclude the following from annotation regardless of content:
+
+```
+*.test.*
+*.spec.*
+__tests__/
+*.test-d.*
+*.generated.*
+*.pb.*
+*.d.ts
+dist/
+build/
+.next/
+coverage/
+```
+
+Also exclude any path matching a pattern listed in `.semanticscanignore` (one glob per line) if that file exists in the project root.
+
+---
+
+## Process Flow
+
+### Step 1 — Mode Detection
+
+Check for `computation-register.json` in the project root:
+- **Absent** → full-scan mode
+- **Present** → incremental mode
+
+### Step 2 — Pre-Flight (Incremental Mode Only)
+
+Run: `git rev-parse --is-shallow-repository`
+
+If output is `true`:
+- Output the exact string: `Shallow clone detected — semantic-scan requires full history for incremental mode. Run with --full to override.`
+- Exit non-zero
+
+If `--full` flag was passed: skip this check and force full-scan mode.
+
+If `lastScanCommit` in the register is not found in git history:
+- Output: `lastScanCommit not found in history — running full scan`
+- Switch to full-scan mode
+
+### Step 3 — Scope Resolution
+
+1. If a path argument was provided (e.g., `/semantic-scan src/pricing`), use it as a prefix filter: only consider files whose paths start with the argument
+2. Apply `.semanticscanignore` patterns: exclude any file matching a listed glob
+3. Apply file exclusion patterns from the Pre-Filter Rules above
+
+### Step 4 — File Selection
+
+**Full-scan mode**: Glob all source files in the resolved scope.
+
+**Incremental mode**: Run `git diff <lastScanCommit> HEAD --name-only`, then filter to files in the resolved scope.
+
+If the git diff result is empty (no files changed since `lastScanCommit`):
+1. Update `lastScanCommit` to HEAD in the register and write the updated register
+2. Output: `No changes since last scan — register up to date`
+3. Exit 0 — do not proceed to annotation or clustering
+
+**Graph-assisted file/function discovery.** Prefer CodeGraph/Repowise over raw
+`Glob`/`Read` for locating candidate computation functions across layers —
+Repowise's semantic search (`search_codebase`) is particularly well suited
+here, since it's built for exactly the kind of similarity search this skill
+needs to find the same domain concept reimplemented in different layers. See
+[`knowledge/codegraph-vs-graphify.md`](../../knowledge/codegraph-vs-graphify.md)
+for tool selection and the fallback contract.
+
+### Step 5 — Pre-Filter
+
+For each selected file, identify non-trivial computation functions using the Trivial Function Definition above. Apply without an LLM call — use structural heuristics (presence of operators, branches, higher-order calls).
+
+If no non-trivial functions remain after filtering:
+
+- **First run**: `No computation units found to analyze` → exit 0, no register created
+- **Incremental run**: `No new computation units found in changed files — register unchanged` → exit 0, register not modified
+
+### Step 6 — Annotation (Haiku, file-level batching)
+
+For each file with non-trivial functions:
+
+1. Emit progress to stderr: `Annotating [N/total] <filename>`
+2. Send all non-trivial functions from the file in a single Haiku call using the pinned prompt below
+3. If the call fails, record `{file, error}` in `scanErrors` and continue — do not abort
+
+**Annotation prompt (pinned — do not paraphrase):**
+
+```
+You are a semantic annotation assistant. For each function below, produce a JSON object describing what it computes in pure domain business terms.
+
+Use this schema:
+{
+  "function": "<function name>",
+  "layer": "<inferred layer — see rules below>",
+  "semanticDescription": {
+    "verb": "<lowercase infinitive verb>",
+    "domainConcept": "<lowercase, no articles, normalized>",
+    "inputs": ["<domain term>", ...],
+    "outputConcept": "<domain term>"
+  }
+}
+
+Layer inference rules — infer from what the function imports and uses:
+- "infrastructure": imports DB clients, ORMs, HTTP clients, message brokers (pg, redis, axios, fetch, prisma, mongoose, etc.)
+- "presentation": imports rendering primitives, formats for display, accesses DOM or templates (React, Vue, Svelte, JSX, HTML templates, etc.)
+- "domain": depends only on domain types and pure functions, no external imports
+- "application": orchestrates domain and infrastructure without owning business rules
+- "unknown": cannot be determined from available context
+
+domainConcept rules:
+- Use lowercase
+- Remove articles: a, an, the
+- Normalize the verb to infinitive form
+- Example: "calculates the discounted price" → domainConcept: "discounted price", verb: "calculate"
+
+Describe only what the function computes in domain terms. Do not reference the implementation language, variable names, or data structure types.
+
+Functions:
+<paste function source here>
+```
+
+**Canonicalize `domainConcept` after receiving the response:**
+1. Lowercase
+2. Strip leading/trailing articles: `a `, `an `, `the `
+3. Normalize verb in the `verb` field to infinitive (e.g., "calculates" → "calculate", "computing" → "compute")
+
+### Step 7 — Register Update
+
+Build a register entry for each annotated function:
+
+```json
+{
+  "file": "<relative path from project root>",
+  "function": "<function name>",
+  "layer": "<inferred layer>",
+  "semanticDescription": {
+    "verb": "<canonicalized>",
+    "domainConcept": "<canonicalized>",
+    "inputs": ["<domain term>", ...],
+    "outputConcept": "<domain term>"
+  },
+  "promptVersion": "1.0",
+  "commitHash": "<HEAD commit hash>",
+  "line": <first line of function definition>
+}
+```
+
+**Merge strategy:**
+- Replace all entries whose `file` matches a re-annotated file
+- Remove entries whose `file` no longer exists on disk
+- Remove entries for files matching `.semanticscanignore` patterns
+- Preserve all other entries unchanged
+
+**Idempotency:** Sort the full entry list by `file` ascending, then `function` ascending before writing.
+
+**Write the register.** If the write fails (permissions, disk full):
+- Output the exact path that could not be written and the OS error
+- Exit non-zero
+
+**Update `lastScanCommit`** to the current HEAD commit hash after successful write.
+
+**Report partial failures.** After writing (only if `scanErrors` is non-empty):
+- N=1: `Warning: 1 file could not be annotated. Re-run /semantic-scan to retry.`
+- N>1: `Warning: N files could not be annotated. Re-run /semantic-scan to retry.`
+
+Exit code 0 — partial success is not a failure.
+
+---
+
+## Clustering
+
+### Token Budget and Partitioning
+
+The full register may be too large to cluster in a single call. Use layer-pair sharding:
+
+Shard the register by layer pair before sending to Sonnet:
+- `domain × presentation`
+- `domain × infrastructure`
+- `application × presentation`
+- `application × infrastructure`
+- `domain × application`
+
+For each shard: if the shard exceeds **50,000 tokens**, further shard by the first normalized token of `domainConcept` (split alphabetically into sub-groups).
+
+After per-shard clustering, run a **cross-shard reconciliation pass**: send only the cluster representatives (one entry per cluster, the top-ranked candidate) back to Sonnet to catch equivalents that landed in different shards. Keep this merge input under 50,000 tokens.
+
+### Clustering Call (Sonnet)
+
+For each shard, emit progress: `Clustering [layer-pair]: <layer-a> × <layer-b>...`
+
+**Clustering prompt (pinned — do not paraphrase):**
+
+```
+Group these register entries by semantic equivalence — entries that compute the same domain concept regardless of implementation differences. Return clusters as JSON arrays of entry IDs (use "file:function" as the ID).
+
+Two entries belong in the same cluster ONLY IF both would need to change if the underlying business rule changed.
+
+Input entries:
+<paste shard entries as JSON array>
+
+Return only:
+{ "clusters": [["file1:funcA", "file2:funcB"], ...] }
+
+Entries that are semantically unique should not appear in any cluster.
+```
+
+---
+
+## Canonical Scoring
+
+For each cluster with 2 or more entries:
+
+**Layer rank** (higher = more canonical):
+1. `domain`
+2. `application`
+3. `presentation`
+4. `infrastructure`
+5. `unknown`
+
+**Within the same layer rank:** count infrastructure imports in the function's file; fewer imports = higher rank.
+
+**Ambiguity predicate:** If the top two candidates tie on layer rank AND differ by ≤1 infrastructure import → escalate to Opus.
+
+Before the Opus call, emit: `Resolving ambiguous canonical for cluster: <domainConcept>...`
+
+**Opus prompt:**
+
+```
+Given these N entries that all compute the same domain concept, which one is the most appropriate canonical location for the business rule? Consider: domain purity, reusability, and least coupling to delivery mechanism. Return the file:function ID of the preferred canonical and a one-sentence rationale.
+
+Entries:
+<paste cluster entries>
+```
+
+If `--no-opus` flag was passed: skip Opus escalation. Report ambiguous clusters as:
+```
+canonical: ambiguous — human review required
+```
+
+### Canonical Verdict Output
+
+- Clear winner (domain or application layer, no tie): `canonical: suggested <file:line> — requires human confirmation`
+- No winner (all infrastructure/unknown, or tie unresolved): `canonical: none — a new domain-layer implementation may be required`
+
+**Cross-scope notice** (scoped runs only): If a cluster contains entries outside the scoped path:
+```
+Note: this cluster includes <N> entry/entries outside the scoped path — run without scope argument to see full context
+```
+(Use "entry" when N=1, "entries" when N>1.)
+
+---
+
+## Report
+
+After clustering is complete:
+
+**Duplicates found:**
+
+```
+## Semantic Duplication Report
+
+### Cluster: <domainConcept>
+
+  - <file>:<line> [<layer>]  ← inferred canonical (or all entries if no canonical)
+  - <file>:<line> [<layer>]
+
+  canonical: suggested <file:line> — requires human confirmation
+  [Note: this cluster includes N entry/entries outside the scoped path ...]
+
+---
+```
+
+**No duplicates:**
+
+```
+No semantic duplication detected
+```
+
+**`file:line` accuracy:** Line numbers point to the first line of the function definition. If the file has been modified since annotation, append: `(line may have shifted — re-run scan to refresh)`
+

package/skills/semantic-scan/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: semantic-scan
+description: >-
+  Build a computation register and detect semantic duplicates across architectural
+  layers. Finds business logic reimplemented multiple times in different layers —
+  the same domain calculation independently appearing in domain services, client
+  adapters, and presentation components. Runs incrementally (git-diff-based) after
+  the first scan. Produces a structured duplicate report with file:line references
+  and canonical location suggestions.
+argument-hint: "[path] [--full] [--no-opus]"
+user-invocable: true
+---
+
+# Semantic Scan
+
+Role: worker.
+
+## Worker constraints
+
+1. Detect and report duplicates; do not refactor.
+2. Run incrementally (git-diff based) after the first scan.
+3. **Be concise.** Report the duplicate table with file:line refs, no narration.
+
+## Steps
+
+### 1. Parse arguments
+
+Capture the optional path and flags from `$ARGUMENTS`.
+
+### 2. Delegate
+
+Invoke the semantic-duplication-scan skill.
+
+**Graph-assisted discovery.** Prefer CodeGraph/Repowise over raw `Grep`/`Read`
+when locating and comparing candidate implementations — Repowise's semantic
+search is especially well suited to finding duplicate implementations across
+layers. See
+[`knowledge/codegraph-vs-graphify.md`](../../knowledge/codegraph-vs-graphify.md)
+for tool selection and the fallback contract.
+
+### 3. Report
+
+Output the duplicate report.
+
+Apply the guidelines defined in skills/semantic-duplication-scan/SKILL.md to the current task. Read the skill file and follow its process flow, pre-filter rules, annotation procedure, clustering strategy, and report format.
+
+## Flags
+
+- `[path]` — Optional subdirectory to scope the scan. Only files under this path are re-annotated; out-of-scope register entries are preserved.
+- `--full` — Force full-scan mode regardless of whether a register exists. Bypasses the shallow-clone pre-flight check. Use when `lastScanCommit` is stale or after a major restructuring.
+- `--no-opus` — Skip Opus canonical resolution for ambiguous clusters. Ambiguous clusters are reported as `canonical: ambiguous — human review required` instead of triggering an Opus call. Use in cost-sensitive environments (CI, personal accounts).
+
+Apply this skill to: $ARGUMENTS

package/skills/semgrep-analyze/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: semgrep-analyze
+description: >-
+  Run Semgrep static analysis on target files and return structured
+  findings. Use this when the user wants static analysis, SAST scanning, or
+  security scanning — phrases like "run semgrep", "scan for
+  vulnerabilities", "static analysis on this code", or as a pre-review gate
+  when security findings are needed before AI agents run.
+argument-hint: "[path] [--rules <ruleset>]"
+user-invocable: true
+allowed-tools: Read, Grep, Glob, Bash(semgrep *)
+---
+
+# Semgrep Analyze
+
+Role: worker. This skill runs Semgrep and reports findings — it does
+not fix code.
+
+You have been invoked with the `/semgrep-analyze` skill. Run a Semgrep
+scan and return structured findings.
+
+## Constraints
+
+1. **Do not modify code.** Report findings only.
+2. **Return structured JSON.** Output must match the output format below.
+3. **Be concise.** No preambles, narration, or filler text.
+
+## Parse Arguments
+
+Arguments: $ARGUMENTS
+
+- `path`: Directory or file to scan (default: current working
+  directory)
+- `--rules <ruleset>`: Semgrep ruleset (default: `auto`)
+- `--programmatic`: Return structured JSON only, with no prose or
+  status messages. Designed for callers like the static analysis
+  pre-pass in `/code-review`. When set, skip installation guidance
+  on failure — just return the skip status JSON.
+
+Examples:
+
+```text
+/semgrep-analyze
+/semgrep-analyze src/
+/semgrep-analyze --rules p/security-audit
+/semgrep-analyze src/utils --rules p/javascript
+/semgrep-analyze --programmatic src/
+```
+
+## Steps
+
+### 1. Check Semgrep installation
+
+```bash
+semgrep --version
+```
+
+If not installed, output:
+
+```json
+{"status": "skip", "issues": [], "summary": "semgrep not installed — install via pip install semgrep, pipx install semgrep, or brew install semgrep"}
+```
+
+If `--programmatic` is set, return the JSON above and stop — do not
+add installation guidance or prose.
+
+Otherwise (human-facing run), also tell the user: **Run `/project-init` to set
+up this repo's tooling as the one-stop entry point — it installs semgrep as a
+capability tool (see its `${CLAUDE_PLUGIN_ROOT}/skills/project-init/references/capability-tools.md`) — or install semgrep
+directly — `pip install semgrep` (also `pipx install semgrep` or `brew install
+semgrep`).** (The direct install command is the fallback.)
+
+Stop.
+
+### 2. Run Semgrep scan
+
+```bash
+semgrep scan --config <ruleset> --quiet --json <path>
+```
+
+Default ruleset is `auto`. Default path is `.`.
+
+### 3. Parse results
+
+Map each Semgrep finding to an issue:
+
+| Semgrep field        | Output field        |
+| -------------------- | ------------------- |
+| `check_id`           | `ruleId`            |
+| `extra.severity`     | `severity`          |
+| `path`               | `file`              |
+| `start.line`         | `line`              |
+| `extra.message`      | `message`           |
+| `extra.metadata.cwe` | `cwe` (if present)  |
+
+Severity mapping:
+
+| Semgrep severity | Output severity |
+| ---------------- | --------------- |
+| ERROR            | error           |
+| WARNING          | warning         |
+| INFO             | suggestion      |
+
+### 4. Output JSON
+
+```json
+{
+  "status": "pass|warn|fail",
+  "issues": [
+    {
+      "severity": "error|warning|suggestion",
+      "file": "<path>",
+      "line": 0,
+      "ruleId": "<check_id>",
+      "message": "<description>",
+      "cwe": "<CWE-ID>",
+      "suggestedFix": "<fix>"
+    }
+  ],
+  "summary": "<N findings: N errors, N warnings, N suggestions>"
+}
+```
+
+Status: `fail` if any errors, `warn` if warnings but no errors,
+`pass` if clean.
+
+## Common Rulesets
+
+| Ruleset            | Description                                 |
+| ------------------ | ------------------------------------------- |
+| `auto`             | Auto-detect language, use recommended rules |
+| `p/javascript`     | JavaScript-specific rules                   |
+| `p/typescript`     | TypeScript-specific rules                   |
+| `p/react`          | React-specific rules                        |
+| `p/nodejs`         | Node.js security rules                      |
+| `p/security-audit` | General security audit                      |
+| `p/owasp-top-ten`  | OWASP Top 10 vulnerabilities                |
+| `p/ci`             | Rules suitable for CI/CD                    |
+| `p/default`        | Semgrep default ruleset                     |