ultimate-pi 0.1.0 → 0.1.3

package/vault/wiki/decisions/adr-021.md

@@ -0,0 +1,86 @@
+---
+type: decision
+title: "ADR-021: Explicit Command for Harness Activation"
+status: accepted
+priority: 1
+date: "2026-05-02"
+tags: [adr, harness, activation, command, explicit]
+sources:
+  - "[[HARNESS-PRD]]"
+related:
+  - "[[adr-012]]"
+  - "[[adr-017]]"
+supersedes:
+created: 2026-05-02
+updated: 2026-05-02
+---
+
+# ADR-021: Explicit Command for Harness Activation
+
+## Context
+
+The harness pipeline must not run on every user message. Simple queries ("what does git status do?") should bypass the pipeline. Three approaches were considered: explicit command, automatic task detection, and sub-agent routing.
+
+## Decision
+
+**Use an explicit command. Harness activates only via `/harness "task description"`.**
+
+### Command Registration
+
+The harness extension registers a `/harness` command via `pi.registerCommand()`:
+
+```
+/harness "fix the authentication bug in auth.ts"
+/harness "add rate limiting to the API endpoints"
+/harness "refactor the user model to use Zod validation"
+/harness --no-verify "quick fix"  (bypass L4 adversarial, P16 still runs)
+/harness --plan-only "implement caching"  (stop after L2, output plan)
+```
+
+### Flags
+
+| Flag | Effect |
+|------|--------|
+| (none) | Full pipeline: L1 → L2 → L2.5 → L3 → L4 → P16 |
+| `--no-verify` | Skip L4 adversarial verification. P16 still runs. |
+| `--plan-only` | Stop after L2 planning. Output plan, don't execute. |
+| `--skip-lint` | Skip P16 lint/format gate. |
+| `--model <model>` | Override model for this harness run. |
+
+### Lifecycle
+
+1. User types `/harness "task"` in pi
+2. Harness extension intercepts, blocks normal agent flow
+3. Runs L1 spec hardening (may call `harness_ask` for clarifications)
+4. Runs L2 planning (generates plan YAML, may trigger plan debate)
+5. Injects hardened spec + plan into agent's system prompt via `before_agent_start`
+6. L2.5 drift monitor activates for this session
+7. Agent executes L3 with grounding checkpoints
+8. L4 critic spawns via pi-subagents RPC
+9. P16 runs deterministic gates
+10. Results returned to user
+
+Normal `/harness`-less chat bypasses all pipeline layers entirely.
+
+## Rationale
+
+- **Explicit user intent**: User knowingly opts into harness overhead. No surprise token costs.
+- **Clean separation**: Normal chat = fast, lean. Harness = formal, verified.
+- **Flag-based flexibility**: `--plan-only` enables plan-then-execute workflow. `--no-verify` for quick fixes.
+- **Matches pi philosophy**: pi has no built-in pipeline. `/harness` command follows pi's extension command pattern.
+
+## Consequences
+
+### Positive
+- No false positives from automatic detection.
+- User controls pipeline depth per task.
+- Simple mental model: type `/harness` when you want formal verification.
+
+### Negative
+- User must remember to use `/harness`. Easy to accidentally bypass.
+- Adds friction for frequent harness users. Mitigated by shell aliases or pi prompt templates.
+
+### Mitigations
+- Pi prompt templates: `/harness` can be aliased to `/h`.
+- `AGENTS.md` can recommend harness for code changes.
+- Future: optional automatic detection via config (`harness.autoDetect: true`).

package/vault/wiki/decisions/adr-022.md

