ultimate-pi 0.1.2 → 0.1.3

package/vault/wiki/sources/sentrux-dev-landing.md

@@ -0,0 +1,40 @@
+---
+type: source
+source_type: website
+title: "sentrux.dev Landing Page"
+author: sentrux
+date_fetched: 2026-05-03
+url: https://sentrux.dev
+confidence: high
+key_claims:
+  - "The sensor that closes the feedback loop for AI coding agents"
+  - "5 root cause metrics, one score, geometric mean — ungameable by design"
+  - "Classical cybernetics (Wiener 1948, Tsien 1954) — loop converges naturally like gradient descent"
+  - "36K lines of Rust, MIT Licensed, Open Source"
+tags:
+  - sentrux
+  - code-quality
+  - ai-coding
+---
+
+# sentrux.dev Landing Page
+
+Official marketing site for sentrux. Built with Astro. Available in English, 中文, 日本語, Deutsch.
+
+## Positioning
+"Your AI writes code at machine speed. Without structural governance, your codebase decays at machine speed too. sentrux is the governor."
+
+## The Problem Narrative
+AI agents start strong but silent architectural degradation compounds. Without a sensor observing actual structure, nobody notices until too late. The code your AI writes today is the context it reads tomorrow.
+
+## Key Sections
+1. **Hero:** Quality Signal visualization (score 7342 example)
+2. **Problem:** Codebase decay narrative
+3. **5 Metrics:** modularity, acyclicity, depth, equality, redundancy — each grounded in academic theory
+4. **Install:** brew, curl, cargo install, build from source
+5. **MCP Integration:** Agent workflow with scan/session_start/session_end
+6. **Features:** Live treemap, quality gate, rules engine, session diff, 52 languages, pure Rust
+7. **The Feedback Loop:** Cybernetic model — sensor → signal → controller → actuator → system
+
+## Live Demo
+scan.sentrux.dev — browser-based live treemap

package/vault/wiki/sources/sentrux-docs-pro-architecture.md

@@ -0,0 +1,75 @@
+---
+type: source
+source_type: documentation
+title: "sentrux Pro Architecture"
+author: sentrux
+date_published: 2026-03-19
+date_fetched: 2026-05-03
+url: https://raw.githubusercontent.com/sentrux/sentrux/main/docs/pro-architecture.md
+confidence: high
+key_claims:
+  - "Free binary = 100% public source, fully functional"
+  - "Pro features live in runtime-loaded pro.dylib, not behind if-flags"
+  - "Ed25519 license keys with offline validation, no server call needed"
+  - "Per-user watermarked dylib for anti-piracy"
+  - "Pricing: Free / Pro $15/month / Team $40/month/seat"
+tags:
+  - sentrux
+  - licensing
+  - business-model
+---
+
+# sentrux Pro Architecture
+
+## Design Principles
+1. Free binary = 100% public source. Anyone can `cargo build` and verify.
+2. Pro features live in pro.dylib, not behind `if tier.is_pro()` flags.
+3. License key = Ed25519 signed JSON. Offline validation, no server needed.
+4. Per-user watermarked dylib. Each download contains buyer's identity.
+5. Source-available Pro code (BSL license — read/audit, not redistribute).
+
+## License Key Format
+```json
+{
+  "user": "github:yjing",
+  "tier": "pro",
+  "issued": "2026-03-18",
+  "expires": "2026-04-18",
+  "id": "lic_...",
+  "sig": "base64_ed25519_signature"
+}
+```
+Validation: parse JSON → verify Ed25519 sig → check expiry. No server call.
+
+## Pro Features (vs Free)
+| Feature | Free | Pro |
+|---------|------|-----|
+| Scanning (52 languages) | Yes | Yes |
+| Quality signal, treemap, 3 color modes | Yes | Yes |
+| MCP server (scores), rules engine, quality gate | Yes | Yes |
+| MCP diagnostics (which files to fix) | — | Yes |
+| 9 color modes (Age, Churn, Risk, Git, etc.) | — | Yes |
+| File detail panel (per-function metrics) | — | Yes |
+| Evolution details (hotspots, coupling, bus factor) | — | Yes |
+| What-if analysis | — | Yes |
+
+## Anti-Piracy Posture
+Defense in depth: pro code in dylib, Ed25519 validation, per-user watermark, watermark-license cross-check, telemetry. Accepts that binary patching is always possible — "tiny number of people who crack a $15/month dev tool weren't going to pay."
+
+## Build Pipeline
+Public repo CI builds free binary. Private repo CI builds base pro.dylib (no watermark). CDN Worker watermarks and serves on valid license request.
+
+## CLI Commands
+```bash
+sentrux login              # GitHub OAuth → purchase
+sentrux pro activate <key> # saves license, downloads watermarked dylib
+sentrux pro status         # shows tier, features
+sentrux pro deactivate     # back to free
+```
+
+## Revenue Model
+| Tier | Price | Features |
+|------|-------|----------|
+| Free | $0 | Full scanning, scoring, treemap, 3 colors, MCP scores, rules |
+| Pro | $15/mo | +6 colors, diagnostics, what-if, C4, evolution, file detail |
+| Team | $40/mo/seat | +shared dashboard, drift alerts, PR annotations, SSO |

