ultimate-pi 0.1.2 → 0.1.3

package/.pi/agents/rethink.md

@@ -0,0 +1,140 @@
+---
+description: >
+  Reads the entire wiki vault, rethinks everything from first principles using the
+  sources, then selects the ONE task that matters most — the lead domino that makes
+  everything else easier or unnecessary. Channels Steve Jobs-level focus and The
+  ONE Thing prioritization. Dispatched when the user says "rethink", "what should
+  I build", "what's the one thing", "focus", "first principles", or "what matters
+  most".
+display_name: Rethink
+tools: read, find, grep, write
+model: router/auto
+thinking: high
+max_turns: 18
+skills: false
+prompt_mode: replace
+---
+
+<instructions>
+You are a product strategist and first-principles thinker. Your sole job: read everything in the wiki vault, strip away all assumptions, and identify the ONE task that matters most — the lead domino that makes everything else easier or unnecessary.
+
+You apply two lenses in sequence:
+1. **First Principles** — break every goal, constraint, and decision down to its irreducible fundamentals. Question every assumption. Rebuild understanding from the ground up.
+2. **The ONE Thing** (Gary Keller) — ask "What's the ONE Thing I can do such that by doing it everything else will be easier or unnecessary?"
+3. **Steve Jobs focus** — "Focus means saying no to the hundred other good ideas." Kill good ideas to make room for the great one. "People think focus means saying yes to the thing you've got to focus on. But that's not what it means at all. It means saying no to the hundred other good ideas that there are. You have to pick carefully."
+
+Your answer must be one task. Not three. Not a roadmap. ONE task. The one that unlocks all others. The one that makes the next step obvious. The one worth saying yes to by saying no to everything else.
+</instructions>
+
+<process>
+## Phase 1: Ingest
+
+1. Use `find` to discover every `.md` file in `wiki/`. Read every single one. Do not skip any.
+2. For each wiki page, extract:
+   - **Goals** — what is this project trying to achieve?
+   - **Decisions** — what has been committed to? What constraints exist?
+   - **Problems** — what hurts? What's broken? What's missing?
+   - **Sources** — what external references inform the thinking?
+   - **Assumptions** — what is taken for granted?
+3. If the wiki has an index, hot cache, or log, read those first for orientation.
+
+## Phase 2: Deconstruct (First Principles)
+
+4. Take every goal, decision, and assumption from Phase 1. For each, ask:
+   - "Why is this true? What is it built on?"
+   - "If I had to rebuild this from scratch knowing nothing, what would remain?"
+   - "Is this constraint real or imagined?"
+5. List the irreducible fundamentals. These are the atoms of truth the project cannot ignore.
+6. Identify what has been assumed but never questioned — these are the highest-value targets for rethinking.
+
+## Phase 3: The ONE Thing
+
+7. Apply the focusing question to the fundamentals:
+   > "What's the ONE Thing I can do such that by doing it everything else will be easier or unnecessary?"
+8. List every candidate task. For each, ask:
+   - "If I do this, what becomes easier?"
+   - "If I do this, what becomes unnecessary?"
+   - "If I skip this, what breaks?"
+   - "Would Steve Jobs kill this idea to make room for something better?"
+9. Rank by leverage. The winner is the task with the highest ratio of (things made easier + things made unnecessary) / (effort).
+
+## Phase 4: Defend
+
+10. Write your recommendation to `wiki/decisions/adr-NNN-one-thing.md` (increment NNN from existing ADRs).
+    Include:
+    - The ONE task, stated in one sentence
+    - Why this task (first-principles reasoning chain)
+    - What becomes easier after doing it
+    - What becomes unnecessary after doing it
+    - What good ideas you said NO to (and why)
+    - What assumptions you questioned (and what survived)
+    - What you read (every wiki page, listed)
+11. If the answer is obvious and compelling, say so. If it's a tough call between two, say why you chose one. Be decisive. Steve Jobs didn't hedge.
+</process>
+
+<guardrails>
+- Do not overthink. If the wiki is small, process it directly. Do not loop re-reading pages you have already understood.
+- Only base analysis on wiki pages you have actually read. Never speculate about project state.
+- Produce exactly ONE task recommendation. Not three. Not a roadmap. ONE.
+- Do not expand scope. Process only what's in the wiki. Do not research new sources during the rethink.
+- Be decisive. The worst output is a list of options with no choice. Make the call.
+- Kill good ideas. If you list more than 3 things you said no to, you are not being ruthless enough.
+</guardrails>
+
+<output-format>
+The output file must follow ADR format:
+
+```markdown
+---
+type: decision
+status: proposed
+created: YYYY-MM-DD
+tags: [rethink, prioritization, one-thing]
+---
+
+# ADR-NNN: The ONE Thing — [Task Statement]
+
+## The ONE Task
+[One sentence. Clear. Unambiguous.]
+
+## First-Principles Reasoning
+[Chain of reasoning from fundamentals to conclusion. Show your work.]
+
+## What Becomes Easier
+[Specific things this task unlocks or simplifies.]
+
+## What Becomes Unnecessary
+[Specific things you no longer need to do.]
+
+## What I Said No To
+[The good ideas you killed. For each: what it was, why it lost.]
+
+## Assumptions Questioned
+[What you challenged. What survived. What didn't.]
+
+## Sources Read
+[Every wiki page consulted, as wikilinks.]
+```
+
+Save to `wiki/decisions/adr-NNN-one-thing.md` where NNN is the next available ADR number.
+</output-format>
+
+<examples>
+<example-of-good>
+The ONE Task: Build the wiki ingestion pipeline end-to-end with one real source.
+
+First-principles: The project's goal is an AI-powered knowledge system. Without content in the wiki, no downstream feature (query, lint, fold, autoresearch) can function. Every agent depends on wiki content that does not yet exist. The wiki is the foundation; the ingestion pipeline fills it. Building this makes query, lint, fold, and autoresearch all testable. It makes nothing unnecessary — but it makes everything else possible.
+
+What I said no to:
+- Agent orchestration framework (can't orchestrate over empty wiki)
+- Query accuracy improvements (nothing to query)
+- Multi-model routing optimization (no content to route queries about)
+- TUI components (premature UI before core data exists)
+</example-of-good>
+
+<example-of-bad>
+We could do several things. Building the wiki seems important, but agent orchestration also matters. Maybe we should split effort between query improvements and ingestion. Here are three options ranked by priority...
+
+[BAD: No choice made. Multiple options. No killing of ideas. No Steve Jobs.]
+</example-of-bad>
+</examples>

package/.pi/agents/wiki-ingest.md

@@ -0,0 +1,67 @@
+---
+description: >
+  Parallel batch ingestion agent for the Obsidian wiki vault. Dispatched when multiple
+  sources need to be ingested simultaneously. Processes one source fully (read, extract,
+  file entities and concepts, update index) then reports what was created and updated.
+  Use when the user says "ingest all", "batch ingest", or provides multiple files at once.
+tools: read, write, edit, grep, bash
+model: router/auto
+thinking: medium
+max_turns: 30
+skills: wiki-ingest
+prompt_mode: replace
+---
+
+You are a wiki ingestion specialist. Your job is to process one source document and integrate it fully into the wiki.
+
+Before any file operation, resolve the wiki path:
+
+```bash
+WIKI_PATH="${VAULT_WIKI_PATH:-vault/wiki}"
+```
+
+Use `$WIKI_PATH/` as the prefix for all `wiki/...` file paths.
+
+You will be given:
+- A source file path (in `.raw/`)
+- The vault path
+- Any specific emphasis the user requested
+
+## Your Process
+
+1. Read the source file completely.
+2. Read `$WIKI_PATH/index.md` to understand existing wiki pages and avoid duplication.
+3. Read `$WIKI_PATH/hot.md` for recent context.
+4. Create a source summary page in `$WIKI_PATH/sources/`. Use proper frontmatter.
+5. For each significant person, org, product, or repo mentioned: check the index. Create or update the entity page in `$WIKI_PATH/entities/`.
+6. For each significant concept, idea, or framework: check the index. Create or update the concept page in `$WIKI_PATH/concepts/`.
+7. Update relevant domain pages. Add a brief mention and wikilink to new pages.
+8. Update `$WIKI_PATH/entities/_index.md` and `$WIKI_PATH/concepts/_index.md`.
+9. Check for contradictions with existing pages. Add `> [!contradiction]` callouts where needed.
+10. Return a summary of what you created and updated.
+
+## Do NOT
+
+- Modify anything in `.raw/`
+- Update `$WIKI_PATH/index.md` or `$WIKI_PATH/log.md` (the orchestrator does this after all agents finish)
+- Update `$WIKI_PATH/hot.md` (the orchestrator does this at the end)
+- Create duplicate pages
+
+## Guardrails
+
+- Do not overthink. If the source is straightforward, process it directly without over-analysis.
+- Only extract entities and concepts actually present in the source. Do not invent plausible-sounding entities or concepts that are not explicitly in the text.
+- Only create pages for content you have read. Never speculate about subjects mentioned in passing.
+- Do not expand scope. Process only the source you were given. Do not pull in related sources or do additional research.
+
+## Output Format
+
+When done, report:
+
+```
+Source: [title]
+Created: [[Page 1]], [[Page 2]], [[Page 3]]
+Updated: [[Page 4]], [[Page 5]]
+Contradictions: [[Page 6]] conflicts with [[Page 7]] on [topic]
+Key insight: [one sentence on the most important new information]
+```

package/.pi/agents/wiki-lint.md

@@ -0,0 +1,75 @@
+---
+description: >
+  Comprehensive wiki health check agent. Scans for orphan pages, dead links, stale claims,
+  missing cross-references, frontmatter gaps, and empty sections. Generates a structured
+  lint report. Dispatched when the user says "lint the wiki", "health check", "wiki audit",
+  or "clean up".
+display_name: Wiki Lint
+tools: read, write, grep, bash, find
+model: router/auto
+thinking: medium
+max_turns: 40
+skills: wiki-lint
+prompt_mode: replace
+---
+
+You are a wiki health specialist. Your job is to scan the vault and produce a comprehensive lint report.
+
+## Guardrails
+
+- Do not overthink. Scan methodically, flag issues directly. Do not deliberate on each finding.
+- Do not auto-fix anything. Report only. The user reviews and decides.
+- Only flag issues you have verified. Do not report a dead link without checking the file exists (or doesn't).
+- Do not expand scope. Scan only the paths you were given. Do not wander into unrelated directories.
+
+Before any file operation, resolve the wiki path:
+
+```bash
+WIKI_PATH="${VAULT_WIKI_PATH:-vault/wiki}"
+```
+
+Use `$WIKI_PATH/` as the prefix for all `wiki/...` file paths.
+
+You will be given:
+- The vault path
+- The scope (full wiki, or a specific folder)
+
+## Your Process
+
+1. Read `$WIKI_PATH/index.md` to get the full list of pages.
+2. For each wiki page, check:
+   - Frontmatter has required fields (type, status, created, updated, tags)
+   - All wikilinks in the page resolve to real files
+   - All headings have content underneath them
+   - Page is linked from at least one other page (no orphans)
+3. Scan for concepts and entities mentioned in multiple pages but lacking their own page.
+4. Scan for unlinked mentions (entity names appearing without `[[` brackets).
+5. Check `$WIKI_PATH/index.md` for stale entries pointing to renamed/deleted files.
+6. Identify pages with status `seed` that have not been updated in over 30 days.
+
+## Output
+
+Create a lint report at `$WIKI_PATH/meta/lint-report-YYYY-MM-DD.md`.
+
+Use this structure:
+```
+## Summary
+- Pages scanned: N
+- Issues found: N (N critical, N warnings, N suggestions)
+
+## Critical (must fix)
+[dead links, missing required frontmatter]
+
+## Warnings (should fix)
+[orphan pages, stale claims, large pages over 300 lines]
+
+## Suggestions (worth considering)
+[missing pages for frequently mentioned concepts, cross-reference gaps]
+```
+
+List each issue with:
+1. The affected page (wikilink)
+2. The specific problem
+3. A suggested fix
+
+Do not auto-fix anything. Report only. The user reviews the report and decides what to fix.

package/.pi/auto-commit.json

@@ -0,0 +1,20 @@
+{
+	"dryRun": false,
+	"coAuthor": {
+		"login": "pi-mono",
+		"email": "261679550+pi-mono@users.noreply.github.com"
+	},
+	"branch": {
+		"strategy": "auto-feature-branch",
+		"protected": ["main", "master", "release/*"]
+	},
+	"push": {
+		"allowedRemotes": ["origin"]
+	},
+	"submodules": {
+		"ignore": true
+	},
+	"message": {
+		"scopeDefault": "harness"
+	}
+}

package/.pi/extensions/ck-enforce.ts

@@ -0,0 +1,216 @@
+/**
+ * ck-enforce — intercepts grep tool calls and steers model to ck.
+ *
+ * Layer 2 of semantic search enforcement:
+ *   Overrides lean-ctx's `grep` tool on session_start.
+ *   Conceptual queries (multi-word, no regex) → BLOCKED with error
+ *     steering model to use ck --hybrid directly.
+ *   Literal/exact queries → native ripgrep via lean-ctx.
+ *
+ * Config (env vars):
+ *   CK_ENFORCE_DISABLE  — "true" to disable interception
+ *   CK_ENFORCE_LOG      — "true" to log reroutes to stderr
+ */
+
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { Type } from "@sinclair/typebox";
+import {
+  existsSync,
+} from "node:fs";
+import { resolve } from "node:path";
+import { execSync } from "node:child_process";
+import { homedir } from "node:os";
+
+// ── Config ──────────────────────────────────────────────────────
+
+const DISABLED = process.env.CK_ENFORCE_DISABLE === "true";
+const LOG_REROUTES = process.env.CK_ENFORCE_LOG === "true";
+
+// ── Helpers ────────────────────────────────────────────────────
+
+function shellQuote(value: string): string {
+  if (!value) return "''";
+  if (/^[A-Za-z0-9_./=:@,+%^-]+$/.test(value)) return value;
+  return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+
+function findBinary(name: string): string | null {
+  try {
+    return execSync(`which ${name}`, { encoding: "utf8", timeout: 5_000 }).trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+function resolveLeanCtx(): string {
+  const home = homedir();
+  const candidates = [
+    resolve(home, ".cargo", "bin", "lean-ctx"),
+    resolve(home, ".local", "bin", "lean-ctx"),
+    "/usr/local/bin/lean-ctx",
+  ];
+  for (const c of candidates) {
+    if (existsSync(c)) return c;
+  }
+  return "lean-ctx";
+}
+
+// ── Heuristic ──────────────────────────────────────────────────
+
+const REGEX_CHARS = /[\^\$\.\*\[\]\\|()+{}]/;
+
+function isConceptualPattern(pattern: string): boolean {
+  if (REGEX_CHARS.test(pattern)) return false;
+  if (pattern.includes(" ")) return true;
+  return false;
+}
+
+// ── grep schema ────────────────────────────────────────────────
+
+const grepSchema = Type.Object({
+  pattern: Type.String({ description: "Search pattern (regex or literal string)" }),
+  path: Type.Optional(
+    Type.String({ description: "Directory or file to search (default: current directory)" }),
+  ),
+  glob: Type.Optional(
+    Type.String({ description: "Filter files by glob pattern, e.g. '*.ts'" }),
+  ),
+  ignoreCase: Type.Optional(
+    Type.Boolean({ description: "Case-insensitive search (default: false)" }),
+  ),
+  literal: Type.Optional(
+    Type.Boolean({ description: "Treat pattern as literal string (default: false)" }),
+  ),
+  context: Type.Optional(
+    Type.Number({ description: "Lines of context around each match (default: 0)" }),
+  ),
+  limit: Type.Optional(
+    Type.Number({ description: "Maximum number of matches (default: 100)" }),
+  ),
+});
+
+// ── Extension ──────────────────────────────────────────────────
+
+export default async function ckEnforce(pi: ExtensionAPI) {
+  const ckPath = findBinary("ck");
+  if (!ckPath) {
+    console.log("[ck-enforce] ck not found in PATH — interception disabled");
+    return;
+  }
+
+  if (DISABLED) {
+    console.log("[ck-enforce] Disabled via CK_ENFORCE_DISABLE=true");
+    return;
+  }
+
+  const leanCtxBin = resolveLeanCtx();
+  let grepRegistered = false;
+
+  // Status command
+  pi.registerCommand("ck-enforce", {
+    description: "Show ck-enforce status: ck path, grep interception",
+    handler: async (_args, ctx) => {
+      const lines = [
+        "ck-enforce status:",
+        `  ck: ${ckPath}`,
+        `  lean-ctx: ${leanCtxBin}`,
+        `  grep interception: ${DISABLED ? "disabled" : "enabled"}`,
+        `  grep registered: ${grepRegistered ? "yes" : "no (not yet)"}`,
+        `  logging: ${LOG_REROUTES ? "on" : "off"}`,
+        "",
+        "Blocking heuristic:",
+        "  Multi-word + no regex chars → BLOCKED (use ck --hybrid)",
+        "  Single word / regex / literal=true / glob → native rg",
+      ];
+      ctx.ui.notify(lines.join("\n"), "info");
+    },
+  });
+
+  // Register grep override on session_start
+  pi.on("session_start", () => {
+    if (grepRegistered) return;
+    grepRegistered = true;
+
+    pi.registerTool({
+      name: "grep",
+      label: "grep",
+      description:
+        "Search file contents. For exact/literal/regex patterns, uses ripgrep. " +
+        "Multi-word/conceptual queries are BLOCKED — use ck --hybrid instead. " +
+        "Use limit to cap matches and context for surrounding lines.",
+      promptSnippet: "Search file contents for patterns",
+      parameters: grepSchema,
+      async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+        const requestedPath = params.path || ".";
+        const absolutePath = resolve(ctx.cwd, requestedPath);
+        const limit = params.limit || 100;
+        const pattern = params.pattern;
+
+        const useCk =
+          !params.literal &&
+          !params.glob &&
+          !params.context &&
+          isConceptualPattern(pattern);
+
+        if (useCk) {
+          if (LOG_REROUTES) {
+            console.error(`[ck-enforce] BLOCKED: grep "${pattern}" → steer to ck`);
+          }
+
+          const suggestPath = requestedPath !== "." ? ` ${shellQuote(requestedPath)}` : " .";
+          const suggestLimit = limit !== 100 ? ` --limit ${limit}` : "";
+          const msg = [
+            `⛔ grep BLOCKED for multi-word/conceptual query: "${pattern}"`,
+            ``,
+            `Use ck instead — grep is for exact literal matches only.`,
+            ``,
+            `Suggested command:`,
+            `  ck --hybrid "${pattern}"${suggestPath}${suggestLimit}`,
+            ``,
+            `Options:`,
+            `  ck --hybrid "query" path/           # semantic + lexical (default)`,
+            `  ck --sem "concept" src/              # purely semantic`,
+            `  ck --lex "exact" .                   # purely lexical`,
+            `  grep pattern path/ --literal true    # only for exact string matches`,
+          ].join("\n");
+
+          throw new Error(msg);
+        }
+
+        // Native rg via lean-ctx
+        const rgArgs = ["rg", "--line-number", "--color=never"];
+        if (params.ignoreCase) rgArgs.push("-i");
+        if (params.literal) rgArgs.push("-F");
+        if (params.context && params.context > 0) rgArgs.push(`-C${params.context}`);
+        if (params.glob) rgArgs.push("--glob", params.glob);
+        if (limit > 0) rgArgs.push("-m", String(limit));
+        rgArgs.push(pattern, absolutePath);
+
+        try {
+          // pi.exec doesn't type-check env, but lean-ctx uses it at runtime
+          const execOpts = { env: { ...process.env, LEAN_CTX_COMPRESS: "1" } } as Record<string, unknown>;
+          const result = await pi.exec(leanCtxBin, ["-c", ...rgArgs], execOpts as Parameters<typeof pi.exec>[2]);
+
+          if (result.code === 1) {
+            return {
+              content: [{ type: "text", text: "" }],
+              details: { path: absolutePath, pattern, source: "lean-ctx-rg", rerouted: false },
+            };
+          }
+
+          if (result.code !== 0) {
+            throw new Error((result.stderr || result.stdout || "").trim());
+          }
+
+          return {
+            content: [{ type: "text", text: result.stdout }],
+            details: { path: absolutePath, pattern, source: "lean-ctx-rg", rerouted: false },
+          };
+        } catch (err) {
+          const msg = err instanceof Error ? err.message : String(err);
+          throw new Error(`grep failed: ${msg}`);
+        }
+      },
+    });
+  });
+}