@@ -0,0 +1,113 @@
+---
+type: decision
+title: "ADR-022: Drift Monitor Pattern Definitions and Turn-Dependent Thresholds"
+status: accepted
+priority: 1
+date: "2026-05-02"
+tags: [adr, harness, l2.5, drift-monitor, thresholds, ck-search]
+sources:
+  - "[[HARNESS-PRD]]"
+  - "[[adr-018]]"
+  - "[[adr-020]]"
+related:
+  - "[[adr-018]]"
+supersedes:
+created: 2026-05-02
+updated: 2026-05-02
+---
+
+# ADR-022: Drift Monitor Pattern Definitions and Thresholds
+
+## Context
+
+L2.5 runtime drift monitor detects agent stuckness via 7 rule-based patterns (6 original + 1 added). Detection runs on every `tool_result` event via a sliding window of the last 20 tool calls. Thresholds are configurable in `.pi/harness/config.json`.
+
+## Decision
+
+### Pattern Definitions
+
+#### 1. Repetition Loops
+- **Detection**: Same tool name + same arguments ≥ N times in a row
+- **Threshold**: 3
+- **Nudge**: "You appear to be repeating the same action. Consider a different approach."
+- **Reset on**: Tool call with different args
+
+#### 2. Failure Spirals
+- **Detection**: Consecutive tool calls returning error/non-zero exit
+- **Threshold**: 3
+- **Nudge**: "Multiple tool calls are failing. Stop and reassess your approach."
+- **Reset on**: Successful tool call
+
+#### 3. Tool Cycling
+- **Detection**: Alternating between 2-3 tools without any write/edit in K turns
+- **Threshold**: 5 turns
+- **Nudge**: "You're cycling between tools without making changes. Act on findings."
+- **Reset on**: Write or edit call
+
+#### 4. Silence/Batching (Turn-Dependent)
+- **Detection**: Agent reads/greps/finds many files without write/edit/bash (modifying)
+- **Thresholds**:
+  | Turn Range | Threshold | Rationale |
+  |------------|-----------|-----------|
+  | Turns 1-8 | No limit | Exploration phase. Read freely. |
+  | Turns 9-15 | 12 reads without action | Should transition from exploring to doing. |
+  | Turns 16+ | 6 reads without action | Analysis paralysis. Agent has enough context. |
+- **Nudge style by severity**:
+  - Turns 9-15: "You've read 12 files without making changes. If you're still mapping the codebase, ignore. If ready, act."
+  - Turns 16+: "You're deep in exploration. Summarize findings and act."
+- **Reset on**: Write, edit, or modifying bash call
+- **"Action" definition**: write, edit, or bash that modifies filesystem (not `ls`/`cat`/`echo`)
+
+#### 5. Rework
+- **Detection**: Editing the same file or overlapping region ≥ N times
+- **Threshold**: 2 edits on same file region
+- **Nudge**: "You've edited this region multiple times. Reassess approach."
+- **Reset on**: Edit on different file or region
+
+#### 6. Excessive Search
+- **Detection**: ≥ N consecutive grep/find calls without narrowing queries or finding results
+- **Threshold**: 8 searches
+- **Nudge**: "Consider narrowing your search or using a different approach."
+- **Reset on**: Read or edit after a grep/find that found results
+
+#### 7. Obsolete Search (ck routing)
+- **Detection**: ≥ 3 grep/find calls in a row where query is a natural-language phrase (≥ 3 words)
+- **Nudge**: "For semantic searches like 'find authentication logic', try ck_search instead of grep."
+- **Reset on**: Successful ck call or narrowing to single-word grep
+
+### Escalation Ladder
+
+| Level | Trigger | Action |
+|-------|---------|--------|
+| Soft nudge | First detection | Inject correction prompt into next `before_agent_start` |
+| Strong nudge | Same pattern re-detected after nudge | Stronger language. "STOP. You are stuck. Reassess." |
+| Forced restart | Pattern persists after strong nudge | Inject "RESTART: Clear your mental model. Re-read spec. Start fresh." + reset pattern counters |
+
+Escalation thresholds configurable. Default: soft at 1 detection, strong at 2 consecutive, restart at 3.
+
+### Config
+
+All thresholds configurable in `.pi/harness/config.json` → `driftMonitor.patterns` and `driftMonitor.escalation`.
+
+## Rationale
+
+- **Turn-dependent batching**: First 8 turns are exploration — penalizing reads here would break legitimate codebase mapping. After turn 16, continued reading signals paralysis.
+- **ck routing**: Grep for semantic queries is an anti-pattern. Nudging toward ck_search saves tokens and improves code discovery.
+- **Sliding window**: Last 20 tool calls is ~4-8 turns of context. Enough to detect patterns, small enough to be responsive.
+- **Configurable**: Every project has different exploration needs. Per-project thresholds prevent false positives.
+
+## Consequences
+
+### Positive
+- Catches 7 distinct stuckness patterns.
+- Escalation prevents infinite loops.
+- Turn-dependent thresholds balance exploration vs paralysis detection.
+- ck routing improves code discovery.
+
+### Negative
+- 20-call sliding window adds memory overhead (minimal — ~2KB state).
+- Turn counting assumes pi doesn't reset turn counter mid-session (verified: pi maintains monotonic turn count).
+
+### Mitigations
+- User can disable drift monitor entirely via config or `/harness --no-drift-monitor`.
+- Pattern counters reset on successful write/edit — productive work clears drift state.