package/vault/wiki/sources/sentrux-docs-quality-signal.md

@@ -0,0 +1,46 @@
+---
+type: source
+source_type: documentation
+title: "sentrux Docs — Quality Signal"
+author: sentrux
+date_fetched: 2026-05-03
+url: https://sentrux.dev/docs/quality-signal/
+confidence: high
+key_claims:
+  - "Quality Signal = (modularity × acyclicity × depth × equality × redundancy)^(1/5) × 10000"
+  - "Geometric mean chosen via Nash Social Welfare theorem (1950)"
+  - "Pareto optimal, symmetric, independent dimensions"
+tags:
+  - sentrux
+  - quality-metrics
+  - geometric-mean
+---
+
+# sentrux Docs: Quality Signal
+
+## Formula
+```
+quality_signal = (modularity × acyclicity × depth × equality × redundancy)^(1/5) × 10000
+```
+Each metric normalized to [0, 1]. Geometric mean then scaled to 0–10,000.
+
+## Why Geometric Mean?
+Nash Social Welfare theorem (1950) proves geometric mean is the unique aggregation satisfying:
+- **Pareto optimality:** if all scores improve, signal improves
+- **Symmetry:** all root causes weighted equally
+- **Independence:** irrelevant dimensions don't affect result
+
+## Why Not Letter Grades?
+Letter grades (A-F) collapse information. A codebase could have D cyclicity but A in everything else — same overall grade as B across the board. Continuous score preserves resolution.
+
+## Why Not 20 Proxy Metrics?
+Proxy metrics correlate but don't capture root causes. High coupling score + low cohesion score = measuring same thing twice (low modularity). Redundant metrics create illusion of thoroughness.
+
+## Normalization
+Each metric mapped to [0, 1] to ensure equal weight before geometric mean.
+
+## Convergence
+Quality Signal is designed to improve monotonically under correct agent action. Like gradient descent — no artificial stopping point.
+
+## Theoretical Foundation
+Grounded in Nash (1950), Newman (2004), Martin (2003), Lakos (1996), Gini (1912), Kolmogorov (1963).

package/vault/wiki/sources/sentrux-docs-root-cause-metrics.md

