ultimate-pi 0.1.7 → 0.2.2

package/vault/AGENTS.md

@@ -1,37 +0,0 @@
-# Codebase Map & Architecture Wiki
-
-Mode: GitHub / Repository (Mode B)
-Purpose: Maintain a codebase map, architecture wiki, and software design decisions.
-Owner: aryaniyaps
-Created: 2026-04-28
-
-## Structure
-
-```
-vault/
-├── .raw/              # source documents: code dumps, issue exports
-├── wiki/
-│   ├── modules/       # one note per major module / package / service
-│   ├── components/    # reusable UI or functional components
-│   ├── decisions/     # Architecture Decision Records (ADRs)
-│   ├── dependencies/  # external deps, versions, risk assessment
-│   ├── flows/         # data flows, request paths, auth flows
-│   └── meta/          # dashboards, lint reports, conventions
-└── CLAUDE.md          # schema and instructions (this file)
-```
-
-## Conventions
-
-- All notes use YAML frontmatter: type, status, created, updated, tags (minimum)
-- Wikilinks use [[Note Name]] format: filenames are unique, no paths needed
-- .raw/ contains source documents: never modify them
-- wiki/index.md is the master catalog: update on every ingest
-- wiki/log.md is append-only: never edit past entries
-- New log entries go at the TOP of the file
-
-## Operations
-
-- Ingest: drop source in .raw/, say "ingest [filename]"
-- Query: ask any question: Claude reads index first, then drills in
-- Lint: say "lint the wiki" to run a health check
-- Archive: move cold sources to .archive/ to keep .raw/ clean

package/vault/wiki/_templates/comparison.md

@@ -1,39 +0,0 @@
----
-type: comparison
-title: "<% tp.file.title %>"
-subjects:
-  - "[[Subject A]]"
-  - "[[Subject B]]"
-dimensions:
-  - "dimension 1"
-  - "dimension 2"
-verdict: "Replace with one-line conclusion."
-created: <% tp.date.now("YYYY-MM-DD") %>
-updated: <% tp.date.now("YYYY-MM-DD") %>
-tags:
-  - comparison
-status: seed
-related: []
-sources: []
----
-
-# <% tp.file.title %>
-
-## Overview
-
-Replace with: why these two things are being compared and what question this answers.
-
-## Comparison
-
-| Dimension | Subject A | Subject B |
-|-----------|-----------|-----------|
-| | | |
-| | | |
-
-## Verdict
-
-Replace with: one clear conclusion — which is better for what use case.
-
-## Sources
-
--

package/vault/wiki/_templates/concept.md

@@ -1,40 +0,0 @@
----
-type: concept
-title: "<% tp.file.title %>"
-complexity: intermediate
-domain: ""
-aliases: []
-created: <% tp.date.now("YYYY-MM-DD") %>
-updated: <% tp.date.now("YYYY-MM-DD") %>
-tags:
-  - concept
-status: seed
-related: []
-sources: []
----
-
-# <% tp.file.title %>
-
-## Definition
-
-[What this concept is. Declarative, present tense. One clear paragraph.]
-
-## How It Works
-
-[Mechanism or explanation]
-
-## Why It Matters
-
-[Significance in this domain]
-
-## Examples
-
--
-
-## Connections
-
--
-
-## Sources
-
--

package/vault/wiki/_templates/decision.md

@@ -1,21 +0,0 @@
----
-type: decision
-status: active
-priority: 3
-date: ""
-owner: ""
-due_date: ""
-context: ""
-tags: [decision]
-created: ""
-updated: ""
-created: 2026-04-30
-updated: 2026-04-30
----
-# {{title}}
-
-## Context
-## Options Considered
-## Decision
-## Rationale
-## Consequences

package/vault/wiki/_templates/entity.md

@@ -1,32 +0,0 @@
----
-type: entity
-title: "<% tp.file.title %>"
-entity_type: person
-role: ""
-first_mentioned: "[[]]"
-created: <% tp.date.now("YYYY-MM-DD") %>
-updated: <% tp.date.now("YYYY-MM-DD") %>
-tags:
-  - entity
-status: seed
-related: []
-sources: []
----
-
-# <% tp.file.title %>
-
-## Overview
-
-[Who or what this is. One paragraph.]
-
-## Key Facts
-
--
-
-## Connections
-
--
-
-## Sources
-
--

package/vault/wiki/_templates/flow.md