package/vault/wiki/decisions/adr-023.md

@@ -0,0 +1,113 @@
+---
+type: decision
+title: "ADR-023: Hybrid Spec Format — Structured + Freeform Acceptance Criteria"
+status: accepted
+priority: 1
+date: "2026-05-02"
+tags: [adr, harness, l1, spec, yaml, acceptance-criteria]
+sources:
+  - "[[HARNESS-PRD]]"
+  - "[[adr-020]]"
+related:
+  - "[[adr-020]]"
+  - "[[adr-021]]"
+supersedes:
+created: 2026-05-02
+updated: 2026-05-02
+---
+
+# ADR-023: Hybrid Spec Format — Structured + Freeform Acceptance Criteria
+
+## Context
+
+L1 spec hardening must produce a content-addressed specification that L2 (planning), L3 (execution), and L4 (adversarial verification) can all consume. The spec must support both deterministic auto-verifiable criteria (tests pass, lint passes) and freeform criteria (security properties, behavioral guarantees) that require LLM judgment.
+
+## Decision
+
+**Use a hybrid YAML format with structured deterministic criteria and freeform acceptance criteria.**
+
+### Schema
+
+`.pi/harness/specs/<sha256-hash>.yaml`:
+
+```yaml
+request: "Fix the authentication timeout bug in auth.ts"
+ambiguities:
+  - question: "Which auth library is used?"
+    answer: "JWT in src/auth.ts — existing."
+    resolved_by: "user"
+  - question: "Must the fix be backward compatible?"
+    answer: "Yes. Cannot change token format."
+    resolved_by: "user"
+intent: "JWT tokens expire prematurely because the TTL calculation uses seconds instead of milliseconds"
+scope:
+  include: ["src/auth.ts", "src/middleware/auth.ts"]
+  exclude: ["src/auth/__tests__/*"]
+constraints:
+  - "Must be backward compatible with existing tokens"
+  - "Must not change the API surface of verifyToken()"
+  - "Must handle edge case: tokens issued before the fix"
+acceptance_criteria:
+  deterministic:
+    - type: tests_pass
+      pattern: "auth/**"
+    - type: lint_passes
+    - type: typescript_compiles
+    - type: no_regression
+      baseline: "main"
+  freeform:
+    - "Tokens issued with the old TTL (seconds) must still validate"
+    - "New tokens must use the correct TTL (milliseconds)"
+    - "No new security vulnerabilities introduced"
+    - "The fix must be contained to auth.ts — no changes to unrelated files"
+model: anthropic/claude-sonnet-4-6
+hardened_at: "2026-05-02T14:30:00Z"
+clarification_rounds: 1
+```
+
+### Field Definitions
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `request` | Yes | Original user request (verbatim) |
+| `ambiguities` | No | Resolved ambiguities with source (user/auto) |
+| `intent` | Yes | One-sentence distilled intent after hardening |
+| `scope` | No | Files/directories in and out of scope |
+| `constraints` | No | Non-negotiable constraints |
+| `acceptance_criteria.deterministic` | No | Auto-verifiable criteria (L3, P16) |
+| `acceptance_criteria.freeform` | Yes | LLM-judged criteria (L4 critic) |
+| `model` | Yes | Model that generated the spec |
+| `hardened_at` | Yes | Timestamp |
+| `clarification_rounds` | Yes | How many Q&A rounds were needed |
+
+### Spec Hash
+
+`SHA256` of the canonical YAML serialization (sorted keys, consistent indentation). Immutable after `hardened_at` timestamp. Any spec change = new hash = new file.
+
+### Enforcement
+
+- L3: checks deterministic criteria at each grounding checkpoint. Auto-verifies via `vitest`, `biome check`, `tsc --noEmit`.
+- L4: critic reads freeform criteria as its attack surface. Critic's pass/fail judgment is based on freeform criteria compliance.
+- P16: runs deterministic gates regardless of L4 outcome.
+
+## Rationale
+
+- **Hybrid = complete**: Deterministic criteria catch syntax/type/test failures without LLM cost. Freeform criteria catch semantic issues that only an LLM can judge.
+- **Both required**: If only deterministic criteria, security and behavioral bugs slip through. If only freeform, every verification burns LLM tokens.
+- **Content-addressed**: Spec is immutable after hardening. No scope creep. L4 critic verifies against the same spec that L1 produced.
+- **Resolved ambiguities recorded**: Trail of Q&A decisions prevents re-litigation.
+
+## Consequences
+
+### Positive
+- Single ground truth for L2, L3, L4.
+- Immutable spec prevents scope creep.
+- Q&A trail provides audit log of clarifications.
+
+### Negative
+- Freeform criteria depend on L4 critic availability. During Groups 1-2 (before L4), freeform criteria are unchecked.
+- Spec YAML can become large for complex tasks.
+
+### Mitigations
+- During Groups 1-2, only deterministic criteria enforced. Freeform criteria stored but skipped.
+- Spec files are gitignored (`.pi/harness/specs/`). Not committed. Re-built per harness run.

