ultimate-pi 0.1.2 → 0.1.4

package/vault/wiki/concepts/harness-control-frameworks.md

@@ -0,0 +1,155 @@
+---
+type: concept
+title: "Harness Control Frameworks — Unified"
+created: 2026-04-30
+updated: 2026-04-30
+status: active
+tags: [harness, controls, architecture, formal-model, unified]
+related:
+  - "[[harness-h-formalism]]"
+  - "[[feedforward-feedback-harness]]"
+  - "[[generator-evaluator-architecture]]"
+  - "[[harness-implementation-plan]]"
+  - "[[agentic-harness]]"
+sources:
+  - "[[meng2026-agent-harness-survey]]"
+  - "[[bockeler2026-harness-engineering]]"
+  - "[[anthropic2026-harness-design]]"
+---
+
+# Harness Control Frameworks — Unified
+
+Three independent frameworks describe harness controls. They are complementary, not competing. This page unifies them and maps them to our pipeline.
+
+## The Three Frameworks
+
+| Framework | Source | Focus | Analogy |
+|-----------|--------|-------|---------|
+| **H-Formalism** H=(E,T,C,S,L,V) | Meng et al. 2026 | Component taxonomy — what pieces must exist | Blueprint |
+| **Feedforward-Feedback** | Böckeler/Fowler 2026 | Control flow — how information moves through the system | Cybernetics |
+| **Generator-Evaluator** | Anthropic 2026 | Agent topology — who does what, who checks whom | Org chart |
+
+Each answers a different question:
+- H-Formalism: "What components must every harness have?"
+- Feedforward-Feedback: "How do guides and sensors work together?"
+- Generator-Evaluator: "How should agents be organized to prevent self-deception?"
+
+---
+
+## H-Formalism: Component Taxonomy (Meng 2026)
+
+**H = (E, T, C, S, L, V)** — six components. No harness achieves production reliability without all six.
+
+| Component | Our Implementation |
+|-----------|-------------------|
+| **E** Execution Loop | L1-L4 pipeline (Spec → Plan → Execute → Verify) |
+| **T** Tool Registry | Tool schemas, MCP tools (lean-ctx 48 tools, ck, Gitingest), skills |
+| **C** Context Manager | Wiki knowledge base, AST truncation, lean-ctx compression, think-in-code |
+| **S** State Store | Wiki vault, ctx_session, hot.md cache |
+| **L** Lifecycle Hooks | L7 Archon orchestration, post-edit validation, drift monitor hooks |
+| **V** Evaluation Interface | L4 adversarial verification, L5 observability, terminal-bench |
+
+**Gaps**: No formal contract language for component interfaces. L-component is implicit. V-component needs systematic action trajectory tracking.
+
+See [[harness-h-formalism]] for full component-by-component specification.
+
+---
+
+## Feedforward-Feedback: Control Flow (Böckeler/Fowler 2026)
+
+Cybernetics model: guides (feedforward) set expectations before action. Sensors (feedback) measure outcomes after action.
+
+```
+FEEDFORWARD (Guides)                   FEEDBACK (Sensors)
+├─ Computational                       ├─ Computational
+│  ├─ Language servers                 │  ├─ Tests (unit, integration)
+│  ├─ CLIs, scripts                    │  ├─ Linters (ESLint, ruff)
+│  └─ Codemods                         │  ├─ Type checkers
+│                                      │  ├─ Mutation testing
+├─ Inferential                         │  └─ Structural tests (ArchUnit)
+│  ├─ AGENTS.md, skills                │
+│  ├─ Rules, conventions               ├─ Inferential
+│  ├─ Reference docs                   │  ├─ AI code review agents
+│  └─ How-to guides                    │  ├─ LLM-as-judge
+│                                      │  └─ Semantic analysis
+```
+
+**Our implementation mapping**:
+
+| Control Type | Our Implementation |
+|-------------|-------------------|
+| Feedforward-Computational | Tool schemas, `tsc --noEmit`, JSON schema validation, structured output contracts |
+| Feedforward-Inferential | SKILL.md files, ADRs, wiki pages, AGENTS.md, model profiles |
+| Feedback-Computational | Inline syntax validation (Phase 12), final lint+format gate (Phase 16), ck semantic grep |
+| Feedback-Inferential | L4 adversarial verification, L2 plan review, L1 spec debate, meta-agent drift monitor (L2.5) |
+
+**Key insight**: Agents need BOTH feedforward AND feedback. Separately, agents either repeat mistakes (feedback-only) or encode rules but never verify them (feedforward-only).
+
+**Unsolved**: Behaviour Harness — functional correctness verification. Current approach (AI-generated tests + manual testing) insufficient. Future Phase F2.
+
+**Steering loop**: Human improves feedforward/feedback controls when issues repeat. This is ongoing harness engineering, not one-time configuration.
+
+See [[feedforward-feedback-harness]] for detailed framework specification.
+
+---
+
+## Generator-Evaluator: Agent Topology (Anthropic 2026)
+
+**Core finding**: When agents evaluate their own work, they "confidently praise mediocre outputs." Self-evaluation is fundamentally broken. Must separate generator from evaluator.
+
+**GAN-inspired architecture**:
+- Generator agent creates output
+- Evaluator agent checks it
+- Evaluator must be explicitly tuned to be skeptical
+- Out of the box, Claude "talks itself out of flagging real issues"
+
+**Our implementation**:
+
+| Layer | Generator | Evaluator | Mechanism |
+|-------|-----------|-----------|-----------|
+| L1 (Spec) | Spec hardener | Spec critic (debate, selective) | Sprint contract: agree "done" before L2 |
+| L2 (Plan) | Planner | Plan critic (debate, selective) | Sprint contract: agree "done" before L3 |
+| L4 (Code) | Implementer (L3) | Adversarial critic (L4) | Hard-threshold pass/fail, multi-round debate |
+
+**Key improvements from this framework**:
+1. Sprint contracts at L2: generator and evaluator explicitly agree on "what done means" BEFORE code is written
+2. Hard-threshold grading: not narrative feedback ("looks good") but falsifiable checklist ("passes all 7 criteria")
+3. Evaluator separate model: use different model for evaluator for genuine adversarial diversity
+4. Regular simplification audits: as models improve, remove unnecessary evaluator components
+
+See [[generator-evaluator-architecture]] for full specification.
+
+---
+
+## How They Fit Together
+
+```
+┌──────────────────────────────────────────────────────────┐
+│                 HARNESS CONTROL STACK                     │
+│                                                           │
+│  H-Formalism (Component Blueprint)                        │
+│  ├─ E: Execution Loop → L1-L4 pipeline                   │
+│  ├─ T: Tool Registry → lean-ctx, ck, Gitingest           │
+│  ├─ C: Context Manager → Wiki, AST truncation, TiC       │
+│  ├─ S: State Store → Wiki vault, hot.md                  │
+│  ├─ L: Lifecycle Hooks → L7 orchestration hooks          │
+│  └─ V: Evaluation → L4 adversarial, L5 observability     │
+│                                                           │
+│  Feedforward-Feedback (Control Flow)                      │
+│  ├─ Feedforward-Inferential → SKILL.md, ADRs, AGENTS.md  │
+│  ├─ Feedforward-Computational → Tool schemas, validators │
+│  ├─ Feedback-Inferential → L4 critics, L2.5 drift monitor│
+│  └─ Feedback-Computational → Phase 12 syntax, Phase 16   │
+│                                                           │
+│  Generator-Evaluator (Agent Topology)                     │
+│  ├─ Generator agents → L1 spec, L2 plan, L3 execute      │
+│  └─ Evaluator agents → L1 critic, L2 critic, L4 critic   │
+└──────────────────────────────────────────────────────────┘
+```
+
+The three frameworks are orthogonal dimensions of the same system:
+- **H-Formalism** says WHAT must exist
+- **Feedforward-Feedback** says HOW information flows
+- **Generator-Evaluator** says WHO does what
+
+Any component can be analyzed through all three lenses simultaneously.