@@ -1,14 +0,0 @@
----
-type: flow
-status: active
-tags: [flow]
-created: ""
-updated: ""
-created: 2026-04-30
-updated: 2026-04-30
----
-# {{title}}
-
-## Description
-## Sequence
-## Components Involved

package/vault/wiki/_templates/module.md

@@ -1,18 +0,0 @@
----
-type: module
-path: ""
-status: active
-language: ""
-purpose: ""
-maintainer: ""
-last_updated: ""
-linked_issues: []
-depends_on: []
-used_by: []
-tags: [module]
-created: ""
-updated: ""
-created: 2026-04-30
-updated: 2026-04-30
----
-# {{title}}

package/vault/wiki/_templates/question.md

@@ -1,31 +0,0 @@
----
-type: question
-title: "<% tp.file.title %>"
-question: ""
-answer_quality: draft
-created: <% tp.date.now("YYYY-MM-DD") %>
-updated: <% tp.date.now("YYYY-MM-DD") %>
-tags:
-  - question
-status: developing
-related: []
-sources: []
----
-
-# <% tp.file.title %>
-
-**Question:** [restate the original query]
-
-## Answer
-
-[The synthesized answer, with citations to specific wiki pages]
-
-(Source: [[]])
-
-## Confidence
-
-[draft | solid | definitive] — [why]
-
-## Related Questions
-
--

package/vault/wiki/_templates/source.md

@@ -1,39 +0,0 @@
----
-type: source
-title: "<% tp.file.title %>"
-source_type: article
-author: ""
-date_published: <% tp.date.now("YYYY-MM-DD") %>
-url: ""
-confidence: medium
-key_claims:
-  - ""
-created: <% tp.date.now("YYYY-MM-DD") %>
-updated: <% tp.date.now("YYYY-MM-DD") %>
-tags:
-  - source
-status: seed
-related: []
-sources: []
----
-
-# <% tp.file.title %>
-
-## Summary
-
-[2-3 sentence summary of the source]
-
-## Key Claims
-
--
-
-## Entities Mentioned
-
-- [[]] —
-
-## Concepts Introduced
-
-- [[]] —
-
-## Notes
-

package/vault/wiki/concepts/AST-Aware Code Chunking.md

@@ -1,44 +0,0 @@
----
-type: concept
-title: "AST-Aware Code Chunking"
-created: 2026-04-30
-status: developing
-tags:
-  - chunking
-  - code-rag
-  - embeddings
-  - semantic-search
-related:
-  - "[[Semantic Codebase Indexing]]"
-  - "[[Context Engine (AI Coding)]]"
-  - "[[Contextualized Text Embedding]]"
-sources:
-  - "[[cast-code-chunking-paper]]"
-  - "[[code-chunk-library-supermemory]]"
-updated: 2026-05-02
-
----# AST-Aware Code Chunking
-
-## Definition
-
-Splitting source code into retrievable chunks at Abstract Syntax Tree (AST) boundaries instead of arbitrary character/line limits. Preserves semantic coherence: functions, classes, and methods remain intact within chunks rather than being split mid-body.
-
-## Why It Matters
-
-Line-based chunking (e.g., split every 500 chars) produces fragments like `subtotal += item.price * item.qu` — meaningless without surrounding context. AST-aware chunking ensures each chunk is a complete, self-contained syntactic unit.
-
-## Algorithm (cAST / code-chunk)
-
-1. **Parse** source into AST via tree-sitter
-2. **Extract entities**: functions, methods, classes, imports with signatures and docstrings
-3. **Build scope tree**: hierarchical parent-child relationships (method → class → file)
-4. **Greedy window assignment**: pack complete AST nodes into chunks up to max non-whitespace character limit
-5. **Recurse into oversized nodes**: if a single function exceeds chunk limit, recurse into its children
-6. **Merge adjacent small windows**: reduce fragmentation
-7. **Add contextualized text**: prepend file path, scope chain, signatures, imports before raw code
-
-## Performance Impact
-
-- cAST paper: +4.3 Recall@5 on RepoEval, +2.67 Pass@1 on SWE-bench generation
-- code-chunk implementation: 70.1% Recall@5 vs 42.4% fixed-size baseline (with hard negatives + IoU threshold)
-- Vectara NAACL 2025: chunking strategy matters as much or more than embedding model choice