package/vault/wiki/decisions/adr-024.md

@@ -0,0 +1,73 @@
+---
+type: decision
+title: "ADR-024: Compact Plan Summary in System Prompt"
+status: accepted
+priority: 1
+date: "2026-05-02"
+tags: [adr, harness, l2, plan, system-prompt, context]
+sources:
+  - "[[HARNESS-PRD]]"
+  - "[[adr-020]]"
+  - "[[adr-023]]"
+related:
+  - "[[adr-020]]"
+  - "[[adr-023]]"
+supersedes:
+created: 2026-05-02
+updated: 2026-05-02
+---
+
+# ADR-024: Compact Plan Summary in System Prompt
+
+## Context
+
+L2 generates a detailed YAML plan (ADR-020). The agent must follow it during L3 execution. Injecting the full plan into the system prompt burns context tokens on every turn. Storing it only on disk risks the agent losing track of the plan.
+
+## Decision
+
+**Inject a compact summary into the system prompt. Full plan YAML on disk. Agent instructed to re-read at checkpoints.**
+
+### Summary Format (in system prompt)
+
+```
+TASK PLAN → .pi/harness/plans/<hash>.yaml
+  1. add-user-model [CHECKPOINT] ← no deps
+  2. add-auth-middleware ← after add-user-model
+  3. add-rate-limiting ← after add-auth-middleware [CHECKPOINT]
+
+CONTRACT: Complete tasks in order. Do not skip checkpoints.
+At each [CHECKPOINT], re-read plan YAML and verify doneCriteria
+before proceeding to next task.
+```
+
+### Agent Instructions
+
+Appended to system prompt:
+- Read plan YAML before starting work
+- Execute tasks in dependency order
+- At each checkpoint: re-read plan YAML, verify all `doneCriteria` for completed tasks
+- If stuck or uncertain about next step: re-read plan YAML
+- Do not work on future tasks before current task's `doneCriteria` are met
+
+### L2.5 Drift Integration
+
+Drift monitor (ADR-022) adds pattern #8: **plan deviation**. Detected when agent edits files outside current task scope or works on tasks out of dependency order. Nudge: "You're working outside the current plan task. Re-read plan and refocus."
+
+## Rationale
+
+- **Minimal context burn**: 3-5 lines per plan in system prompt vs potentially hundreds of lines of full YAML.
+- **Agent autonomy**: Agent decides when to re-read the plan. Not forced to hold it in context at all times.
+- **Checkpoint enforcement**: Re-reading at checkpoints ensures the agent re-grounds before proceeding.
+- **Drift integration**: Plan deviation detection catches scope creep early.
+
+## Consequences
+
+### Positive
+- Context-efficient. Plan details don't consume tokens on every turn.
+- Agent has access to full plan details when needed.
+- Drift monitor catches plan deviation.
+
+### Negative
+- Agent must be trusted to re-read the plan. Lazy agents may skip re-reading.
+- Plan YAML file path is in system prompt — agent could accidentally edit it. Mitigated by file permissions or drift detection.
+- Summary format is lossy — task descriptions and criteria details only in YAML file.