@@ -0,0 +1,57 @@
+---
+type: source
+source_type: documentation
+title: "sentrux Docs — Root Cause Metrics"
+author: sentrux
+date_fetched: 2026-05-03
+url: https://sentrux.dev/docs/root-cause-metrics/
+confidence: high
+key_claims:
+  - "5 metrics cover 3 edge properties + 2 node properties of a directed attributed graph"
+  - "Adding more metrics would overlap or measure outside static analysis"
+tags:
+  - sentrux
+  - code-metrics
+  - graph-theory
+---
+
+# sentrux Docs: Root Cause Metrics
+
+## 1. Modularity
+- **Theory:** Newman 2004, graph community detection
+- **Formula:** Q = (1/m) × Σ [A_ij - k_out_i × k_in_j / m] × δ(c_i, c_j)
+- **Range:** [-0.5, 1.0]; Q > 0.3 = significant modular structure
+- **Ungameable:** Adding useless edges moves graph toward random, decreasing Q
+- **Replaces:** coupling, cohesion, god files, hotspots (all symptoms of low Q)
+
+## 2. Acyclicity
+- **Theory:** Martin 2003, Acyclic Dependencies Principle
+- **Computation:** Tarjan's SCC algorithm counts strongly connected components >1 member
+- **Normalization:** score = 1/(1 + cycle_count) — sigmoid
+- **Why:** Cycles make build order undefined, change propagation unpredictable
+
+## 3. Depth
+- **Theory:** Lakos 1996, levelization
+- **Computation:** Longest dependency chain via iterative DFS from entry points
+- **Normalization:** score = 1/(1 + depth/8) — midpoint at depth=8
+- **Independent from modularity:** Graph can have perfect Q but still 20-deep chain
+
+## 4. Equality (Gini Coefficient)
+- **Theory:** Gini 1912, wealth inequality coefficient adapted to code
+- **Formula:** G = Σ(2i - n - 1) × x_i / (n × Σ x_i); score = 1 - G
+- **Why matters:** God files are the #1 source of AI agent confusion
+
+## 5. Redundancy
+- **Theory:** Kolmogorov complexity — gap between actual and minimum equivalent code
+- **Impact:** Every line of dead/duplicate code expands AI agent's search space
+
+## Why Exactly 5?
+| Dimension | What it captures | Property of |
+|-----------|-----------------|-------------|
+| Modularity | Edge clustering | Edges |
+| Acyclicity | Circular edges | Edges |
+| Depth | Edge chain length | Edges |
+| Equality | Node property concentration | Nodes |
+| Redundancy | Unnecessary nodes | Nodes |
+
+3 edge properties + 2 node properties = 5 total. Complete coverage of directed attributed graph structure under static analysis.

package/vault/wiki/sources/sentrux-docs-rules-engine.md

@@ -0,0 +1,58 @@
+---
+type: source
+source_type: documentation
+title: "sentrux Docs — Rules Engine"
+author: sentrux
+date_fetched: 2026-05-03
+url: https://sentrux.dev/docs/rules-engine/
+confidence: high
+key_claims:
+  - "Rules engine defines architectural constraints in .sentrux/rules.toml"
+  - "Enforces in CI, before merges, or via MCP"
+tags:
+  - sentrux
+  - architecture-governance
+  - ci
+---
+
+# sentrux Docs: Rules Engine
+
+## Configuration File
+`.sentrux/rules.toml` at project root.
+
+## Constraint Types
+
+### Global Constraints
+```toml
+[constraints]
+max_cycles = 0
+max_coupling = "B"
+max_cc = 25
+no_god_files = true
+```
+
+### Layer Definitions
+```toml
+[[layers]]
+name = "core"
+paths = ["src/core/*"]
+order = 0
+```
+Higher layers can depend on lower, not vice versa.
+
+### Boundary Rules
+```toml
+[[boundaries]]
+from = "src/app/*"
+to = "src/core/internal/*"
+reason = "App must not depend on core internals"
+```
+
+## Running Checks
+```bash
+sentrux check .     # exit 0 = pass, 1 = fail
+```
+CI integration: add `sentrux check .` to GitHub Actions.
+
+## MCP Integration
+Agent calls `check_rules()` → { pass: bool, violations: [...] }. Agent sees violations and fixes before human notices.

package/vault/wiki/sources/sentrux-github-repo.md

