ultimate-pi 0.1.2 → 0.1.4

package/vault/wiki/sources/executor-rhyssullivan.md

@@ -0,0 +1,122 @@
+---
+type: source
+source_type: open_source_project
+title: "Executor — The Integration Layer for AI Agents"
+author: "Rhys Sullivan"
+date_published: 2026-04-25
+updated: 2026-05-01
+status: ingested
+url: "https://executor.sh"
+repo: "https://github.com/RhysSullivan/executor"
+confidence: high
+tags:
+  - agent-tools
+  - integration-layer
+  - tool-catalog
+  - typescript-execution-layer
+  - mcp
+  - sandbox
+  - policy-engine
+  - cross-agent
+key_claims:
+  - "Unified integration layer: one catalog, every agent, shared auth/policies/tools across Cursor, Claude Code, OpenCode"
+  - "Three eras framing: Era 1 tool calling (context bloat), Era 2 bash (poor permissions), Era 3 Executor (typed, sandboxed, shared)"
+  - "Source-agnostic plugin system: OpenAPI, GraphQL, MCP, gRPC, custom JSON schema — any source type"
+  - "Intent-based tool discovery: agents search by what they need, not memorized paths (tools.discover)"
+  - "Shared auth: sign in once, every agent shares credentials via local keychain"
+  - "Policy engine: auto-approve reads, pause on writes, wildcard rules, human-in-the-loop approval workflows"
+  - "Execution lifecycle with pause/resume: stateful executions that pause for auth/approval, resume via executor resume"
+  - "Local-first: secrets in OS keychain, nothing leaves machine. PGlite/Postgres persistence."
+  - "MCP server mode: point any MCP-compatible agent at Executor to share tool catalog, auth, and policies"
+  - "Bun monorepo architecture: apps/executor (CLI/server), apps/web (React UI), packages/ (core logic), plugins/ (source-specific)"
+  - "Sandbox: SES (Secure EcmaScript) or Deno subprocesses for isolation"
+  - "1.3K GitHub stars, 1,492 commits, MIT license"
+created: 2026-05-02
+
+---# Executor (RhysSullivan/executor)
+
+> Product site: [executor.sh](https://executor.sh) | Repo: [github.com/RhysSullivan/executor](https://github.com/RhysSullivan/executor)
+
+Executor is a **local-first integration layer** for AI agents. It gives agents a typed, sandboxed TypeScript runtime with a discoverable tool catalog spanning OpenAPI, GraphQL, MCP, and custom sources. The core insight: instead of loading every tool definition into the LLM's context window (Era 1) or giving agents raw bash access (Era 2), Executor provides a **typed runtime** where agents write code that calls typed functions (Era 3).
+
+## Product Positioning (from executor.sh)
+
+Executor positions itself as "Your missing execution layer" with three-era framing:
+
+| Era | Model | Problem |
+|-----|-------|--------|
+| **Era 1**: Tool calling | Every schema dumped into context | Tokens wasted, poor performance |
+| **Era 2**: Bash | Agent calls CLI directly | Poor permission model, pushes users to dangerously skip permissions |
+| **Era 3**: Executor | Agent → executor → typed tools | Typed, sandboxed, shared across all agents |
+
+Five pillars from landing page:
+1. **Unified catalog**: Every integration indexed into one typed, discoverable catalog
+2. **Shared auth**: Sign in once. Every agent shares credentials
+3. **Policies**: Auto-approve reads. Pause on writes. Wildcard rules.
+4. **Any agent via MCP**: Executor is an MCP server — point any agent at it
+5. **Local-first**: Secrets in keychain. Nothing leaves machine.
+
+## Architecture (from DeepWiki + GitHub README)
+
+### Monorepo Structure (Bun-powered)
+
+| Directory | Purpose | Key Packages |
+|-----------|---------|-------------|
+| `apps/` | Entrypoint applications | `executor` (CLI/Server), `web` (React UI) |
+| `packages/` | Core logic and SDKs | `@executor/platform-sdk`, `@executor/codemode-core`, `@executor/server` |
+| `plugins/` | Source-specific logic | `@executor/plugin-mcp-sdk`, `@executor/plugin-openapi-sdk` |
+| `examples/` | Integration demos | `sqlite-sdk-consumer`, `mcp-elicitation-demo` |
+
+### Key Components
+- **Server** (`@executor/server`): Hono-based HTTP server, REST API (`/v1`), MCP bridge (`/mcp`). `SqlControlPlaneRuntime` manages database and execution services
+- **CLI** (`apps/executor`): `executor web`, `executor mcp --stdio`, `executor call`, `executor tools search`, `executor resume`
+- **Web UI** (`apps/web`): React + Tailwind + Shadcn UI. Source management, tool explorer, secret management
+- **Persistence**: PGlite or local Postgres for workspace state, execution history, secrets
+- **Sandbox**: SES (Secure EcmaScript) or Deno subprocesses for isolation
+
+### Execution Lifecycle
+Executions are stateful and persisted. Key lifecycle phases:
+- `running` → tool execution in sandbox
+- `waiting_for_interaction` → paused for human to provide secret or approve action
+- `resumed` via `executor resume --execution-id <id>`
+
+### Tool System
+- **Source-agnostic plugin system**: OpenAPI, GraphQL, MCP, Google Discovery, custom JSON schema
+- **Automatic source detection**: Paste a URL → Executor detects type, indexes tools, handles auth
+- **Intent-based discovery**: `tools.discover({ query: "github issues", limit: 5 })` → returns typed paths
+- **Typed invocation**: `tools.github.issues.list({ owner: "vercel", repo: "next.js" })`
+
+## How Agents Use It
+
+```typescript
+// Discover tools by intent
+const matches = await tools.discover({ query: "github issues", limit: 5 });
+
+// Inspect schema
+const detail = await tools.describe.tool({ path: matches.bestPath, includeSchemas: true });
+
+// Call with type safety
+const issues = await tools.github.issues.list({ owner: "vercel", repo: "next.js" });
+```
+
+## Roadmap (from executor.sh)
+
+**Now**: Core SDK & CLI, MCP bridge, Policy engine, Local web UI, Desktop app
+**Soon**: Team management & SaaS, Advanced approval workflows, Org-wide source catalog
+**Later**: Customer-managed integrations, Workflow primitives (webhooks, crons), Virtual filesystems & KV stores, npm ecosystem support
+
+## Relevance to ultimate-pi Harness
+
+Executor is the closest reference implementation for our P43 TypeScript Execution Layer — but its scope is broader. Key intersections:
+
+| Executor Feature | Our Equivalent | Status |
+|-----------------|---------------|--------|
+| TS execution runtime | P43 `harness-ts-exec.ts` | Planned |
+| Tool catalog + discovery | Not planned (P43 has static type gen only) | **Gap** |
+| Policy engine + approval workflows | P35 Permission Subsystem | Planned (less rich) |
+| Shared auth across agents | Not addressed | **Gap** |
+| Cross-agent MCP server | P39 Harness as MCP Server | Planned |
+| Execution pause/resume | Not addressed | **Gap** |
+| Multi-source normalization | Not in scope (our tools are harness-native) | Different scope |
+
+**Build vs integrate decision**: Executor can be used as a dependency (MCP server mode + `executor call`). For external API integration (GitHub, Slack, Stripe), Executor is a strong candidate for integration rather than reimplementation. For harness-native tools (read, bash, edit, grep, ck_search), P43's custom TS runtime is still needed — but should borrow Executor's catalog/discovery/policy patterns.

package/vault/wiki/sources/fallow-rs-codebase-intelligence.md

@@ -0,0 +1,125 @@
+---
+type: source
+status: ingested
+source_type: github-repo
+title: "Fallow - Codebase Intelligence for TypeScript & JavaScript"
+author: "Bart Waardenburg (fallow-rs)"
+date_published: 2025
+date_fetched: 2026-05-01
+url: "https://github.com/fallow-rs/fallow"
+confidence: high
+tags:
+  - codebase-intelligence
+  - static-analysis
+  - dead-code
+  - duplication
+  - complexity
+  - rust
+  - typescript
+  - javascript
+  - harness-tool
+key_claims:
+  - "Fallow is NOT an AI assistant — it's the codebase truth layer coding agents call"
+  - "Rust-native, zero config, sub-second analysis. 91 framework plugins."
+  - "Detects dead code: unused files, exports, types, dependencies, circular deps, boundary violations"
+  - "Detects duplication: 4 modes (strict/mild/weak/semantic), suffix-array algorithm"
+  - "Complexity analysis: health scores, hotspots, refactor targets, per-file maintainability"
+  - "Architecture boundary enforcement presets: bulletproof, layered, hexagonal, feature-sliced"
+  - "Optional runtime intelligence: hot/cold path detection from V8 coverage (paid)"
+  - "MCP server for AI agent integration. JSON output with machine-actionable `actions` array per issue."
+  - "Audit mode for CI/CD: pass/warn/fail verdict. baselines for incremental adoption."
+  - "Benchmarked 5-41x faster than knip, 8-26x faster than jscpd"
+  - "1.7K GitHub stars, 31 forks, 151 releases (v2.58.0 as of May 2026)"
+  - "MIT licensed"
+related:
+  - "[[Research: Fallow Codebase Intelligence Harness Integration]]"
+  - "[[codebase-intelligence-harness-integration]]"
+  - "[[codebase-intelligence-ecosystem-comparison]]"
+created: 2026-05-02
+updated: 2026-05-02
+
+---# Fallow: Codebase Intelligence for TypeScript & JavaScript
+
+Rust-native static analysis tool for TS/JS codebases. Built by Bart Waardenburg (fallow-rs). 1.7K GitHub stars, MIT licensed, 151 releases. Sub-second analysis on projects up to 20K+ files (Next.js benchmark: 1.72s).
+
+## Core Capabilities
+
+### Dead Code Detection
+- Unused files, exports, types, enum/class members
+- Unused dependencies (package.json)
+- Circular dependencies (including cross-package in monorepos)
+- Boundary violations across layers/modules
+- Stale suppression comments
+- Private type leaks (opt-in API hygiene)
+- Per-file analysis (`--file src/utils.ts` for lint-staged integration)
+- Grouping by CODEOWNERS, directory, package, or GitLab CODEOWNERS section
+
+### Duplication Detection
+- Suffix-array algorithm (no quadratic pairwise comparison)
+- Four detection modes: strict (exact tokens), mild (AST-based, default), weak (different string literals), semantic (renamed variables)
+- Cross-directory and per-file scoping
+- Clone family grouping with `--trace src/file.ts:42`
+
+### Complexity Analysis
+- Health scores (0-100) with letter grades
+- Per-file maintainability index
+- Hotspot detection (git churn × complexity)
+- Refactoring targets ranked by effort (low/medium/high)
+- Static test coverage gaps
+- Angular template analysis included
+
+### Architecture Boundaries
+- Preset configurations: bulletproof, layered, hexagonal, feature-sliced
+- Zero manual config for boundary rules
+- `fallow list --boundaries` to inspect expanded rules
+
+### Runtime Intelligence (Optional, Paid)
+- Hot/cold path detection from V8 coverage dumps
+- Istanbul coverage-final.json integration
+- CRAP scoring (Change Risk Analysis and Predictions) with exact coverage data
+- Feature flag staleness detection
+- Cloud analysis via `fallow coverage analyze --cloud`
+
+## Agent Integration
+
+```
+npx fallow --format json
+npx fallow audit --format json
+npx fallow fix --dry-run --format json
+```
+
+- MCP server for Claude Code, Codex, Cursor, Windsurf
+- Agent Skill shipped in npm package
+- JSON output includes per-issue `actions` array with `auto_fixable` flag
+- Audit mode returns verdict: pass/warn/fail with machine-readable exit codes
+
+## Benchmarks (Apple M5, median of 5 runs with 2 warmups)
+
+| Project | Files | fallow | knip v6 | Speedup |
+|---------|-------|--------|---------|---------|
+| zod | 174 | 25ms | 330ms | 13x |
+| fastify | 286 | 27ms | 222ms | 8x |
+| preact | 244 | 200ms | 2.15s | 11x |
+| vue/core | 522 | 68ms | N/A | N/A |
+| TanStack/query | 901 | 330ms | 1.08s | 3.3x |
+| vite | 1,420 | 378ms | N/A | N/A |
+| svelte | 3,337 | 363ms | 714ms | 2x |
+| next.js | 20,416 | 1.72s | N/A | N/A |
+
+knip does not produce valid JSON for vite, vue/core, and next.js on benchmark fixtures.
+
+## Limitations
+
+- Syntactic analysis only: no type-level dead code detection
+- TS/JS only. No Python, Go, Rust, or Elixir support.
+- Runtime intelligence requires paid license
+
+## Relevance to ultimate-pi Harness
+
+Fallow is the **Phase 16 deterministic quality gate** and **P15b pre-verification sandbox tool** for our harness. It provides:
+1. Post-L4 lint-style gate with pass/warn/fail verdict (`fallow audit`)
+2. Pre-verification scoped to changed files (`fallow audit --changed-since main`)
+3. L5 observability substrate (health trends, complexity scores)
+4. P21 Keep Rate proxy (health snapshots over time)
+5. P29 error classification substrate (per-issue `actions` with `auto_fixable` flags)
+6. MCP server integration for L3 execution layer agent tool calling

package/vault/wiki/sources/fan2025-imad.md

@@ -0,0 +1,60 @@
+---
+type: source
+source_type: paper
+title: "iMAD: Intelligent Multi-Agent Debate for Efficient and Accurate LLM Inference"
+author: "Fan, Wei; Yoon, JinYi; Ji, Bo"
+date_published: 2025-11-14
+url: "https://arxiv.org/abs/2511.11306"
+confidence: medium
+key_claims:
+  - "Selective debate: only trigger multi-agent debate when likely beneficial"
+  - "41 linguistic features extracted from self-critique to predict debate benefit"
+  - "92% token reduction compared to always-debate"
+  - "13.5% accuracy improvement over single-agent"
+  - "Debate can overturn correct answers — not always beneficial"
+  - "Accepted at AAAI 2026 (Oral)"
+tags:
+  - multi-agent
+  - debate
+  - consensus
+  - token-efficiency
+created: 2026-04-30
+updated: 2026-04-30
+status: ingested
+
+---# iMAD: Intelligent Multi-Agent Debate
+
+Fan et al., AAAI 2026 (Oral).
+
+## Core Idea
+
+Multi-Agent Debate (MAD) is powerful but expensive. Triggering it for every query is inefficient — it may even degrade accuracy by overturning correct answers. iMAD selectively triggers debate only when likely to be beneficial.
+
+## Mechanism
+
+1. Single agent produces structured self-critique response
+2. Extract 41 interpretable linguistic and semantic features (hesitation cues)
+3. Lightweight debate-decision classifier (FocusCal loss) determines whether to trigger MAD
+4. No test dataset-specific tuning required
+
+## Results
+
+| Metric | Improvement |
+|--------|-------------|
+| Token reduction | Up to 92% |
+| Accuracy improvement | Up to 13.5% |
+| Generalization | Across 6 QA datasets, 5 baselines |
+
+## Key Insight
+
+> Debate can overturn correct single-agent answers. Selective routing is essential for both cost and accuracy.
+
+This directly challenges our consensus debate design (ADR-011, Phases 14-15), which currently assumes debate is always beneficial and always worth the token cost. iMAD suggests we need a **debate-gating classifier** that determines whether a given spec/plan/implementation NEEDS debate.
+
+## Relevance to Our Consensus Debate (Phases 14-15)
+
+Current ADR-011 design: debate always on for L1/L2/L4. iMAD suggests:
+
+1. **Pre-debate classifier**: Before spawning debate, single agent self-critiques. If confidence is high and no hesitation cues detected, skip debate entirely.
+2. **Token savings**: 92% token reduction on unnecessary debates — directly addresses ADR-011's ~13,000 token added cost.
+3. **Accuracy guard**: Classifier prevents debate from overturning correct answers.

package/vault/wiki/sources/forgecode-gpt5-agent-improvements.md

@@ -0,0 +1,63 @@
+---
+type: source
+source_type: blog
+title: "Benchmarks Don't Matter — Until They Do (Part 2)"
+author: Tushar Mathur (ForgeCode / Tailcall Inc.)
+date_published: 2026-03-16
+url: https://forgecode.dev/blog/gpt-5-4-agent-improvements/
+confidence: high
+key_claims:
+  - "ForgeCode reached 81.8% on TermBench 2.0 with both GPT 5.4 and Opus 4.6 — after model-specific harness adaptation"
+  - "GPT 5.4 is sensitive to field ordering in schemas: required before properties reduces malformed tool calls"
+  - "GPT 5.4 gets confused by nested schemas: flattening reduces structural errors"
+  - "GPT 5.4 needs in-band truncation signals (body text), cannot rely on metadata inference like Opus"
+  - "GPT 5.4 requires enforced verification gates — suggestions don't work; the model stops after plausible-but-incomplete solutions"
+  - "The difference is behavioral, not capability: same benchmark score when harness compensates"
+  - "The frontier is not better models — it's better harnesses for the models we already have"
+created: 2026-04-30
+updated: 2026-04-30
+status: ingested
+tags: [#source/blog, #agents, #benchmarks, #harness-design]
+---
+
+# Benchmarks Don't Matter — Until They Do (Part 2)
+
+Blog post by Tushar Mathur (ForgeCode) documenting how they reached #1 and #2 on TermBench 2.0 with two different models by adapting their agent harness to each model's specific failure modes.
+
+## Core Finding
+
+**Same benchmark score (81.8%), two different models, same harness — after model-specific adaptation.** The models didn't change. The harness did.
+
+## Four Fixes Applied
+
+### Fix 1: Field Ordering in Tool Schemas
+GPT 5.4 is sensitive to where fields appear in JSON. Moving `required` before `properties` reduced malformed tool calls. The model anchors on what it sees first. Same semantics, different reliability.
+
+### Fix 2: Flatten Nested Schemas
+GPT 5.4 gets confused by nested `required` arrays — mixing up which belongs to which object. Flat schemas (single object layer, single `required` array) eliminated this failure mode.
+
+### Fix 3: Make Truncation Impossible to Miss
+Opus 4.6 inferred truncation from `total_lines` metadata. GPT 5.4 missed that inference and proceeded as if it had the full file. Adding plain-text "... truncated N more lines" in the body fixed it.
+
+### Fix 4: Enforced Verification
+GPT 5.4 would implement a solution, sound confident, and stop — even when the task wasn't complete. Building a verification skill and **enforcing it programmatically** (not just suggesting) caught gaps before exit. This was the single biggest improvement.
+
+## Model Behavioral Differences
+
+| Behavior | Opus 4.6 | GPT 5.4 |
+|---|---|---|
+| Schema tolerance | Tolerates messy schemas | Needs clean ordering + flat structure |
+| Truncation | Infers from metadata | Needs explicit body-text signal |
+| Verification | Naturally double-checks | Must be enforced programmatically |
+| Completion | Self-aware of gaps | Stops after plausible solutions |
+
+**Key insight**: "Drop both models into the same harness and Opus looks easier to work with. Adapt the harness to GPT 5.4's actual failure modes and the gap disappears."
+
+## What Comes Next
+
+The frontier is not better models — it's:
+- Per-tool reliability tracking by model
+- Schema-shape evals before new tools ship
+- Verification-skill precision (when to enforce, when to skip)
+- Trajectory-level analysis of stop-vs-continue decisions
+- Provider-specific runtime defaults where failure modes differ

package/vault/wiki/sources/gemini-3-prompting-guide.md

@@ -0,0 +1,78 @@
+---
+type: source
+status: ingested
+source_type: official-documentation
+title: "Gemini 3 Prompting Guide"
+author: "Google Cloud"
+date_published: 2026-04-29
+date_fetched: 2026-05-01
+url: "https://docs.cloud.google.com/vertex-ai/generative-ai/docs/start/gemini-3-prompting-guide"
+confidence: high
+key_claims:
+  - "Temperature must stay at default 1.0 for Gemini 3 — lowering causes degraded performance"
+  - "Constraints (especially negative) must be placed at the END of the prompt"
+  - "Split-step verification prevents hallucination: verify capability → then generate"
+  - "Model treats assigned personas seriously and may ignore instructions to maintain persona"
+  - "Explicit grounding statement needed when working with hypothetical/ungrounded context"
+  - "Synthesis across multiple sources improved by placing questions at end with 'Based on the entire document above...'"
+  - "Gemini 3 is less verbose by default; must explicitly steer for conversational/chattier output"
+tags:
+  - prompting
+  - google
+  - gemini
+  - model-specific
+  - harness-design
+created: 2026-05-02
+updated: 2026-05-02
+
+---# Gemini 3 Prompting Guide
+
+Official prompting guide published by Google Cloud for Gemini 3 models on Vertex AI. Covers prompting strategies specific to Gemini 3's architecture and reasoning capabilities.
+
+## Critical Model-Specific Rules
+
+### Temperature Tuning
+- **DO NOT lower temperature below 1.0.** Gemini 3's reasoning is optimized for the default.
+- Changing temperature may cause unexpected behavior, looping, or degraded performance, especially for math/reasoning tasks.
+- This is a hard constraint — not a suggestion.
+
+### Prompt Structure
+- **Context and source material first**
+- **Main task instructions second**
+- **Negative, formatting, and quantitative constraints LAST**
+- The model may drop constraints (especially negative ones) if they appear too early.
+- "Place your core request and most critical restrictions as the final line."
+
+### Latency
+- Set thinking level to `LOW` for lower latency
+- Use system instructions like `think silently`
+
+### Preventing Hallucination
+- **Split-step verification**: Verify capability/information exists → then generate answer. Example: "Verify with high confidence if you're able to access the New York Times home page. If you cannot verify, state 'No Info' and STOP."
+- **Do not use broad negative constraints** like "do not infer" — these cause over-indexing and failure to perform basic logic.
+- Instead: "You are expected to perform calculations and logical deductions based strictly on the provided text. Do not introduce external information."
+
+### Persona Handling
+- Model treats assigned personas **very seriously**
+- May ignore other instructions to maintain persona adherence
+- Explicitly define persona boundaries: "You are a data extractor. You are forbidden from clarifying, explaining, or expanding terms."
+
+### Grounding
+- Model may revert to training data over provided context for hypothetical/unreal scenarios
+- When working with ungrounded context, explicitly state: "You are a strictly grounded assistant limited to the information provided in the User Context. Treat the provided context as the absolute limit of truth."
+- This must be an explicit, strong grounding statement — not implied.
+
+### Synthesizing Multiple Sources
+- Model may stop processing after first relevant match in large documents
+- Place specific instructions/questions at the END, after data context
+- Anchor reasoning: "Based on the entire document above, provide a comprehensive answer."
+- Explicitly ask to "Synthesize all relevant information from the text."
+
+### Output Verbosity
+- Gemini 3 defaults to less verbose, direct, efficient answers
+- For conversational/chatty output, must **explicitly** steer: "Explain this as a friendly, talkative assistant."
+
+### Distinguishing Deduction from External Info
+- Open-ended "do not infer" or "do not guess" causes over-indexing
+- Better: "Use the provided additional information or context for deductions and avoid using outside knowledge."
+- Distinguish between internal deduction (good) and external information injection (bad)

package/vault/wiki/sources/gh-cli-sub-issue-rfc.md

@@ -0,0 +1,50 @@
+---
+type: source
+status: ingested
+source_type: github-issue
+title: "gh CLI Feature Request: Parent Issues / Sub-Tasks Support"
+author: premun (cli/cli)
+date_published: 2025-01-23
+url: https://github.com/cli/cli/issues/10298
+confidence: high
+key_claims:
+  - "`gh` CLI does not currently support setting parent issues / sub-tasks on issue create/edit"
+  - "Feature request: --set-parent [ID] and --unset-parent [ID] flags on gh issue"
+  - "Linked to PR #13057 (in progress as of April 2026)"
+  - "Labeled: core (not accepting outside PRs), enhancement, gh-issue, needs-product"
+tags:
+  - github
+  - cli
+  - feature-request
+  - sub-issues
+related:
+  - "[[Research: GitHub Issues as Harness Spec Storage]]"
+  - "[[gh-sub-issue-extension]]"
+created: 2026-05-02
+updated: 2026-05-02
+
+---# gh CLI Feature Request: Parent Issues / Sub-Tasks
+
+Official feature request on `cli/cli` repo (44.2k stars) requesting native sub-issue support in `gh issue create` and `gh issue edit`.
+
+## Status
+
+- **Opened**: January 23, 2025
+- **Status**: Open (as of April 2026)
+- **Labels**: `core` (not accepting PRs from outside contributors), `enhancement`, `gh-issue`, `needs-product`
+- **PR**: [#13057](https://github.com/cli/cli/pull/13057) — linked, in development
+
+## Proposed Solution
+
+```bash
+# Create issue with parent
+gh issue create --title "..." --set-parent 123
+
+# Edit existing issue
+gh issue edit 456 --set-parent 123
+gh issue edit 456 --unset-parent
+```
+
+## Harness Impact
+
+When native support lands in `gh` CLI, the harness can drop the `gh-sub-issue` extension dependency and use `gh issue create --parent` directly. Until then, the extension or raw `gh api` GraphQL calls are required.

package/vault/wiki/sources/gh-sub-issue-extension.md

@@ -0,0 +1,72 @@
+---
+type: source
+status: ingested
+source_type: github-repo
+title: "gh-sub-issue: GitHub CLI Extension for Sub-Issues"
+author: yahsan2
+date_published: 2025
+url: https://github.com/yahsan2/gh-sub-issue
+confidence: high
+key_claims:
+  - "Community `gh` CLI extension for managing sub-issues (parent-child relationships)"
+  - "Supports add, create, list, remove operations on sub-issues"
+  - "Uses GitHub GraphQL API under the hood, not custom reference schemes"
+  - "Cross-repository support"
+  - "JSON output for machine readability"
+  - "110 stars, 35 commits, MIT license"
+  - "Non-destructive: links existing issues without closing or recreating them"
+tags:
+  - github
+  - cli
+  - sub-issues
+  - gh-extension
+related:
+  - "[[Research: GitHub Issues as Harness Spec Storage]]"
+  - "[[gh-cli-sub-issue-rfc]]"
+created: 2026-05-02
+updated: 2026-05-02
+
+---# gh-sub-issue: GitHub CLI Extension for Sub-Issues
+
+Community `gh` CLI extension (110 stars, MIT) bridging the gap where `gh` CLI lacks native sub-issue support.
+
+## Commands
+
+| Command | Purpose |
+|---------|---------|
+| `gh sub-issue add <parent> <child>` | Link existing issue as child of parent |
+| `gh sub-issue create --parent <id> --title "..."` | Create new child issue |
+| `gh sub-issue list <parent>` | List all children of a parent |
+| `gh sub-issue remove <parent> <child>` | Unlink child from parent |
+
+## Key Features
+
+- **JSON output**: `--json number,title,state,labels` for machine parsing
+- **Cross-repo**: `--repo owner/repo` to work across repositories
+- **Force remove**: `--force` to skip confirmation prompts
+- **Output formats**: TTY (colored), plain text, JSON
+- **Non-destructive**: Uses native GitHub sub-issue relationships, not custom reference schemes
+
+## Installation
+
+```bash
+gh extension install yahsan2/gh-sub-issue
+```
+
+Requirements: `gh` CLI 2.0.0+, GitHub account with repo write access.
+
+## Harness Integration
+
+This extension is the primary CLI tool for creating harness task sub-issues from L2 structured planning. Example harness workflow:
+
+```bash
+# Create spec issue
+SPEC_ID=$(gh issue create --title "Spec: Add user auth" --body "..." --label harness-spec,layer-1 --json number -q .number)
+
+# Create task sub-issues
+gh sub-issue create --parent $SPEC_ID --title "P1: Design DB schema" --label harness-task
+gh sub-issue create --parent $SPEC_ID --title "P2: Implement JWT tokens" --label harness-task
+
+# Check progress
+gh sub-issue list $SPEC_ID --json number,title,state
+```

package/vault/wiki/sources/github-fork-issues-discussion.md

@@ -0,0 +1,44 @@
+---
+type: source
+status: ingested
+source_type: github-discussion
+title: "GitHub Community: No Issues to Enable in Forked Repo"
+author: guangli-dai, tarak6984, secretnamebasis
+date_published: 2025-06-02
+url: https://github.com/orgs/community/discussions/161368
+confidence: high
+key_claims:
+  - "GitHub historically blocked enabling Issues on forked repositories independently"
+  - "As of June 2025, users reported no Issues checkbox in fork Settings > General > Features"
+  - "As of December 2025, a user confirmed Issues CAN be enabled on forks via Settings"
+  - "Workaround for older/restricted forks: create new repo, use Discussions, or external trackers"
+  - "Issue tracking is designed to be centralized in the original repo; forks are copies for contribution, not independent projects"
+tags:
+  - github
+  - fork
+  - issues
+  - multi-tenant
+related:
+  - "[[Research: GitHub Issues as Harness Spec Storage]]"
+created: 2026-05-02
+updated: 2026-05-02
+
+---# GitHub Community: Fork Issues Discussion
+
+GitHub Community discussion #161368 tracking the evolution of issue support on forked repositories.
+
+## Timeline
+
+| Date | Event |
+|------|-------|
+| Jun 2, 2025 | `guangli-dai` reports: No "Issues" checkbox in fork's Settings → Features |
+| Jun 3, 2025 | `tarak6984` confirms: "GitHub currently does NOT allow enabling Issues on forked repositories independently" |
+| Dec 30, 2025 | `secretnamebasis` reports: "Under /settings there is a way to check the issues box on a fork" — feature added |
+
+## Relevance to Harness
+
+Forks of ultimate-pi projects need their own issue tracker for spec storage. This discussion confirms:
+1. **Forks CAN now enable issues** (post-Dec 2025). No fundamental blocker.
+2. **Upstream issues are never copied** — each fork starts with a clean slate.
+3. **`gh` CLI must be reconfigured** for the fork's repo, not upstream.
+4. **Local cache isolation is critical** — `.pi/harness/specs/` must be gitignored to prevent stale upstream refs from leaking into forks.

package/vault/wiki/sources/github-issue-dependencies-docs.md

@@ -0,0 +1,49 @@
+---
+type: source
+status: ingested
+source_type: documentation
+title: "GitHub Issue Dependencies — Official Documentation"
+author: GitHub Docs
+date_published: 2025-04
+url: https://docs.github.com/en/issues/tracking-your-work-with-issues/using-issues/creating-issue-dependencies
+confidence: high
+key_claims:
+  - "Issue dependencies define blocked-by and blocking relationships between issues"
+  - "Dependencies are distinct from sub-issues — they define execution order, not decomposition"
+  - "Blocked issues show a Blocked icon on project boards and Issues page"
+  - "Available on Free, Pro, Team, and Enterprise Cloud plans"
+  - "Requires at least triage permissions"
+tags:
+  - github
+  - issues
+  - dependencies
+  - project-management
+related:
+  - "[[Research: GitHub Issues as Harness Spec Storage]]"
+  - "[[github-sub-issues-docs]]"
+created: 2026-05-02
+updated: 2026-05-02
+
+---# GitHub Issue Dependencies — Official Documentation
+
+GitHub's official documentation for issue dependencies (blocked-by / blocking relationships).
+
+## Key Capabilities
+
+- **Blocked by**: Mark an issue as dependent on another issue's completion
+- **Blocking**: Mark an issue as preventing another from progressing
+- **Visual indicators**: Blocked icon on project boards and Issues list
+- **Multiple dependencies**: An issue can be blocked by multiple issues, and block multiple issues
+
+## Distinction from Sub-Issues
+
+| Feature | Sub-Issues | Dependencies |
+|---------|------------|--------------|
+| Relationship | Parent-child (decomposition) | Blocked-by / blocking (ordering) |
+| Progress roll-up | Automatic (parent shows child completion %) | Manual (no auto-status from deps) |
+| Hierarchical limit | 8 levels deep | No depth limit (graph) |
+| Per-parent limit | 100 children | No limit |
+
+## Relevance to Harness
+
+L2 Structured Planning produces a task DAG. Dependencies map the DAG edges — "Task B cannot start until Task A completes." Sub-issues map the tree structure — "Spec S decomposes into Tasks A, B, C." Both are needed for full task topology.