ultimate-pi 0.1.7 → 0.2.2

package/.pi/prompts/harness-trace.md

@@ -0,0 +1,51 @@
+---
+description: Query and summarize harness run traces for replay and forensics.
+argument-hint: "--run <run-id> [--phase plan|execute|evaluate|adversary|merge]"
+---
+
+# harness-trace
+
+Retrieve and summarize trace artifacts for a run.
+
+## Step 0 — Parse arguments
+
+Read `$ARGUMENTS` and parse:
+
+- required: `--run <run-id>`
+- optional: `--phase plan|execute|evaluate|adversary|merge`
+
+If `--run` is missing, stop and return:
+
+`Usage: /harness-trace --run <run-id> [--phase plan|execute|evaluate|adversary|merge]`
+
+## Process
+
+1. Collect run artifacts from canonical harness locations and provided trace refs.
+2. Build phase timeline with policy and gate decision points.
+3. Report completeness gaps against strict gate artifact requirements.
+
+## Requirements
+
+- Use `.pi/harness/runs/` and external trace references as source of truth pointers.
+- Include phase timeline, artifact refs, and policy decisions.
+- Highlight missing artifacts that violate strict gate requirements.
+
+## Guardrails
+
+- Do not overthink simple trace lookups; prioritize completeness and stable references.
+- Only report artifacts for the requested run and optional phase filter.
+- Never infer artifact existence without verifying source pointers.
+
+## Output
+
+- Replay-ready timeline summary.
+- Artifact index (`plan`, `run`, `eval`, `adversary`, `consensus`, `incident`, `rollback`).
+- Any integrity or completeness gaps.
+
+## Completion behavior
+
+Always end with:
+
+- `trace_completeness` (`complete` or `incomplete`)
+- missing artifact checklist (if any)
+- most likely next command (`/harness-incident`, `/harness-review`, or `/harness-critic`)

package/.pi/prompts/wiki-autoresearch.md

@@ -1,5 +1,5 @@
 ---
-description: Run an autonomous research loop on a topic. Searches the web, synthesizes findings, and files everything into the wiki as structured pages.
+description: Run an autonomous research loop on a topic. Searches the web, synthesizes findings, and builds a knowledge graph via Graphify.
 argument-hint: "[topic]"
 ---
 
@@ -10,10 +10,12 @@ Invocation arguments:
 - If `$ARGUMENTS` is non-empty: treat it as explicit topic and use it verbatim.
 - If `$ARGUMENTS` is empty: ask exactly "What topic should I research?"
 
-Before starting, read `skills/wiki-autoresearch/references/program.md` to load the research constraints and objectives.
+Before starting:
+1. Read `skills/wiki-autoresearch/references/program.md` for research constraints.
+2. Ensure `./raw/` directory exists for source storage.
+3. Ensure Graphify is installed (`pip show graphifyy`).
 
-If no vault is set up yet, say: "No wiki vault found. Run /wiki first to set one up."
-
-After research is complete, update wiki/index.md, wiki/log.md, and wiki/hot.md.
-
-Report how many pages were created and what the key findings are.
+After research is complete:
+1. Run `graphify ./raw --wiki --mode deep` to build the knowledge graph
+2. Cleanup: remove `./raw/` since graphify has already ingested all data
+3. Report: rounds, sources, graph nodes/edges, god nodes, surprising connections

package/.pi/prompts/wiki-save.md

@@ -0,0 +1,20 @@
+---
+description: Save the current conversation or a specific insight as a structured note in the knowledge graph.
+---
+
+Read the `graphify` skill for context on graphify-out/ structure.
+
+Save the current conversation or requested insight as a markdown file in `./raw/`
+so it can be graphified and queried. Then run `graphify ./raw --update` to
+incorporate it into the knowledge graph.
+
+Usage:
+- `/save` — analyze the full conversation and save the most valuable content
+- `/save [name]` — save with a specific note title
+- `/save session` — save a complete session summary
+- `/save decision [name]` — save as a design/governance decision (also mirror into `.pi/harness/incidents/` when incident tracking is required)
+
+Save to: `./raw/[sanitized-name].md`
+Then: `graphify ./raw --update`
+
+If Graphify is not installed, say: "Graphify not installed. Run: pip install graphifyy && graphify install"