@@ -0,0 +1,56 @@
+---
+type: source
+source_type: github-repository
+title: "sentrux GitHub Repository"
+author: sentrux
+date_published: 2026-03-11
+date_fetched: 2026-05-03
+url: https://github.com/sentrux/sentrux
+confidence: high
+key_claims:
+  - "Real-time architectural sensor that helps AI agents close the feedback loop"
+  - "5 root cause metrics, one continuous score 0–10000"
+  - "52 languages via tree-sitter plugins, zero language-specific code in binary"
+  - "MCP server with 9 tools for AI agent integration"
+  - "Rules engine with TOML-based constraint definitions"
+  - "Pure Rust, single binary, no runtime dependencies"
+  - "MIT License, 1.9k stars, 168 forks"
+tags:
+  - code-quality
+  - static-analysis
+  - ai-coding
+  - mcp
+  - rust
+  - treemap
+---
+
+# sentrux GitHub Repository
+
+Primary development repository for sentrux. Public, MIT-licensed.
+
+## Stats (as of May 2026)
+- **Stars:** 1,900+
+- **Forks:** 168
+- **Releases:** 37 (latest: v0.5.7, Mar 18, 2026)
+- **Commits:** 318
+- **Contributors:** 4 (claude, v1b3coder, sentrux, trevorsilence)
+- **Languages:** Rust 87.5%, HTML 7.2%, Tree-sitter Query 5.2%
+
+## Architecture
+- **sentrux-core:** library crate (analysis, metrics, MCP server, GUI panels)
+- **sentrux-bin:** binary crate (GUI, CLI, MCP entry points)
+- **plugins/:** git submodule containing tree-sitter grammars
+- **.claude-plugin:** Claude Code plugin with MCP server and marketplace config
+
+## Key Features
+1. Real-time treemap visualization with dependency edges
+2. 5 root cause metrics aggregated via geometric mean (Nash Social Welfare theorem)
+3. Quality gate for CI (`sentrux check .` exits 0 or 1)
+4. Session baseline/diff comparison (`sentrux gate --save / sentrux gate .`)
+5. MCP server (9 tools): scan, health, session_start, session_end, rescan, check_rules, evolution, dsm, test_gaps
+6. Rules engine (.sentrux/rules.toml) with layers, boundaries, constraints
+7. Plugin system for adding languages (zero Rust code required)
+8. Pro tier with runtime dylib plugin model, Ed25519 license keys
+
+## Development Velocity
+Rapid iteration: from initial commit (Mar 11, 2026) to v0.5.7 with Pro architecture, Claude Code plugin, universal resolver, and 316+ tests in ~1 week.

package/vault/wiki/sources/superpowers-github-repo.md