package/vault/wiki/concepts/harness-engineering-first-principles.md

@@ -0,0 +1,90 @@
+---
+type: concept
+title: "Harness Engineering First Principles"
+created: 2026-05-01
+updated: 2026-05-01
+status: stable
+tags:
+  - harness
+  - first-principles
+  - architecture
+related:
+  - "[[harness-implementation-plan]]"
+  - "[[harness]]"
+  - "[[harness-control-frameworks]]"
+sources:
+  - "[[Source: Martin Fowler - Harness Engineering]]"
+  - "[[Source: LangChain - Anatomy of Agent Harness]]"
+  - "[[Source: OpenAI Harness Engineering Five Principles]]"
+  - "[[Source: Augment - Harness Engineering for AI Coding Agents]]"
+
+---# Harness Engineering: First Principles
+
+## Core Definition
+
+**Agent = Model + Harness.** (LangChain, 2026)
+
+The harness is every piece of code, configuration, and execution logic that isn't the model itself. A raw model is not an agent. It becomes one when a harness gives it state, tool execution, feedback loops, and enforceable constraints.
+
+## First Principles (Synthesized from All Sources)
+
+### P1: Feedforward + Feedback
+Every harness control is either a **guide** (feedforward: anticipate, prevent) or a **sensor** (feedback: observe, self-correct). Both are required — feedforward-only encodes rules never tested; feedback-only repeats mistakes. Source: [[Source: Martin Fowler - Harness Engineering]]
+
+### P2: Computational > Inferential (for Enforcement)
+Computational controls (linters, type checkers, structural tests) are deterministic, fast, and cheap. Inferential controls (AI code review, LLM-as-judge) are probabilistic, slow, and expensive. Prefer computational for enforcement; use inferential for discovery and guidance. Source: [[Source: Martin Fowler - Harness Engineering]]
+
+### P3: Mechanical Enforcement Over Documentation
+Documentation alone cannot keep agent-generated code consistent. Invariant rules must be enforced mechanically (linters, structural tests, CI gates). The linters themselves can be written by agents. Source: [[Source: OpenAI Harness Engineering Five Principles]]
+
+### P4: What the Agent Can't See Doesn't Exist
+All decisions, context, architecture, and conventions must live in the repository as structured documents (markdown, schemas, plans). Tacit knowledge, Slack decisions, Google Docs — invisible to agent = nonexistent. Source: [[Source: OpenAI Harness Engineering Five Principles]]
+
+### P5: Ask What Capability Is Missing
+When agent fails, ask "what capability is missing from the environment?" — not "why is the agent failing?" Reframe from prompting harder to instrumenting better. Source: [[Source: OpenAI Harness Engineering Five Principles]]
+
+### P6: Give the Agent Eyes
+Connect observability, browser automation, logs, metrics directly to agent runtime. Prompts like "make service start under 800ms" become executable when agent can query metrics. Source: [[Source: OpenAI Harness Engineering Five Principles]]
+
+### P7: A Map, Not a Manual
+Context must be a bird's-eye view (what rarely changes), not exhaustive documentation. State architectural boundaries as "something does not exist here" rather than long descriptions. Source: [[Source: OpenAI Harness Engineering Five Principles]]
+
+### P8: Keep Quality Left
+Distribute checks across development timeline by cost/speed/criticality. Fast checks pre-commit (linters, fast tests). Expensive checks post-integration (mutation testing, broad code review). Continuous drift sensors run outside change lifecycle. Source: [[Source: Martin Fowler - Harness Engineering]]
+
+### P9: Progressive Disclosure
+Too many tools/skills loaded at context start degrades performance. Load capabilities on-demand via activation mechanism. Skills solve context rot through progressive disclosure. Source: [[Source: LangChain - Anatomy of Agent Harness]]
+
+### P10: The Steering Loop
+Human iterates on harness. When issue recurs → improve feedforward/feedback controls. Agents can help write harness controls (custom linters, structural tests, how-to guides). Source: [[Source: Martin Fowler - Harness Engineering]]
+
+### P11: Model-Harness Independence
+Best harness for a task may NOT be the one a model was post-trained with. Co-evolution creates overfitting to specific tool logic. Test model-harness combinations independently. Source: [[Source: LangChain - Anatomy of Agent Harness]]
+
+### P12: Ashby's Law of Requisite Variety
+Regulator must have at least as much variety as system it governs. Committing to predefined topologies (harness templates) reduces variety, making comprehensive harness achievable. Source: [[Source: Martin Fowler - Harness Engineering]]
+
+## Three Regulation Dimensions
+
+1. **Maintainability**: Code quality, conventions, structure. Easiest — pre-existing computational tooling.
+2. **Architecture Fitness**: Performance, observability, security characteristics. Fitness functions.
+3. **Behaviour**: Functional correctness. Hardest — AI-generated tests unreliable. "Elephant in the room."
+
+Source: [[Source: Martin Fowler - Harness Engineering]]
+
+## How Ultimate-PI Maps
+
+| Principle | Ultimate-PI Implementation |
+|-----------|---------------------------|
+| P1 Feedforward + Feedback | L1-L2 (feedforward), L2.5-L4 (feedback) |
+| P2 Computational > Inferential | Phase 16 Lint Gate (computational), L4 Adversarial (inferential) |
+| P3 Mechanical Enforcement | Planned P-F1 (pre-execution policy gates) |
+| P4 Visibility | L3 Grounding (Gitingest + ck + wiki) |
+| P5 Capability Thinking | Tool-first approach (ck, pi-lean-ctx, pi-messenger) |
+| P6 Agent Eyes | L5 Observability (lacks browser/CDP — P-F7) |
+| P7 Map Not Manual | wiki/overview.md + index.md (lacks formal ARCHITECTURE.md) |
+| P8 Keep Quality Left | Phased pipeline (L1→L8) with drift at multiple points |
+| P9 Progressive Disclosure | `.pi/skills/` (lacks formal activation — P-F2) |
+| P10 Steering Loop | L7 Archon + L8 Wiki Query + wiki/log.md |
+| P11 Model-Harness Independence | 4 model profiles × 4 config layers |
+| P12 Ashby's Law | Not yet applied (no harness templates) |