package/vault/wiki/concepts/Build-Time Prompt Compilation.md

@@ -1,107 +0,0 @@
----
-type: concept
-title: "Build-Time Prompt Compilation"
-created: 2026-05-02
-updated: 2026-05-02
-tags:
-  - prompt-compilation
-  - build-time
-  - deterministic-builds
-  - npm-packaging
-status: developing
-related:
-  - "[[Prompt Renderer]]"
-  - "[[research: Prompt Renderer for Multi-Model Agent Harness]]"
-sources:
-  - "[[Source: Build-Time Prompt Compilation Architecture]]"
-
----# Build-Time Prompt Compilation
-
-The practice of compiling prompts from a base specification into validated, model-specific output at **build time** (not runtime), then shipping the compiled output as static assets in an npm package.
-
-## Why Build-Time?
-
-| Aspect | Build-Time | Runtime |
-|--------|-----------|---------|
-| **Latency** | Zero at runtime | Template parse + render per request |
-| **Caching** | Built-in (compiled output IS the cache) | Requires cache warming, TTL management |
-| **Validation** | Syntax errors caught at build | Errors at request time |
-| **npm distribution** | Static JSON files | Ship template engine + templates |
-| **Determinism** | Hash-verifiable output | Runtime variables may differ |
-| **Dependency weight** | None (compiled JSON is raw data) | Must ship template engine in bundle |
-| **Real-world tools** | Microsoft prompt-engine (abandoned, 2.8K stars), PromptWeaver (active, MIT) | Jinja2, Handlebars runtime rendering |
-
-## Pipeline Design
-
-```
-Source: prompts/*.yaml (base specs)
-   ↓ [parser]
-PromptConfig[] (validated AST)
-   ↓ [model-renderers]
-Per-model output: prompts/gpt/*.json, prompts/claude/*.json, prompts/gemini/*.json
-   ↓ [validator]
-Check: syntax, token thresholds, variable completeness
-   ↓ [serializer]
-Deterministic JSON (sorted keys, fixed formatting, hash manifest)
-   ↓ [packager]
-Included in npm package as static assets
-```
-
-## Deterministic Build Requirements
-
-1. **Version-locked renderer**: Pinned compiler version in build manifest
-2. **Input hashing**: `sha256sum` over all source spec files
-3. **Build manifest**: Records compiler version, source files, file hashes, build time
-4. **Same input → same output**: Guaranteed identical compiled prompts for same spec + version
-
-## Incremental Compilation
-
-Only recompile prompts whose spec hash changed:
-1. Hash each source spec file
-2. Compare against previous build manifest
-3. Only recompile changed specs + specs that depend on changed fragments
-4. Full compilation only for release builds
-
-## Two-Phase Variable Model
-
-```yaml
-# Compile-time vars: resolved at build, produce multiple variants
-model_name: { compile: true, values: [gpt-5.2, claude-sonnet-4.5] }
-# → generates 2 compiled prompts per spec
-
-# Runtime vars: resolved at call time, injected into compiled template
-user_query: { compile: false }
-# → placeholder left in compiled output for runtime substitution
-```
-
-## Token Budget Awareness
-
-Compiled prompts must be validated against model-specific constraints:
-- **Minimum cache threshold**: 1,024 tokens (OpenAI/Anthropic), 4,096 (Google)
-- **Maximum context window**: Model-specific (e.g., 200K for Claude)
-- **Cost estimate**: Embedded in compiled output metadata
-
-## Integration with npm
-
-```
-ultimate-pi/
-├── prompts/              # Source specs (committed to git)
-│   ├── base/
-│   │   ├── system.yaml
-│   │   ├── spec-hardening.yaml
-│   │   └── verify.yaml
-│   └── fragments/
-│       └── code-context.yaml
-├── dist/
-│   └── prompts/          # Compiled output (shipped in npm)
-│       ├── gpt/
-│       │   ├── system.json
-│       │   └── verify.json
-│       ├── claude/
-│       │   └── system.json
-│       └── gemini/
-│           └── system.json
-│       └── manifest.json  # Build manifest with hashes
-└── scripts/
-    └── compile-prompts.ts  # Build script
-```

package/vault/wiki/concepts/Context Engine (AI Coding).md