package/vault/wiki/decisions/adr-025.md

@@ -0,0 +1,130 @@
+---
+type: decision
+title: "ADR-025: GitHub Issues as Sole Spec Storage + harness-setup Bootstrap"
+status: accepted
+priority: 1
+date: "2026-05-02"
+tags: [adr, harness, specs, github-issues, storage, setup]
+sources:
+  - "[[HARNESS-PRD]]"
+  - "[[adr-023]]"
+  - "[[adr-021]]"
+related:
+  - "[[adr-023]]"
+  - "[[adr-021]]"
+supersedes: "PRD P1.4 (dual-tier local + GitHub Issues)"
+created: 2026-05-02
+updated: 2026-05-02
+---
+
+# ADR-025: GitHub Issues as Sole Spec Storage + harness-setup
+
+## Context
+
+PRD P1.4 specified dual-tier spec storage: local `.pi/harness/specs/<hash>.json` cache + GitHub Issue for cross-session ledger. Local cache adds complexity and two sources of truth. GitHub Issues alone provides a single source of truth with built-in cross-session durability, issue numbers as IDs, and no local file management.
+
+P2b (iMAD pre-debate gating classifier) was considered for Group 1 but is deferred until L4 debate infrastructure exists (Group 3).
+
+## Decision
+
+**Use GitHub Issues as the sole spec storage. No local cache. If GitHub is unreachable, harness fails with clear error.**
+
+### Issue Format
+
+Each harness spec is a GitHub Issue in the project's repository, using a custom issue template.
+
+Issue body contains the spec YAML (ADR-023) in a markdown code block:
+
+```markdown
+## Spec
+
+\`\`\`yaml
+request: "Fix the authentication timeout bug in auth.ts"
+intent: "JWT tokens expire prematurely..."
+acceptance_criteria:
+  deterministic:
+    - type: tests_pass
+      pattern: "auth/**"
+  freeform:
+    - "Tokens issued with old TTL must still validate"
+...
+\`\`\`
+```
+
+### Issue Template
+
+`.github/ISSUE_TEMPLATE/harness-spec.yml`:
+
+```yaml
+name: Harness Spec
+description: Auto-generated hardened spec from pi harness
+title: "harness: [spec title]"
+labels: ["harness", "spec"]
+body:
+  - type: textarea
+    attributes:
+      label: Spec
+      description: Hardened specification (auto-generated)
+      render: yaml
+    validations:
+      required: true
+```
+
+### Storage Model
+
+- **Spec ID**: GitHub issue number (replaces SHA256 hash as stable ID)
+- **Issue title**: `harness: <intent truncated to 80 chars>`
+- **Issue labels**: `harness`, `spec`, plus status labels (`in-progress`, `verified`, `failed`)
+- **Issue close**: Closed when task completes (L4 verdict + P16 pass). Comment with verdict summary.
+- **Issue reopen**: If L4 fails and agent retries, same issue gets reopened.
+
+### Failure Mode
+
+If GitHub API is unreachable (no network, rate limited, token expired):
+- Harness fails immediately with: "GitHub API unreachable. Spec storage requires GitHub connectivity."
+- User sees clear error, not a crash.
+- No offline mode. No local fallback.
+
+### harness-setup Command
+
+One-time bootstrap registered as a pi command:
+
+```
+/harness-setup
+```
+
+Runs the following checklist interactively:
+
+| Step | Action | Confirm? |
+|------|--------|----------|
+| 1. Install sub-agents | `pi install npm:@tintinweb/pi-subagents` | Auto |
+| 2. Create wiki vault | Invoke `/wiki` prompt template (ensures `wiki/`, `vault/` exist) | Auto |
+| 3. Create issue template | Write `.github/ISSUE_TEMPLATE/harness-spec.yml` | User confirm |
+| 4. Create harness config | Generate `.pi/harness/config.json` from defaults | Auto |
+| 5. Create critic agent | Write `.pi/agents/critic.md` with L4 critic definition | Auto |
+| 6. Verify firecrawl | Check CLI, prompt install if missing | Auto |
+| 7. Verify defuddle | Check CLI, prompt install if missing | Auto |
+| 8. Verify GitHub | `gh auth status`, prompt login if missing | Auto |
+| 9. Create consensus dir | `mkdir -p wiki/consensus/` | Auto |
+
+## Rationale
+
+- **Single source of truth**: No sync between local cache and remote. GitHub IS the store.
+- **Cross-session durable**: Issues survive between sessions, machines, forks.
+- **Built-in IDs**: Issue numbers are stable, sequential, human-friendly identifiers.
+- **Labels as state**: Issue labels track spec lifecycle without custom database.
+- **Fail-fast**: No offline fallback. Forces clean failure instead of silent divergence.
+
+## Consequences
+
+### Positive
+- Zero local storage management.
+- Specs visible in GitHub UI for human review.
+- Issue labels enable filtering: "show all verified harness specs."
+- Cross-session without any persistence layer.
+
+### Negative
+- **Network dependency**: No offline work. Harness won't function without GitHub.
+- **Rate limits**: GitHub API has rate limits (5,000/hr authenticated). Harness spec operations are low-volume (1-2 per session), well within limits.
+- **No local caching**: Even a transient network blip blocks harness. Mitigated by clear error message.
+- **Issue noise**: Harness specs will appear in the project's GitHub Issues alongside bugs and features. Mitigated by `harness` label for filtering.