package/vault/wiki/concepts/harness-h-formalism.md

@@ -0,0 +1,53 @@
+---
+type: concept
+title: "Harness H-Formalism (H = ETCSLV)"
+created: 2026-04-30
+updated: 2026-04-30
+status: seed
+tags:
+  - harness
+  - architecture
+  - formal-model
+related:
+  - "[[agentic-harness]]"
+  - "[[harness-implementation-plan]]"
+  - "[[model-adaptive-harness]]"
+sources:
+  - "[[meng2026-agent-harness-survey]]"
+
+---# Harness H-Formalism
+
+The six-component formal model of an agent execution harness, from Meng et al. (2026): **H = (E, T, C, S, L, V)**.
+
+## Components
+
+| Symbol | Name | Function |
+|--------|------|----------|
+| **E** | Execution Loop | Observe-think-act cycle, termination conditions, error recovery |
+| **T** | Tool Registry | Typed tool catalog, routing, monitoring, schema validation |
+| **C** | Context Manager | What enters the context window, compaction, retrieval |
+| **S** | State Store | Persistence across turns/sessions, crash recovery |
+| **L** | Lifecycle Hooks | Auth, logging, policy enforcement, instrumentation |
+| **V** | Evaluation Interface | Action trajectories, intermediate states, success signals |
+
+## Key Finding
+
+> No agent framework can achieve production reliability without implementing ALL six governance components.
+
+## Mapping to Our Harness
+
+| H Component | Our Implementation |
+|-------------|-------------------|
+| E | L1-L4 pipeline (Spec → Plan → Execute → Verify) |
+| T | Tool schemas, MCP tools, skills |
+| C | Wiki knowledge base, context compaction, AST truncation |
+| S | Wiki vault persistence, session memory (ctx_session) |
+| L | Archon L7 orchestration, post-edit validation hooks |
+| V | L4 adversarial verification, L5 observability |
+
+## Gaps
+
+- No formal specification language for component contracts
+- L-component (lifecycle hooks) is implicit, not explicit
+- V-component does not track intermediate action trajectories systematically
+- No cross-harness portability testing