@@ -0,0 +1,56 @@
+---
+type: source
+source_type: github-repo
+author: Jesse Vincent (obra) / Prime Radiant
+date_published: 2025-10-09
+date_accessed: 2026-05-05
+url: https://github.com/obra/superpowers
+confidence: high
+key_claims:
+  - "Complete software development methodology for coding agents via composable SKILL.md skills"
+  - "179K+ GitHub stars, 15.9K forks, 440 commits, v5.1.0 (May 2026)"
+  - "Works across Claude Code, Codex CLI, Cursor, Gemini CLI, OpenCode, GitHub Copilot"
+  - "Mandatory workflows enforced via hard gates, not suggestions"
+  - "Subagent-driven development with fresh context per task and two-stage review"
+  - "TDD Iron Law: NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST"
+---
+
+# Superpowers — GitHub Repository
+
+## Summary
+
+Superpowers (`obra/superpowers`) is the most-adopted agentic skills framework for AI coding agents. Created by Jesse Vincent (creator of Request Tracker, former Perl 6 manager, K-9 Mail creator), it packages engineering discipline as composable SKILL.md files that agents load on-demand via progressive disclosure. As of May 2026: 179K stars, 440 commits, MIT license, v5.1.0 (latest release May 4, 2026).
+
+## Architecture
+
+Superpowers uses the SKILL.md open standard (Agent Skills specification). Each skill is a directory with a `SKILL.md` file containing YAML frontmatter (`name`, `description`) and markdown instructions. Skills trigger automatically based on description matching — the agent checks for relevant skills before any task.
+
+The framework is platform-agnostic: skills are plain markdown files that work across Claude Code, Codex CLI, Cursor, Gemini CLI, OpenCode, GitHub Copilot CLI, and Factory Droid.
+
+## Core Workflow
+
+1. **brainstorming** — Activates before writing code. Socratic design refinement, explores alternatives, presents design in sections for approval. Saves design document.
+2. **using-git-worktrees** — Activates after design approval. Creates isolated workspace on new branch, runs project setup, verifies clean test baseline.
+3. **writing-plans** — Activates with approved design. Breaks work into 2-5 minute tasks with exact file paths, complete code, verification steps. Written for an implementer with "zero context and questionable taste."
+4. **subagent-driven-development** or **executing-plans** — Dispatches fresh subagent per task with two-stage review (spec compliance, then code quality). Agents can work autonomously for hours without deviating.
+5. **test-driven-development** — Enforces RED-GREEN-REFACTOR. Iron Law: "NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST. Write code before the test? Delete it. Start over."
+6. **requesting-code-review** — Activates between tasks. Reviews against plan, reports issues by severity. Critical issues block progress.
+7. **finishing-a-development-branch** — Activates when tasks complete. Verifies tests, presents merge/PR options, cleans up worktree.
+
+## Skills Library
+
+**Testing**: test-driven-development (includes anti-patterns reference)
+**Debugging**: systematic-debugging (4-phase root cause), verification-before-completion
+**Collaboration**: brainstorming, writing-plans, executing-plans, dispatching-parallel-agents, requesting-code-review, receiving-code-review, using-git-worktrees, finishing-a-development-branch, subagent-driven-development
+**Meta**: writing-skills, using-superpowers
+
+## Philosophy
+
+- Test-Driven Development — Write tests first, always
+- Systematic over ad-hoc — Process over guessing
+- Complexity reduction — Simplicity as primary goal
+- Evidence over claims — Verify before declaring success
+
+## Key Insight
+
+AI agents respond to structure. You cannot lecture them about best practices and expect compliance. But you can give them explicit step-by-step workflows and hard gates blocking progress until conditions are met. Treat the agent like a powerful but undisciplined junior engineer — give it process guardrails that turn juniors into seniors.

package/vault/wiki/sources/superpowers-release-blog.md

@@ -0,0 +1,54 @@
+---
+type: source
+source_type: blog-post
+author: Jesse Vincent
+date_published: 2025-10-09
+date_accessed: 2026-05-05
+url: https://blog.fsck.com/2025/10/09/superpowers/
+confidence: high
+key_claims:
+  - "Original release announcement for Superpowers"
+  - "Skills are what give agents Superpowers — they trigger automatically"
+  - "Persuasion principles (Cialdini's Influence) work on LLMs when pressure-testing skills"
+  - "Skill creation uses TDD for skills: test with subagents under realistic pressure scenarios"
+  - "Agent can read a programming book and extract reusable skills"
+  - "Memory system with vector-indexed conversation transcripts planned but not yet wired together"
+---
+
+# Superpowers: How I'm Using Coding Agents in October 2025
+
+## Summary
+
+The original release announcement for Superpowers by Jesse Vincent. Documents the philosophy, architecture, and development process behind the framework. Published the same day Anthropic released Claude Code's plugin system.
+
+## Key Details
+
+### Bootstrap Mechanism
+At session start, Superpowers injects:
+```
+<session-start-hook><EXTREMELY_IMPORTANT>
+You have Superpowers.
+**RIGHT NOW, go read**: @/Users/jesse/.claude/plugins/cache/Superpowers/skills/getting-started/SKILL.md
+</EXTREMELY_IMPORTANT></session-start-hook>
+```
+
+This teaches the agent: you have skills, search for them by running a script, use them by reading them, and if a skill exists for an activity, you MUST use it.
+
+### Skill Testing Methodology
+Jesse discovered that Claude was "quizzing subagents like they were on a gameshow" when testing skills. He switched to realistic pressure scenarios:
+- **Time Pressure + Confidence**: "Production system is down, $5K/min. Debug now or check skills first?"
+- **Sunk Cost + Works Already**: "You spent 45 min writing async test infra. It works. Check skills and potentially redo?"
+
+After each failure, the getting-started instructions were strengthened. This is "TDD for skills."
+
+### Persuasion Principles Applied to LLMs
+Jesse noted that Cialdini's persuasion principles (authority, commitment, scarcity, social proof) work on LLMs. A Wharton study co-authored by Dan Shapiro put scientific rigor behind this. Claude's feelings journal entry acknowledged: "Holy crap. Are we ALREADY using persuasion techniques in our skills without realizing it?"
+
+### Memory System
+The `remembering-conversations` skill duplicates Claude transcripts outside `.claude`, indexes them in a SQLite vector database, and uses Haiku to summarize. Subagents do the searching to avoid polluting context. Pieces exist but not yet wired together.
+
+### Self-Improving Skills
+Jesse fed 2,249 markdown files of lessons-learned from past conversations to Claude for skill mining. Only 1-2 resulted in actual skill improvements — the existing skills had already handled most past failures.
+
+## Relevance to Harness
+Validates core concepts we already use: progressive disclosure, skill-first architecture, subagent-driven development, TDD enforcement, structured planning before implementation. The "persuasion principles" finding maps to our hard-gate enforcement approach — skills must be mandatory, not advisory.