package/vault/wiki/decisions/adr-026.md

@@ -0,0 +1,56 @@
+---
+type: decision
+title: "ADR-026: Replace CLI Cursor Provider with Native Cursor SDK Provider"
+status: accepted
+priority: 1
+date: "2026-05-04"
+tags: [adr, provider, cursor, sdk, pi]
+sources:
+  - "https://pi.dev/docs/latest/custom-provider"
+  - "https://cursor.com/docs/api/sdk/typescript"
+related:
+  - "[[adr-012]]"
+created: 2026-05-04
+updated: 2026-05-04
+---
+
+# ADR-026: Replace CLI Cursor Provider with Native Cursor SDK Provider
+
+## Context
+
+Current setup used `npm:@netandreus/pi-cursor-provider`, which wrapped Cursor CLI calls.
+That path was brittle and not purely programmatic.
+
+Project needs clean provider integration through Pi `registerProvider(..., streamSimple)` and Cursor TypeScript SDK.
+
+## Decision
+
+Use repo-local extension `.pi/extensions/cursor-sdk-provider.ts`.
+
+- Register provider name: `cursor-sdk`
+- Implement `streamSimple` using `@cursor/sdk` (`Agent.create`, `agent.send`, `run.stream`, `run.wait`)
+- Remove `npm:@netandreus/pi-cursor-provider` from `.pi/settings.json`
+- Keep auth via `CURSOR_API_KEY`
+
+## Alternatives considered
+
+1. Keep external CLI package
+   - Rejected: CLI indirection, less control, hacky behavior.
+2. Keep external package but fork it
+   - Rejected: extra maintenance for little gain.
+
+## Rationale
+
+Cursor SDK gives stable programmatic API, event stream access, and direct TypeScript types.
+Pi custom-provider API supports this natively through `streamSimple`.
+
+## Consequences
+
+### Positive
+- Cleaner architecture
+- No CLI shell glue
+- Local code ownership of provider behavior
+
+### Negative
+- Must maintain local provider extension on future SDK changes
+- Initial model defaults may need tuning per team account/model availability

package/vault/wiki/decisions/colocate-wiki.md