package/vault/wiki/concepts/hybrid-code-search.md

@@ -0,0 +1,61 @@
+---
+type: concept
+status: stable
+created: 2026-04-30
+updated: 2026-04-30
+tags:
+  - code-search
+  - semantic-search
+  - embeddings
+  - information-retrieval
+related:
+  - "[[ck-tool]]"
+  - "[[agent-search-enforcement]]"
+  - "[[Research: semantic code search tools]]"
+title: "hybrid code search"
+
+---# hybrid code search
+
+Combining lexical (keyword-based) and semantic (embedding-based) search with Reciprocal Rank Fusion (RRF) for code search.
+
+## Lexical Search (BM25)
+
+- Exact keyword matching
+- Fast, deterministic, predictable
+- Finds what you ask for literally
+- Misses conceptual matches: `"retry logic"` won't find `with_backoff()`, `circuit_breaker()`
+
+## Semantic Search (Embeddings)
+
+- Vector similarity based on meaning
+- Finds conceptually related code even without keyword overlap
+- Query `"error handling"` finds `try/catch`, `Result<T,E>`, `if err != nil`
+- Non-deterministic: results depend on embedding model and threshold
+- Can surface irrelevant results (false positives)
+
+## Reciprocal Rank Fusion (RRF)
+
+```
+RRF_score(d) = Σ (1 / (k + rank_i(d)))
+```
+
+Where `k` is a constant (typically 60) and `rank_i` is the document's rank in each result list. RRF combines ranked lists from lexical and semantic search without requiring score normalization. Documents ranked highly by both methods get the highest fused scores.
+
+## Why Hybrid Matters for AI Agents
+
+AI coding agents need both precision (exact function/class names) and recall (finding all error-handling code). Hybrid search gives both in one query:
+
+```bash
+ck --hybrid "connection timeout handling" src/
+```
+
+This finds:
+1. Exact matches for `timeout`, `connection` (lexical)
+2. Related patterns: `setTimeout`, `connect_timeout`, `deadline`, `keepalive` (semantic)
+3. RRF re-ranks so items matching both appear first
+
+## Alternatives to RRF
+
+- **Linear combination**: Weighted sum of normalized scores. Requires score calibration.
+- **Learning to rank (LTR)**: Trained model predicts relevance. Requires labeled training data.
+- **Simple concatenation**: Append semantic results to lexical results. No re-ranking.