package/.pi/skills/agent-router/SKILL.md

@@ -66,8 +66,8 @@ to re-read frontmatter for already-profiled agents.
 | "create an agent" | Agent-related keywords in description |
 | "Pi extension" / "Pi theme" | Pi component domain keywords |
 | "rethink" / "first principles" | Prioritization keywords |
-| "ingest to wiki" | Wiki ingestion keywords |
-| "lint the wiki" | Wiki lint keywords |
+| "build knowledge graph" | Graphify keywords |
+| "query the graph" | Graphify queries |
 
 ### Fuzzy Match — Semantic Fit
 
@@ -158,8 +158,6 @@ $ find .pi/agents -name '*.md' -type f
 # .pi/agents/pi-pi/agent-expert.md
 # .pi/agents/pi-pi/skill-expert.md
 # .pi/agents/rethink.md
-# .pi/agents/wiki-ingest.md
-# .pi/agents/wiki-lint.md
 
 # Then read each to understand capabilities
 # Then match user task to the right agent(s)

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

@@ -0,0 +1,354 @@
+---
+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."
+allowed-tools:
+  - Bash(sg *)
+  - Bash(npm install -g @ast-grep/cli)
+---
+
+# ast-grep: Structural Code Search
+
+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.
+
+## Install
+
+```bash
+npm install -g @ast-grep/cli
+```
+
+Verifies with `sg --version`.
+
+## 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 / ck | Semantic search, knowledge graph |
+| 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 |
+
+### Examples
+
+```
+# 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 { ... }
+```
+
+### Language Specification
+
+`sg` auto-detects language from file extensions. Override explicitly:
+
+```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()
+```
+
+## Search Decision Flow
+
+```
+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 or ck --hybrid
+  ├─ Explore architecture? → graphify
+  └─ Exact literal string in non-code? → 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.

package/.pi/sounds/project-sounds.json

@@ -1,25 +1,19 @@
 {
-    "themeName": "ultimate-pi-custom",
-    "randomizeSounds": true,
-    "sounds": {
-        "success": [
-            "success/1-tada-track.mp3",
-            "success/2-jobs-done-track.mp3",
-            "success/3-yay-track.mp3"
-        ],
-        "error": [
-            "error/1-ksi-wth-track.mp3",
-            "error/2-smash-track.mp3",
-            "error/3-buzzer-track.mp3"
-        ],
-        "alert": [
-            "alert/1-kaching-track.mp3"
-        ],
-        "notification": [
-            "notification/1-soft-notification-track.mp3"
-        ],
-        "reminder": [
-            "reminder/1-soft-notification-track.mp3"
-        ]
-    }
-}
+	"themeName": "ultimate-pi-custom",
+	"randomizeSounds": true,
+	"sounds": {
+		"success": [
+			"success/1-tada-track.mp3",
+			"success/2-jobs-done-track.mp3",
+			"success/3-yay-track.mp3"
+		],
+		"error": [
+			"error/1-ksi-wth-track.mp3",
+			"error/2-smash-track.mp3",
+			"error/3-buzzer-track.mp3"
+		],
+		"alert": ["alert/1-kaching-track.mp3"],
+		"notification": ["notification/1-soft-notification-track.mp3"],
+		"reminder": ["reminder/1-soft-notification-track.mp3"]
+	}
+}

package/AGENTS.md

@@ -0,0 +1,30 @@
+# ultimate-pi: Agentic Harness
+
+Purpose: Agentic coding harness — architecture, research, decisions, implementation.
+Owner: pi-mono + user
+Created: 2026-05-14
+
+## Structure
+
+- graphify-out/ → Knowledge graph (run `graphify update .` to build)
+- ./raw/ → Source documents for graphify ingestion
+- docs/adr/ → Architectural Decision Records
+- .pi/skills/ → Agent skills
+- .pi/agents/ → Specialized agents
+
+## Graphify-First Workflow
+
+1. Run `graphify update .` to build/update the knowledge graph
+2. Read `graphify-out/GRAPH_REPORT.md` for god nodes and surprising connections
+3. Query: `graphify query "question"`
+4. Explain: `graphify explain "Concept"` for caller/callee traces
+5. ADRs stored in `docs/adr/`
+
+## Conventions
+
+- Graph before grep — always consult the knowledge graph first
+- ./raw/ is source storage for graphify
+- ADRs in docs/adr/ with structured format
+- `graphify update .` after significant code changes
+- ast-grep (`sg`) is the default code search tool — use `sg -p 'pattern'` for structural search, never grep for code
+- Self-hosted Firecrawl at http://localhost:3002 (FIRECRAWL_API_URL)

package/CHANGELOG.md

@@ -2,6 +2,95 @@
 
 All notable changes to this project are documented in this file.
 
+## [v0.2.2] — 2026-05-15
+
+### 🔧 Chores
+
+- trim npm bundle and declare bundled deps
+- refresh generated artifacts
+
+## [v0.2.1] — 2026-05-15
+
+### 🐛 Fixes
+
+- default to flow mode and soften budget gates
+
+### 🔧 Chores
+
+- sync generated report and graph artifacts
+- refresh rebuild lock metadata
+- update install instructions and refresh graph artifacts
+
+## [v0.2.0] — 2026-05-15
+
+### ✨ Features
+
+- update extension banner and custom header
+- add abort flow and safer live widget rendering
+- add orchestration stack and banner compatibility
+- router-aware custom footer with profile colors
+- gitignore model-router.json and generate dynamically from env
+- merge books & YT corpora, add merge scripts, up viz cap to 200K
+- add research papers and graphify knowledge graph outputs
+- add skill and rebuild knowledge graph
+- ingest Gleeson Musk first-principles prompts thread
+- add books corpus knowledge graph with cross-book linking
+- integrate ast-grep as primary code search tool
+- add sentrux architectural quality gate integration
+
+### 🐛 Fixes
+
+- consolidate outputs into graphify-out/, prevent root duplication
+- add --ignore-scripts to npm publish in GitHub Packages workflow
+
+### ♻️ Refactoring
+
+- migrate from Obsidian wiki to Graphify knowledge graph
+
+### 📖 Documentation
+
+- add beginner-friendly harness user guide
+- label all 428 communities, regenerate report and HTML
+
+### 🎨 Style
+
+- apply linter formatting (tab indent)
+
+### 🔧 Chores
+
+- refresh generated graph artifacts
+- align graphify skill source to project-local path
+- include latest post-commit graph rebuild outputs
+- refresh generated graph and harness run artifacts
+- remove redundant internal code
+- refresh generated graph artifacts
+- remove rethink agent, add youtube video catalog
+- index NEA × Namespace CI/CD / continuous compute YouTube talk
+- remove graphify-books-corpus aigleeson musk prompts markdown file
+- rename data/yt-vid to data/youtube-transcripts
+- align graphify outputs with data/books corpus paths
+- add data/ corpus: books (Git LFS) and yt-vid transcripts
+- add reusable YouTube transcript indexer (yt-dlp + Firecrawl CLI)
+- re-format includes array as multi-line
+- exclude graphify-books-out/ from lint/format
+- accept remote graphify-out artifacts, remove cache/ from tracking (gitignored)
+- add graphify-out/cache/ to .gitignore
+- update wiki docs
+- update wiki docs
+- update wiki docs
+- update wiki docs
+- update wiki docs
+- update wiki docs
+- update wiki docs
+- update wiki docs
+- update wiki docs
+- update wiki docs
+- fix biome ignore pattern: !graphify-out
+- ignore graphify-out from biome lint
+- update knowledge graph caches after background rebuild
+- remove wiki skills superseded by graphify
+- remove defuddle-cli and defuddle skill references (firecrawl covers same)
+
 ## [v0.1.7] — 2026-05-07
 
 ### ✨ Features