@@ -1,47 +0,0 @@
----
-type: concept
-title: "Context Engine (AI Coding)"
-created: 2026-04-30
-status: developing
-tags:
-  - ai-coding
-  - context
-  - semantic-search
-  - rag
-aliases:
-  - Codebase Context Engine
-related:
-  - "[[Semantic Codebase Indexing]]"
-  - "[[Prompt Enhancement]]"
-  - "[[Contractor vs Employee AI Model]]"
-sources:
-  - "[[Augment Context Engine Official]]"
-  - "[[Augment Code WorkOS ERC 2025]]"
-updated: 2026-05-02
-
----# Context Engine (AI Coding)
-
-A context engine is a system that provides AI coding agents with deep, semantic understanding of a codebase beyond what text search (grep) can provide. It is the differentiator between agents that merely generate code and agents that write code that fits the codebase.
-
-## Core Properties
-
-1. **Semantic indexing**: Embeds code into vector space, understanding relationships between files, functions, classes, and services.
-2. **Real-time sync**: Maintains live understanding as code changes, with millisecond-level sync.
-3. **Relationship mapping**: Tracks dependencies, call graphs, imports, and architectural patterns.
-4. **Intelligent retrieval**: Returns only what's relevant to the current task — not the entire codebase.
-5. **Multi-source**: Goes beyond code to include commit history, team patterns, documentation, and tribal knowledge.
-
-## Why It Matters
-
-The same LLM model produces dramatically different results depending on context quality. Augment Code demonstrated that Claude Opus 4.5 scored 51.80% (Auggie) vs 45.89% (SWE-Agent baseline) — a 6-point gap from context alone. When used as a context provider for other agents, improvements of 30-80% were observed.
-
-## Key Insight
-
-> Context quality determines code quality more than model intelligence. A weaker model with excellent context outperforms a stronger model with poor context.
-
-## Implementation Approaches
-
-1. **Embedding-based**: Use local embedding models (e.g., all-MiniLM-L6-v2) to index code files into a vector database (LanceDB, ChromaDB).
-2. **Hybrid retrieval**: Combine keyword (BM25) + semantic (cosine similarity) search for best recall.
-3. **Graph-based**: Build dependency/call graphs using tree-sitter AST analysis.
-4. **MCP exposure**: Wrap the context engine as an MCP server for any AI agent to consume.

package/vault/wiki/concepts/Context-Aware System Reminders.md