package/vault/wiki/concepts/inline-post-edit-validation.md

@@ -0,0 +1,112 @@
+---
+type: concept
+title: "Inline Post-Edit Validation"
+created: 2026-04-30
+updated: 2026-04-30
+tags:
+  - agent-tools
+  - quality
+  - token-reduction
+related:
+  - "[[wozcode]]"
+  - "[[grounding-checkpoints]]"
+  - "[[adversarial-verification]]"
+  - "[[research-wozcode-token-reduction]]"
+  - "[[harness-implementation-plan]]"
+status: developing
+
+---# Inline Post-Edit Validation
+
+Inline post-edit validation runs **compilers and parsers** immediately after each code edit — before the model sees the result. Syntax errors are caught at the tool layer, not at the agent reasoning layer, eliminating unnecessary retry round-trips. Linting and formatting are deferred to Phase 16: a single deterministic final gate that runs after L4 adversarial verification passes. See [[harness-implementation-plan#phase-16-final-lint-format-gate|Phase 16]].
+
+## How It Differs From Our Current Approach
+
+| Aspect | Current Harness (L3+L4) | WOZCODE (Inline) | Our Design (Phase 12 + 16) |
+|--------|------------------------|-------------------|---------------------------|
+| **When syntax validation runs** | After all edits, before next phase | After each individual edit | After each individual edit (Phase 12) |
+| **When linting runs** | N/A (not in pipeline) | Inline after each edit | Once, post-L4 verification (Phase 16) |
+| **When formatting runs** | N/A (not in pipeline) | Inline after each edit | Once, post-L4, absolute last code-modifying step (Phase 16) |
+| **Who sees errors** | Model sees errors, reformulates | Tool layer catches errors, auto-fixes or enriches | Syntax: tool layer. Lint/format: deterministic gate, no LLM |
+| **Error context** | Raw compiler/linter output | Dialect-specific hints, location-precise diffs | Syntax: enriched diffs. Lint: structured violation report |
+| **Auto-fix capability** | None | SQL dialect rewrites, common pattern fixes | Syntax: SQL dialect. Lint: eslint --fix, biome --fix, ruff --fix. Format: always auto-applied |
+| **Token cost** | Error + re-edit = full round-trip | Caught pre-model = zero model tokens | Syntax inline: zero. Lint/format gate: zero (deterministic tools) |
+
+## WOZCODE's Implementation (Source: [[wozcode]])
+
+### Syntax Validation
+After every edit, WOZCODE runs:
+- **TypeScript compiler** (`tsc --noEmit`): catches type errors
+- **JSON/YAML/HTML parsers**: catches structural errors
+- **SQL linter**: catches syntax and semantic errors
+
+If no errors → edit result returned to model. If errors → inline handling before model sees them.
+
+### SQL Dialect Auto-Fix
+WOZCODE rewrites common SQL mistakes before they reach the model:
+- Backtick identifiers → dialect-appropriate quoting (double quotes for Postgres)
+- Unquoted reserved word aliases → quoted
+- `COUNT(DISTINCT a, b)` → expanded (not all dialects support multi-column distinct)
+- `date_trunc("month", col)` → database-specific equivalents
+
+### Better Error Context
+When an error does reach the model, WOZCODE enriches it:
+- Failed edits expand stubs with actual file content
+- Real diff provided instead of "string not found"
+- Dialect-specific hints included
+
+## Integration Into Our Harness
+
+### Phase 12: Inline Syntax Validation (L3)
+Current: `grounding-check` validates spec compliance and state integrity.
+
+Add: `post-edit-validate` hook that runs immediately after each `edit` tool invocation:
+1. Run language-appropriate compiler/parser (NOT linter, NOT formatter)
+2. If errors → attempt auto-fix (SQL dialect only; type errors surfaced)
+3. If auto-fix fails → enrich error with context, return to model
+4. If success → proceed to next edit
+
+**Gate rule**: Inline validator MUST complete in <2 seconds. Full-project `tsc`, ESLint with plugins, and prettier are excluded — they belong in Phase 16.
+
+### Phase 16: Final Lint + Format Gate (post-L4)
+After L4 adversarial verification passes, a deterministic gate runs:
+1. Lint with auto-fix (ESLint, biome, ruff, clippy)
+2. Format with auto-apply (prettier, biome, rustfmt)
+3. Verify format didn't introduce lint violations
+4. Verdict: PASS / PASS_WITH_WARNINGS / FAIL
+
+See [[harness-implementation-plan#phase-16-final-lint-format-gate|Phase 16]] for full specification.
+
+### Layer 4: Adversarial Verification
+Current: Critic agents attack after all edits are complete.
+
+This remains unchanged — inline validation handles syntax errors; adversarial verification handles semantic/logic errors; final gate handles lint/format. The layers are complementary:
+- **Inline (L3/Phase 12)**: "Does it compile/parse?" (fast, tool-level, syntax only)
+- **Adversarial (L4)**: "Is it correct?" (slow, agent-level, semantic)
+- **Final Gate (Phase 16)**: "Is it clean?" (fast, deterministic, lint + format)
+
+### Supported Inline Validators (Phase 12 — Syntax Only)
+
+| Language/Format | Validator | Auto-Fix Scope |
+|-----------------|-----------|---------------|
+| TypeScript/JavaScript | `tsc --noEmit` (single file) | None (type errors surfaced to model) |
+| JSON | `JSON.parse` | Trailing commas, unquoted keys |
+| YAML | `yaml.parse` | None (structural errors surfaced) |
+| SQL | Dialect-specific parser | Backtick→quote, reserved words |
+| Python | `py_compile` (single file) | None (syntax errors surfaced) |
+| HTML | HTML parser | Unclosed tags |
+
+### Final Gate Tooling (Phase 16 — Lint + Format)
+
+These run ONCE after L4 verification passes. Never inline.
+
+| Language | Linter (auto-fix) | Formatter |
+|----------|-------------------|-----------|
+| TypeScript/JavaScript | `eslint --fix` or `biome check --fix` | `prettier --write` or `biome format --write` |
+| Python | `ruff check --fix` | `ruff format` |
+| Rust | `clippy --fix` | `rustfmt` |
+| JSON/YAML | `prettier --write` | `prettier --write` |
+| SQL | `sqlfluff fix` | `sqlfluff format` |
+
+## Token Savings Mechanism
+
+Each avoided retry saves a full API round-trip. For a session with 20 edits and a 10% inline catch rate, that's 2 avoided round-trips × (~8000 tokens per round-trip) = ~16,000 tokens saved. On a 5-subtask plan (our baseline ~83,500 overhead + coding), this represents ~15-20% overhead reduction.

package/vault/wiki/concepts/legendary-engineering-patterns-harness.md

@@ -0,0 +1,110 @@
+---
+type: concept
+title: "Legendary Engineering Patterns for AI Coding Harness"
+status: developing
+created: 2026-05-03
+tags: [harness, engineering, patterns, legendary-programmers]
+related:
+  - "[[Linus Torvalds]]"
+  - "[[Ken Thompson]]"
+  - "[[Dennis Ritchie]]"
+  - "[[Anders Hejlsberg]]"
+  - "[[Guido van Rossum]]"
+  - "[[Bjarne Stroustrup]]"
+  - "[[fast-feedback-loops]]"
+  - "[[unix-composability]]"
+  - "[[chain-of-trust-software]]"
+  - "[[subtractive-design]]"
+  - "[[behavioral-compatibility-over-purity]]"
+  - "[[pragmatic-language-design]]"
+sources:
+  - "[[linux-kernel-coding-workflow]]"
+  - "[[unix-philosophy]]"
+  - "[[birth-of-unix-kernighan-interview]]"
+  - "[[hejlsberg-7-learnings]]"
+  - "[[guido-python-design-philosophy]]"
+---
+
+# Legendary Engineering Patterns for AI Coding Harness
+
+Ten patterns distilled from the engineering workflows of Torvalds, Thompson, Ritchie, Stroustrup, Hejlsberg, and van Rossum — mapped to harness design.
+
+## 1. Fast Feedback Loops (Hejlsberg, Torvalds)
+
+**Source**: Turbo Pascal's instant compile-run, Linux's merge-window cadence.
+
+**Principle**: Developers experiment more and catch errors sooner when feedback is immediate. Slow feedback drives workarounds.
+
+**Harness Map**: The harness must provide instant lint/build feedback on AI-generated code. Every generated change should be testable within seconds. Pre-execution type checking, fast incremental compilation, and editor-integrated diagnostics are non-negotiable. Consider a "did this compile?" gate before diff presentation.
+
+## 2. Composability over Monoliths (Thompson, Ritchie, McIlroy)
+
+**Source**: Unix pipes — small programs that do one thing well, connected via text streams.
+
+**Principle**: "The power of a system comes more from the relationships among programs than from the programs themselves." (Kernighan)
+
+**Harness Map**: AI should generate small, composable modules — not giant files. The harness should decompose tasks into pipeline stages where specialized sub-agents handle one concern each. Pipes map to agent composition: type checker → linter → test runner → reviewer, each as a specialized gate.
+
+## 3. Chain of Trust (Torvalds)
+
+**Source**: Linux kernel maintainer hierarchy. Patches flow through subsystem maintainers before reaching Linus. Only ~1.3% chosen directly.
+
+**Principle**: No single reviewer can inspect everything. Trust scales through delegation to specialized reviewers.
+
+**Harness Map**: Tiered verification pipeline. Automated checks (lint, type-check, test) → specialized critic agents → human review for final sign-off. Each layer must be gating: if lint fails, don't waste critic tokens. The human is always the final gatekeeper.
+
+## 4. Subtractive Design (Thompson, McIlroy)
+
+**Source**: Bell Labs Unix Room culture: "What can we throw out? Why is there this option?"
+
+**Principle**: Additive-only development produces bloat. Good design actively removes what isn't needed.
+
+**Harness Map**: The harness should proactively suggest deletions and simplifications — not just additions. A "subtract" mode that analyzes existing code for dead paths, unnecessary abstractions, and redundant options. McIlroy's critique of Linux bloat is a warning for AI-generated code.
+
+## 5. Behavioral Compatibility over Purity (Hejlsberg, Stroustrup, Torvalds)
+
+**Source**: TypeScript extending JavaScript, C++ retaining C compatibility, Linux never breaking userspace.
+
+**Principle**: Improvements that respect existing workflows spread. Clean-slate rewrites rarely succeed. "Languages do not succeed because they are perfectly designed. They succeed because they accommodate the way teams actually work." (Hejlsberg)
+
+**Harness Map**: When modifying existing code, the harness must verify behavioral equivalence for unchanged paths. Fidelity gates: does the change preserve all existing test behavior? "Don't break userspace" as a mandatory harness layer.
+
+## 6. Pragmatism over Perfection (van Rossum)
+
+**Source**: Python as a skunkworks project. "Don't try for perfection because good enough is often just that."
+
+**Principle**: Ship working code. Optimize later. Perfectionism kills momentum.
+
+**Harness Map**: The harness should optimize for "correct enough" over "provably correct." Grounding checkpoints (L3) verify behavior, not formal proof. Spec-hardening (L1) prevents ambiguity, not all edge cases.
+
+## 7. Readability as First Principle (Torvalds, van Rossum, Kernighan)
+
+**Source**: Linux coding style ("comments say WHAT, not HOW"), Zen of Python ("readability counts"), Kernighan's lament about modern programming being "more like looking it up."
+
+**Principle**: Code is read far more than written. Style conventions reduce cognitive load.
+
+**Harness Map**: The harness must enforce readability conventions on AI output. Post-generation lint/style passes. Short functions. Descriptive names for exported symbols, short names for locals. "If the implementation is hard to explain, it's a bad idea" — applies equally to AI-generated code.
+
+## 8. Deep Understanding Enables Leverage (Thompson)
+
+**Source**: Thompson built Unix in 3 weeks and reverse-engineered a typesetter in hours because he understood the machine at every level.
+
+**Principle**: Deep system knowledge produces disproportionate output. Shallow tool usage produces shallow results.
+
+**Harness Map**: The harness must provide deep codebase understanding before code generation. Semantic indexing, call graphs, AST-level queries — the AI must "understand" the codebase the way Thompson understood the hardware. Context Engine (Augment) or equivalent is table stakes.
+
+## 9. Type Systems as AI Guardrails (Hejlsberg, Stroustrup)
+
+**Source**: Hejlsberg's 2026 insight: "The most valuable tools in an AI-assisted workflow aren't the ones that generate the most code, but the ones that constrain it correctly."
+
+**Principle**: In an AI world, deterministic tools (type checkers, linters, refactoring engines) become more important, not less. They provide the structure that allows AI output to be reviewed and validated.
+
+**Harness Map**: The harness must run deterministic constraint checks as mandatory gates before any human review. TypeScript strict mode. Rust borrow checker. Python mypy. These are not optional — they are the primary safety net against plausible-but-wrong AI output.
+
+## 10. Shared Context and Community (Thompson, Ritchie, Kernighan)
+
+**Source**: The Unix Room — shared physical space, shared source tree, `who` command showing who's logged in. "You changed it last, it's yours."
+
+**Principle**: Collaboration thrives on shared context and visibility. The best work happens when everyone can see what everyone else is doing.
+
+**Harness Map**: The wiki (persistent memory, L6) is the digital Unix Room. All design decisions, tradeoffs, and context must be visible and searchable. The harness must write its reasoning to the wiki, not just code to disk. Shared context across sessions enables compound improvement.