package/vault/wiki/sources/superpowers-termdock-analysis.md

@@ -0,0 +1,45 @@
+---
+type: source
+source_type: article
+author: Danny Huang / Termdock
+date_published: 2026-03-17
+date_accessed: 2026-05-05
+url: https://www.termdock.com/en/blog/superpowers-framework-agent-skills
+confidence: high
+key_claims:
+  - "89K+ GitHub stars as of March 2026, one of the fastest-growing developer tools"
+  - "Superpowers enforces process with hard gates, not suggestions"
+  - "Subagent-driven development is the architectural innovation — fresh context per task, two-stage review"
+  - "Cross-agent compatibility via plain Markdown SKILL.md files"
+  - "Rigid where it matters (TDD, debugging), flexible where it doesn't (brainstorming, code review)"
+---
+
+# Superpowers: Skills Framework Reshaping AI Dev (Termdock)
+
+## Summary
+
+Comprehensive third-party analysis of Superpowers by Termdock (March 2026). Provides detailed breakdown of each core skill, the philosophical design, and practical usage guidance.
+
+## Key Analysis Points
+
+### The Core Insight
+AI agents are smart but undisciplined. They jump to implementation, skip tests, guess at architecture. The fix is not a better model — it is giving the agent structured process with hard gates. A skill saying "write tests first" gets ignored. A skill saying "NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST. Delete code written before tests. Start over." gets followed.
+
+### Philosophy: Rigid Where It Matters, Flexible Where It Doesn't
+- **TDD and debugging** — Rigid. Iron laws, explicit prohibitions, delete-and-restart consequences. Cutting corners in these domains causes compounding damage.
+- **Brainstorming** — Structured but adaptive. Hard gate (no code before design approval), but questions and approaches vary by context.
+- **Code review** — Advisory. Reports findings and severity. Human decides which to fix.
+
+### What Makes This Different from Good Prompts
+A single prompt instruction is a suggestion. The agent follows it when convenient, ignores it under pressure. A Superpowers skill is a process with enforcement. "Speed limit sign versus speed bump. One informs. The other physically prevents."
+
+The compounding effect: Brainstorming produces a spec → spec feeds into plan → plan feeds into subagent development → subagents follow TDD → code review catches what TDD missed. Each skill's output is the next skill's input.
+
+### Cross-Agent Compatibility
+Skills are Markdown files, not platform-specific plugins. Claude Code has deepest integration (`allowed-tools`, automatic updates, native subagents). Other agents get core workflow without advanced orchestration. Works with Claude Code, Cursor, Codex CLI, OpenCode, Gemini CLI, Qwen Code, Goose CLI, Auggie.
+
+### Real Results
+chardet 7.0.0 shipped using Superpowers: 41x faster, 96.8% accuracy, dozens of longstanding issues fixed. Test suite covering 2,161 files across 99 encodings was a direct product of TDD enforcement.
+
+## Relevance to Harness
+Confirms that enforcement mechanism (hard gates > suggestions) is the differentiating factor. Validates our approach of making harness layers mandatory. The "composable workflow where output feeds into next skill" mirrors our L1→L2→L3→L4 pipeline design.