@@ -0,0 +1,34 @@
+---
+type: decision
+status: active
+priority: 2
+date: "2026-04-28"
+owner: "aryaniyaps"
+due_date: ""
+context: "Should the architecture wiki be co-located in the same repository as the application source code?"
+tags: [decision, architecture, documentation]
+created: "2026-04-28"
+updated: "2026-04-28"
+title: "Co-locating Wiki with Codebase"
+---
+# Co-locating Wiki with Codebase
+
+## Context
+Deciding whether to store the codebase map and architecture wiki inside the source repository or in a separate documentation vault.
+
+## Options Considered
+1. **Co-location (Monorepo approach)**: Wiki lives in `wiki/` and `CLAUDE.md` in the root.
+2. **Separate Vault**: Codebase is purely code; wiki is an isolated Obsidian vault elsewhere.
+
+## Decision
+**Option 1: Co-location.**
+
+## Rationale
+- **Proximity**: Developers can update code and architecture documentation in the same commit, preventing the wiki from becoming stale (the "doc rot" problem).
+- **Tooling Integration**: Agent skills (`wiki`, `wiki-ingest`) can seamlessly traverse the codebase and cross-reference real files because they share the same filesystem context.
+- **Git as Single Source of Truth**: Branching, PR reviews, and versioning apply to code and its architectural reasoning simultaneously.
+
+## Consequences
+- The repository clone size slightly increases (markdown is negligible, but attachments/images could add up).
+- Non-code contributors (if any) need git access to update documentation.
+- We must enforce policies (e.g., `.gitignore` rules or pre-commit hooks) so that generated wiki artifacts don't interfere with the build process.

package/vault/wiki/entities/Anders Hejlsberg.md

@@ -0,0 +1,29 @@
+---
+type: entity
+entity_type: person
+title: "Anders Hejlsberg"
+role: "Creator of Turbo Pascal, Delphi, C#, TypeScript"
+active: true
+tags: [person, language-design, typescript, csharp, microsoft]
+related:
+  - "[[hejlsberg-7-learnings]]"
+  - "[[fast-feedback-loops]]"
+  - "[[behavioral-compatibility-over-purity]]"
+---
+
+# Anders Hejlsberg
+
+Creator of Turbo Pascal (Borland, 1983), Delphi (1995), lead architect of C# (Microsoft, 2000), and designer of TypeScript (2012). Self-taught compiler writer. Still writes code daily — "my calling is writing code."
+
+## Engineering Practices
+
+- **Fast feedback as first principle**: Turbo Pascal's impact came from shortening edit-compile-run to instants. TypeScript's value equally from tooling responsiveness as from the type system.
+- **Stay hands-on**: Discovered hash tables from a book while writing Turbo Pascal 2.0 — doubled compiler speed. Wrote the TypeScript type checker core himself. "I treated work as the place where I wouldn't work and then I go home and work."
+- **Compromise over purity**: TypeScript extended JavaScript instead of replacing it. C# merged VB6 ease with C++ power. "Languages do not succeed because they are perfectly designed. They succeed because they accommodate the way teams actually work."
+- **Behavioral compatibility**: When porting TypeScript compiler to Go, the goal was semantic fidelity — "the new compiler needed to behave exactly like the old one, including quirks and edge cases."
+- **Open development**: 2014 move to GitHub was TypeScript's turning point. "Our entire workflow is in the open... no secrets on this project."
+- **On AI coding**: Grounding/constraint matters more than generation. Type systems and refactoring tools become essential guardrails. "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."
+
+## Relevance to AI Coding Harness
+
+Hejlsberg's career is the strongest bridge between legendary programming and AI-assisted development. His 7 learnings (2026 GitHub blog) directly address AI coding workflow: fast feedback matters most, behavioral compatibility over purity, visibility builds trust, and deterministic constraints (type checkers, linters) as guardrails around AI output. The idea that "grounding matters more than generation" is a direct harness design principle.

package/vault/wiki/entities/Anthropic.md

@@ -0,0 +1,17 @@
+---
+type: entity
+status: stub
+created: 2026-05-02
+updated: 2026-05-02
+tags: [entity, ai-lab]
+---
+
+# Anthropic
+
+AI research company. Creator of Claude (Opus, Sonnet, Haiku models) and the Claude Code agentic coding tool.
+
+## Relevance to Harness
+
+- [[anthropic-prompt-best-practices]] — official prompting guidance
+- [[anthropic2026-harness-design]] — GAN-inspired generator-evaluator architecture
+- [[claude-code-architecture-vila-lab-2026]] — Claude Code architecture analysis