@@ -1,61 +0,0 @@
----
-type: concept
-title: "Context-Aware System Reminders"
-created: 2026-05-03
-updated: 2026-05-03
-status: developing
-tags:
-  - context-engineering
-  - long-horizon
-  - behavioral-steering
-  - attention-decay
-related:
-  - "[[context-engineering]]"
-  - "[[context-anxiety]]"
-  - "[[Source: OpenDev — Building AI Coding Agents for the Terminal]]"
-sources:
-  - "[[Source: OpenDev — Building AI Coding Agents for the Terminal]]"
-
----# Context-Aware System Reminders
-
-A mechanism for **counteracting instruction fade-out** in long-running agent sessions. From OpenDev ([Section 2.3.4](https://arxiv.org/html/2603.05344v1#S2.SS3.SSS4)). The core problem: after 30+ tool calls, agents silently stop following system prompt instructions — even though the instructions are still in the context window.
-
-## How It Works
-
-Instead of putting all instructions in the system prompt (which sits at the conversation's beginning and loses influence over time), inject **short, targeted reminders at the exact point of decision**.
-
-Each reminder is a brief `role: user` message placed at maximum recency in the conversation, immediately before the next LLM call. The model treats it as "something that just happened requiring a response."
-
-## Event Detectors
-
-Eight conditions trigger reminders:
-- Tool failure without retry (6 error-specific templates)
-- Exploration spiral (5+ consecutive reads)
-- Denied tool re-attempts
-- Premature completion with incomplete todos
-- Continued work after all todos done
-- Plan approval without follow-through
-- Unprocessed subagent results
-- Empty completion messages
-
-## Guardrail Counters
-
-Each reminder type has a counter or one-shot flag to prevent degenerating into noise:
-- Incomplete-todo nudges: max 2
-- Error-recovery nudges: max 3
-- Plan-approved, all-todos-complete, completion-summary: fire exactly once
-
-## Why role: user beats role: system
-
-Early experiments with `role: system` injection confirmed: user-role reminders produced noticeably higher compliance rates. After 40 turns, another system message blends into the background. A user message appears at the position of highest recency — the model treats it as something demanding a response.
-
-## Relevance to Our Harness
-
-Our harness's instruction drift is a known problem in long sessions. System reminders provide a lightweight, targeted mechanism:
-1. Catalog our failure modes (what instructions does our agent stop following?)
-2. Create a reminder template for each
-3. Detect the triggering condition at iteration boundaries
-4. Inject at decision point with `role: user`
-5. Cap frequency to prevent noise
-
-This is **cheaper than context resets** and **more targeted than full system prompt re-injection**.

package/vault/wiki/concepts/Contextualized Text Embedding.md

@@ -1,42 +0,0 @@
----
-type: concept
-title: "Contextualized Text Embedding"
-created: 2026-04-30
-status: developing
-tags:
-  - embeddings
-  - chunking
-  - code-rag
-  - semantic-search
-related:
-  - "[[AST-Aware Code Chunking]]"
-  - "[[Semantic Codebase Indexing]]"
-sources:
-  - "[[code-chunk-library-supermemory]]"
-updated: 2026-05-02
-
----# Contextualized Text Embedding
-
-## Definition
-
-Prepending semantic metadata (file path, scope chain, signatures, imports) to raw code before embedding. Transforms code from a bare syntactic fragment into a natural-language-like description that embedding models (trained primarily on natural language) can process effectively.
-
-## Format
-
-```
-# src/services/user.ts
-# Scope: UserService > getUser
-# Defines: async getUser(id: string): Promise<User>
-# Uses: Database
-# After: constructor
-
-  async getUser(id: string): Promise<User> { ... }
-```
-
-## Why It Works
-
-Embedding models like MiniLM-L6-v2 are trained on natural language corpora (Wikipedia, books, web text). They understand sentences and paragraphs, not raw code syntax. By prepending a natural-language description of what the code is, where it lives, and what it depends on, the embedding captures semantic relationships that pure code misses.
-
-## Impact on MiniLM-L6-v2
-
-MiniLM-L6-v2 was not trained on code. Without contextualized text, it embeds `async getUser(id)` as a sequence of tokens without understanding it's inside a UserService class or uses a Database. Contextualized text bridges this gap, making smaller general-purpose models viable for code retrieval.

package/vault/wiki/concepts/Contractor vs Employee AI Model.md

@@ -1,55 +0,0 @@
----
-type: concept
-title: "Contractor vs Employee AI Model"
-created: 2026-04-30
-status: developing
-tags:
-  - ai-strategy
-  - context
-  - model-selection
-aliases:
-  - Context vs Intelligence
-related:
-  - "[[Context Engine (AI Coding)]]"
-  - "[[Augment Code]]"
-sources:
-  - "[[Augment Code Codacy AI Giants]]"
-updated: 2026-05-02
-
----# Contractor vs Employee AI Model
-
-A mental model coined by Vinay Perneti (VP Engineering at Augment Code) that frames the relationship between LLM intelligence and codebase context in AI coding tools.
-
-## The Analogy
-
-| Aspect | Contractor | Employee |
-|--------|-----------|----------|
-| **Intelligence** | Has it (borrowed) | Has it |
-| **Context** | Missing | Has it (accumulated over time) |
-| **Result** | Needs constant re-explanation | Understands the codebase deeply |
-| **AI equivalent** | Raw LLM with no codebase context | LLM + Context Engine |
-
-## Why This Matters
-
-Most AI coding tools focus on model intelligence — chasing higher benchmark scores by using more powerful models. Augment's insight: context is the bottleneck, not intelligence.
-
-### Evidence
-- Claude Opus 4.5 scored 45.89% through SWE-Agent (baseline context).
-- Same model scored 51.80% through Auggie (semantic context).
-- A weaker model (Sonnet) with Augment's context can outperform Opus without it.
-
-## Practical Implications
-
-### For Tool Builders
-- Invest in context infrastructure before chasing model upgrades.
-- Build contextual understanding that persists across sessions.
-- Treat context as a first-class engineering problem, not an afterthought.
-
-### For Model Selection
-- Augment offers only 3 model choices (vs competitors' 20+).
-- Philosophy: "Let us solve the hard problems of what models make sense. You shouldn't spend mental cycles on how to get the best context."
-
-### For Our Harness
-- Context layer should be independent of model layer.
-- Swap models without rebuilding context infrastructure.
-- Invest in semantic indexing, knowledge persistence, and pattern recognition before model optimization.