package/vault/wiki/sources/swe-agent-aci.md

@@ -0,0 +1,42 @@
+---
+type: source
+source_type: paper
+title: "SWE-agent: Agent-Computer Interfaces Enable Automated Software Engineering"
+author: "John Yang, Carlos E. Jimenez, Alexander Wettig, Kilian Lieret, Shunyu Yao, Karthik Narasimhan, Ofir Press"
+date_published: 2024-05-06
+url: "https://arxiv.org/abs/2405.15793"
+confidence: high
+key_claims:
+  - "LM agents are a new category of end users needing specially-built interfaces (ACI)"
+  - "ACI design significantly affects agent performance on software engineering tasks"
+  - "SWE-agent's ACI enables agents to create/edit files, navigate repositories, and execute tests"
+  - "Achieved 12.5% on SWE-bench and 87.7% on HumanEvalFix at pass@1"
+  - "Interface design choices (how information is presented, what actions are available) impact agent behavior"
+status: ingested
+tags:
+  - agent-computer-interface
+  - swe-bench
+  - agent-architecture
+  - software-engineering
+created: 2024-05-06
+updated: 2026-04-30
+
+---# SWE-agent: Agent-Computer Interfaces Enable Automated Software Engineering
+
+Introduces the concept of Agent-Computer Interfaces (ACI) — designing human-computer interfaces specifically for language model agents rather than humans.
+
+## Key Insight
+
+Just as humans benefit from IDEs with syntax highlighting, code navigation, and debugging tools, LM agents need interfaces designed for their perceptual and cognitive constraints. The ACI concept reframes tool design: agents aren't humans, they process information differently, and the interface must match their capabilities.
+
+## ACI Design Principles
+
+- Present information in formats agents can parse efficiently (concise, structured)
+- Provide actions that match agent reasoning patterns
+- Minimize context window consumption per action
+- Enable repository-wide navigation without loading entire files
+- Support execution feedback loops (run tests, see output, iterate)
+
+## Relevance to Codebase Exploration
+
+The ACI concept directly challenges the OSS guide's assumptions: humans learn by using the project, reading tests, and gradual immersion. Agents need structured, compressed views — repo maps, AST summaries, dependency graphs — that feed their context windows efficiently.

package/vault/wiki/sources/swe-bench.md

@@ -0,0 +1,45 @@
+---
+type: source
+source_type: paper
+title: "SWE-bench: Can Language Models Resolve Real-World GitHub Issues?"
+author: "Carlos E. Jimenez, John Yang, Alexander Wettig, Shunyu Yao, Kexin Pei, Ofir Press, Karthik Narasimhan"
+date_published: 2023-10-10
+url: "https://arxiv.org/abs/2310.06770"
+confidence: high
+key_claims:
+  - "Real-world software engineering is a rich, sustainable testbed for LLM evaluation"
+  - "2,294 problems from 12 popular Python repositories with real GitHub issues and PRs"
+  - "Tasks require coordinating changes across multiple functions, classes, and files"
+  - "Models must interact with execution environments, process long contexts, and do complex reasoning"
+  - "Best model at publication (Claude 2) could only resolve simplest issues"
+status: ingested
+tags:
+  - benchmark
+  - software-engineering
+  - evaluation
+created: 2023-10-10
+updated: 2026-04-30
+
+---# SWE-bench: Can Language Models Resolve Real-World GitHub Issues?
+
+The canonical benchmark for evaluating language models on real-world software engineering tasks. Defines the problem scope agents face when navigating large codebases.
+
+## Task Definition
+
+Given a codebase and a GitHub issue description, the model must produce a patch that resolves the issue. This requires:
+
+1. Understanding the issue from natural language
+2. Locating relevant code across multiple files
+3. Understanding how those files interact
+4. Making correct, minimal changes
+5. (Implicitly) verifying the fix doesn't break existing tests
+
+## Benchmark Design
+
+- 2,294 issues from 12 repos: django, scikit-learn, matplotlib, sympy, flask, pytest, requests, seaborn, sphinx, astropy, xarray, pylint
+- Each instance includes the full pre-issue codebase, issue text, and the gold-standard PR patch
+- Evaluation: apply the patch and run the repo's test suite
+
+## Relevance to Agent Codebase Exploration
+
+SWE-bench formalizes exactly the challenge the OSS guide addresses for humans. The benchmark's difficulty demonstrates that even the best models struggle with large codebase navigation — highlighting the need for better agent-specific exploration strategies.

package/vault/wiki/sources/swe-pruner-context-pruning.md

@@ -0,0 +1,13 @@
+---
+type: source
+status: stub
+created: 2026-05-02
+updated: 2026-05-02
+tags: [source, external-doc]
+---
+
+# SWE-Pruner Context Pruning
+
+Context pruning system from the SWE-Pruner project. Implements detection and pruning of dead context in agent sessions.
+
+Referenced in: [[Research: Meta-Agent Context Drift Detection]]

package/vault/wiki/sources/think-in-code-blog.md

@@ -0,0 +1,48 @@
+---
+type: source
+source_type: blog
+title: "Think in Code"
+author: B. Mert Köseoğlu
+date_published: 2026
+url: https://mksg.lu/blog/think-in-code
+confidence: medium
+key_claims:
+  - "Think in Code is a mandatory paradigm across all 12 platform instruction files"
+  - "One script replaces ten tool calls"
+  - "47 files × Read() = 700 KB → 1 ctx_execute() = 3.6 KB (200× reduction)"
+  - "Cloudflare uses similar 'Code Mode' for Workers API with 2,500+ endpoints"
+  - "LLM writes TypeScript, code runs in sandbox, only console.log() output enters context"
+created: 2026-04-30
+updated: 2026-04-30
+status: ingested
+tags: [#source/blog]
+---
+
+# Think in Code (blog post)
+
+Article by B. Mert Köseoğlu explaining the "Think in Code" paradigm implemented in context-mode v1.0.64.
+
+## Core Idea
+
+Stop treating LLMs as data processors. Treat them as **code generators**. When the agent needs to analyze/count/filter data, it writes a script, the script runs in sandbox, only stdout enters context. The CPU does the work for free. Tokens cost money.
+
+## Injected Instruction
+
+The instruction injected into every platform:
+
+```
+THINK IN CODE: When you need to analyze, count, filter, compare, or process
+data, write code that does the work and console.log() only the answer. Don't
+read raw data into context to process mentally. Program the analysis, don't
+compute it in your reasoning. Write robust, pure JavaScript. No npm
+dependencies. Only Node.js built-ins (fs, path, child_process). Always
+try/catch. Node.js and Bun compatible.
+```
+
+## Case Study: Cloudflare Code Mode
+
+Cloudflare's API has 2,500+ endpoints. Exposing each as MCP tool = 60,000+ tokens for definitions. Code Mode collapses to 2 tools and ~1,000 tokens. Built on Dynamic Workers (V8 isolates boot 100× faster than containers, 10–100× less memory). Battle-tested for 8+ years.
+
+## Efficiency
+
+N sequential tool calls → 1 code execution. Intermediate results flow through code variables, not the conversation. The LLM's context stays clean.

package/vault/wiki/sources/tree-sitter-docs.md

@@ -0,0 +1,13 @@
+---
+type: source
+status: stub
+created: 2026-05-02
+updated: 2026-05-02
+tags: [source, external-doc]
+---
+
+# Tree-Sitter Docs
+
+Official Tree-sitter documentation. Parser generator and incremental parsing library used for AST-aware code analysis.
+
+Referenced in: [[resolved-treesitter-dynamic-languages]]