@flyingrobots/graft 0.7.1 → 0.9.0

package/CHANGELOG.md

@@ -7,6 +7,208 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.9.0] - 2026-06-10
+
+### Added
+
+- **Fake Echo-shaped TypeScript witness**: Graft proves its Echo-facing seam
+  before any real Echo runtime exists. The canonical schema gains its first
+  Intent (`recordGitWarpImportBatch`), Wesley 0.0.5 emits LE-binary var
+  codecs (`src/generated/graft-structural-history.codec.generated.ts`), and
+  a new app-safe stack — `EchoKernelTransport` byte seam, EINT v1 +
+  canonical-CBOR envelope codec, typed structural-history client, and an
+  Echo-backed `StructuralReadingPort` adapter mapping Echo's
+  `ContractObstructionKind` taxonomy into Graft freshness/residual posture —
+  is exercised end to end by a deterministic fake transport. The fake
+  mirrors Echo's wire-level authority enforcement (`FORBIDDEN_CONTROL_INTENT`
+  for the reserved control op id), and guard tests keep the Echo adapter out
+  of production contexts. No public surface changes.
+- **Structural-history Echo package descriptor**: Graft now carries a
+  deterministic descriptor for the structural-history package it expects Echo
+  to host later, with repo-root-relative schema and generated-artifact
+  identities, descriptor-only Echo posture, and a local drift check wired into
+  `pnpm schema:structural-history:check`.
+- **Structural history schema authority**: Graft now carries a canonical
+  `schemas/graft-structural-history.graphql` schema with Wesley-generated
+  TypeScript contracts and a deterministic artifact drift check, establishing
+  the schema-first Echo migration boundary without changing Echo or Wesley.
+- **Structural source span invariants**: The canonical structural-history schema
+  now rejects source spans whose end offsets or present end lines precede their
+  starts.
+- **Opened workspace paths**: MCP sessions can now call `workspace_open` to
+  open another git worktree path, activate it by default, and inspect opened
+  paths through `workspace_list_opened` without adding per-tool `cwd` routing.
+- **Symbol history locations**: `graft_blame` and `graft symbol history`
+  now carry per-version path and available line-range facts from WARP symbol
+  timelines without adding a second `code_show` history response shape.
+
+### Changed
+
+- **Structural history generation gate**: `pnpm schema:structural-history:check`
+  now requires a configured Wesley CLI, verifies the pinned CLI version and L1
+  registry hash, regenerates the TypeScript artifact from GraphQL, and
+  byte-compares it with the committed generated file. CI and release workflows
+  install Wesley from a pinned release commit before running the check, and
+  `pnpm release:check` includes the same gate.
+- **Structural reading boundary**: `graft_review` impact counts and
+  `graft_dead_symbols` now read through a Graft-owned
+  `StructuralReadingPort` with explicit `echo-native`,
+  `git-warp-imported`, and `fallback-translated` evidence labels, preserving
+  existing public response shapes while preventing current git-warp readings
+  from masquerading as Echo-native witnesshood.
+
+### Fixed
+
+- **Structural reading residual posture**: Reference-count readings now
+  report a partial residual posture when committed import-scan fallback
+  evidence is unavailable after a zero-count WARP graph reading.
+
+### Security
+
+- **Dependency audit posture**: Patched audited transitive dependencies through
+  pnpm overrides for `brace-expansion` and `qs`, preserving a clean release
+  security gate.
+
+## [0.8.0] - 2026-05-13
+
+### Added
+
+- **Top-level structural review CLI**: `graft review --base <ref>
+  [--head <ref>]` now renders a human-readable structural review summary
+  from the existing `graft_review` model, while `--json` keeps the
+  schema-validated `graft.cli.struct_review` payload for agents.
+- **Structural test coverage map**: `graft_test_coverage` and
+  `graft struct test-coverage [--src <path>] [--tests <path>]` now
+  report exported source symbols with or without bounded test-directory
+  references, explicitly labeled as structural/reference coverage rather
+  than execution coverage.
+- **Git enhance provenance hints**: `git graft enhance --since <ref>`
+  now adds a bounded provenance-hints section for changed symbols using
+  WARP-backed blame facts when available, including ambiguity,
+  creation/signature-change commits, reference count, and unavailable
+  blame reasons.
+- **Symbol history timeline**: `graft symbol history <symbol>
+  [--path <path>]` now renders a timeline-first human view over the
+  existing provenance-backed `graft_blame` facts while preserving the
+  `graft.cli.symbol_blame` JSON schema.
+- **Dead symbol detection**: `graft_dead_symbols` and `graft struct
+  dead-symbols [--limit <n>]` now list symbols removed from indexed WARP
+  history and not subsequently re-added.
+- **Review cooldown status helper**: `graft review cooldown [--pr
+  <number>]` now reads PR comments via `gh pr view --json comments`,
+  detects CodeRabbit rate-limit markers, and reports local ready,
+  cooldown, or unknown status; `--comments-file` supports fixture-backed
+  checks.
+- **Rust structural parsing**: parser-backed outlines, governed reads,
+  structural diffs, and WARP indexing now recognize `.rs` files using
+  the bundled Rust tree-sitter grammar.
+- **GraphQL structural parsing**: parser-backed outlines, governed
+  reads, structural diffs, and WARP indexing now recognize `.graphql`,
+  `.gql`, and `.graphqls` files using a compatible GraphQL
+  tree-sitter WASM grammar with GraphQL-specific outline kinds for
+  objects, fields, inputs, scalars, unions, directives, operations,
+  fragments, schema declarations, and enum values, with fixture coverage
+  for Continuum/Wesley-style contract schemas.
+- **Python structural parsing**: parser-backed outlines, governed reads,
+  structural diffs, and WARP indexing now recognize `.py` and `.pyi`
+  files using the bundled Python tree-sitter grammar. Outlines cover
+  functions, async functions, classes, public methods, class fields, and
+  uppercase module constants.
+- **Go structural parsing**: parser-backed outlines, governed reads,
+  structural diffs, and WARP indexing now recognize `.go` files using
+  the bundled Go tree-sitter grammar. Outlines cover packages,
+  functions, receiver methods, structs, interfaces, constants, and
+  variables.
+- **JSON structured config projection**: parser-backed outlines,
+  governed reads, structural diffs, and WARP indexing now recognize
+  `.json` files using the bundled JSON tree-sitter grammar. Outlines
+  summarize top-level config keys with bounded nested object children.
+- **TOML structured config projection**: parser-backed outlines,
+  governed reads, structural diffs, and WARP indexing now recognize
+  `.toml` files using the bundled TOML tree-sitter grammar. Outlines
+  summarize tables, array tables, and bounded package/tool fields.
+- **YAML structured config projection**: parser-backed outlines,
+  governed reads, structural diffs, and WARP indexing now recognize
+  `.yaml` and `.yml` files using the bundled YAML tree-sitter grammar.
+  Outlines summarize top-level keys and bounded nested mapping anchors.
+- **Docker auto-start helper**: the isolated test runner now attempts to
+  launch Docker Desktop on macOS before failing the Docker daemon
+  preflight, while keeping the existing explicit fallback guidance for
+  unsupported or failed startup paths.
+- **Bounded WARP semantic enrichment seam**: `indexHead` accepts an
+  optional semantic enrichment provider for explicit-path indexing,
+  emits same-file `calls` edges and `typeof` symbol properties from
+  accepted provider facts, caps per-file semantic facts, and reports
+  unavailable providers without breaking tree-sitter indexing.
+- **Git version startup guard**: CLI, stdio MCP, and daemon startup now
+  fail early when the installed Git is below the plumbing baseline
+  needed for flags such as `--path-format`. Hosts can also call
+  `ensureGitVersionSupportsGraft(...)` from the root package export.
+- **Method glossary**: `docs/method/GLOSSARY.md` defines core project
+  terms including WARP, causal provenance, strand, worldline, checkout
+  epoch, and workspace overlay.
+
+### Changed
+
+- **Lazy parser runtime**: Tree-sitter and grammar WASM loading now
+  happens through an explicit `ensureParserReady()` path instead of
+  top-level await, reducing cold-start pressure for runtimes that do
+  not parse immediately.
+- **MCP orchestration staging**: MCP invocation and server construction
+  are split into named stages and factories, preserving tool behavior
+  while reducing orchestration debt.
+- **Unified governed read logic**: MCP `safe_read` delegates cache and
+  structural-diff decisions to `RepoWorkspace.safeRead`, keeping the
+  MCP and direct library surfaces aligned.
+- **WARP symbol identity hardening**: symbol-id encoding and decoding
+  now route through `SymIdCodec`, and `indexHead` uses a lighter patch
+  payload estimator instead of serializing full patch JSON for budget
+  checks.
+
+### Fixed
+
+- **Structural test coverage review fix**: `graft struct
+  test-coverage` now skips tracked test files deleted from the working
+  tree before running reference searches, so unstaged or staged test
+  deletions degrade to uncovered symbols instead of failing on missing
+  paths.
+- **Review truth follow-up**: CodeRabbit cooldown detection now ignores
+  unauthored rate-limit text by default, structural test coverage batches
+  symbol reference searches per run, CLI render schemas use strict object
+  definitions directly, and review-facing model/render tests cover empty
+  history plus provenance-hint output.
+- **Review truth collision follow-up**: CodeRabbit cooldown detection now
+  returns unknown when any authored rate-limit marker lacks timestamp or
+  duration evidence, and structural test coverage avoids substring
+  matches while attributing duplicate exported symbol names to the
+  referenced source file.
+- **Structural review PR feedback**: `graft review` and
+  `graft struct review` now require `--base` at parse time, nested
+  object-literal defaults no longer compact into malformed signatures,
+  and Rust impl/trait extraction uses the grammar's `body` field
+  without a dead fallback.
+- **PR review hardening follow-up**: Docker auto-start polling no longer
+  uses `Atomics.wait` on the main thread, Docker probe subprocesses are
+  bounded, parser warmup fire-and-forget paths consume rejected promises,
+  `SymIdCodec` rejects malformed IDs and escapes delimiter characters,
+  WARP structural path filters are directory-boundary safe, the MCP server
+  passes injected Git clients through `ToolContext`, and playback tests avoid
+  Node 21-only `import.meta.dirname`.
+- **Release gate stability**: the Docker-isolated test runner now bounds
+  default Vitest worker concurrency unless an explicit `--maxWorkers`
+  argument is supplied, keeping full-suite release validation stable under
+  constrained Docker resources.
+- **Parser readiness follow-up**: root library hosts can now call
+  `ensureParserReady()` before synchronous structured-buffer use, while
+  pre-warm sync projection bundles return explicit partial parser
+  unavailable results instead of throwing. Outline cache writes are
+  best-effort after successful governed reads, lazy outline snapshots
+  share in-flight work, and WARP indexing reuses the parsed tree for
+  outline extraction.
+- **Projection bundle README example**: direct `StructuredBuffer` usage
+  now shows explicit disposal, while `createProjectionBundle(...)` is
+  documented as the lifecycle-owning wrapper.
+
 ## [0.7.1] - 2026-04-30
 
 ### Fixed

package/GUIDE.md

@@ -18,7 +18,7 @@ Manually enforce policies or inspect structural history from your terminal.
 ### 3. Shared Daemon Mode
 Run the central execution authority for multi-repo work and persistent monitors.
 - **Run**: `npx @flyingrobots/graft daemon`
-- **Read**: [docs/SETUP.md](./docs/SETUP.md) (Daemon bootstrap and `workspace_authorize` / `workspace_bind`)
+- **Read**: [docs/SETUP.md](./docs/SETUP.md) (Daemon bootstrap and `workspace_open`)
 - **Read**: [Architecture](./ARCHITECTURE.md) (Daemon section)
 
 ## Big Picture: System Orchestration
@@ -33,9 +33,9 @@ Graft is a tiered governor. It manages the context burden across three layers:
 
 - [ ] **I am setting up a new project**: Start with `README.md` Quick Start.
 - [ ] **I am configuring Claude Code**: Use `npx graft init --write-claude-hooks`.
-- [ ] **I am using daemon mode in a generic MCP client**: Read [docs/SETUP.md](./docs/SETUP.md) and expect explicit `workspace_authorize` then `workspace_bind`.
+- [ ] **I am using daemon mode in a generic MCP client**: Read [docs/SETUP.md](./docs/SETUP.md) and expect `workspace_open` as the normal agent-facing path.
 - [ ] **I am debugging a structural diff**: Use `npx graft struct diff --json`.
-- [ ] **I am contributing to Graft**: Read `METHOD.md` and `docs/BEARING.md`.
+- [ ] **I am contributing to Graft**: Read `CONTRIBUTING.md`, `METHOD.md`, and [docs/github-issues-mirroring.md](./docs/github-issues-mirroring.md).
 
 ## Rule of Thumb
 
@@ -49,5 +49,10 @@ If you need to know "what's true right now," use [docs/BEARING.md](./docs/BEARIN
 
 If you are just starting, use the [README.md](./README.md) and the setup instructions in [docs/SETUP.md](./docs/SETUP.md).
 
+If you are reporting a bug or feature idea as a newcomer, use
+[GitHub Issues](https://github.com/flyingrobots/graft/issues). Issues are
+the public discovery surface; execution details stay in Method backlog and
+design packets.
+
 ---
 **The goal is inevitably. Every feature is defined by its tests.**

package/README.md

@@ -2,100 +2,132 @@
 
 A context governor for coding agents. Graft enforces read policy so agents consume the smallest structurally correct view of a codebase instead of dumping raw files into their context window.
 
-Graft is designed for the operator who demands precision and the architect who needs a stable foundation for agentic work. It scales from simple policy-aware reads to high-fidelity causal provenance tracking across multi-session worktrees.
-
 [![npm version](https://img.shields.io/npm/v/@flyingrobots/graft)](https://www.npmjs.com/package/@flyingrobots/graft)
 
 ![Graft demo](./docs/assets/graft.svg)
 
+---
+
+## TL;DR — Up and Running in 30 Seconds
+
+**What it is**: Graft sits between your AI coding agent and the filesystem. Instead of dumping entire files into the context window, it returns the minimum structurally correct view — full content for small files, AST-derived outlines for large ones, hard refusals for secrets and binaries. Every response carries a receipt so agents know exactly how much context they've consumed.
+
+**Why you want it**: Agents that read files naively fill their context window with lockfiles, minified output, and 2,000-line modules they only needed 10 lines of. Graft fixes that automatically.
+
+```bash
+# Install and bootstrap your repo
+npx @flyingrobots/graft init --write-claude-hooks --write-codex-mcp
+
+# Start serving (MCP over stdio — point your agent at this)
+npx @flyingrobots/graft serve
+
+# Or try a governed read from the CLI right now
+npx @flyingrobots/graft read safe src/app.ts
+```
+
+That's it. `init` scaffolds `.graftignore` and writes the MCP config your agent needs. `serve` starts listening on stdio. Your agent calls `safe_read` instead of reading files directly, and Graft handles the rest.
+
+---
+
+## The Problem
+
+AI coding agents read files the same way a first-year developer does: grab the whole thing, every time. A 2,000-line module goes straight into the context window. So does the lockfile. So does the compiled output. So does the `.env`.
+
+Context windows are finite. Once they fill up, the agent starts forgetting what it already read. Performance degrades. Hallucinations increase. You burn tokens on noise.
+
+Graft sits between the agent and the filesystem and enforces a simple rule: **return the minimum structurally correct view**.
+
+- Small file? Full content.
+- Large file? A structural outline — function names, signatures, line ranges. The agent can drill in with a range read if it needs a specific function body.
+- Binary, secret, or lockfile? Hard refusal with a machine-readable reason code and a suggested alternative.
+
+Every response carries a receipt: bytes consumed, bytes avoided, session depth, policy decision. Agents can self-regulate. Operators can audit.
+
+---
+
 ## Why Graft?
 
-Unlike simple file-scraping tools, Graft treats the repository as a layered worldline of code structure and causal activity.
+- **Parser-backed outlines.** Outlines come from Tree-Sitter ASTs, not heuristic line-scanning. Function signatures, class hierarchies, and jump tables are structurally accurate across JavaScript, TypeScript, Rust, Python, Go, GraphQL, JSON, TOML, YAML, Markdown, and more.
 
-- **Policy-Enforced Reads**: Automatically degrades large files to structural outlines and jump tables. Refuses binaries, secrets, and lockfiles with machine-readable reasons.
-- **Machine-Readable Contracts**: Responses carry versioned `_schema` metadata and decision receipts so agents can reason about outcomes without scraping prose.
-- **Structural Memory**: Uses WARP (Structural Worldline Memory) to track AST evolution across Git commits. Query what changed structurally without reading a single byte of source code.
-- **Causal Provenance**: Tracks the *why* behind structural changes by logging read, stage, and transition activity into strand-scoped causal workspaces.
-- **Industrial-Grade Daemon**: A same-user local runtime that manages multi-repo authorization, background indexing, and shared-machine worker pools.
+- **Machine-readable contracts.** Every response carries versioned `_schema` metadata and a decision receipt. Agents reason about outcomes without scraping prose. Receipts accumulate cumulative session stats so agents know when they're burning budget.
 
-## Quick Start
+- **Structural memory across Git history.** WARP (Structural Worldline Memory) indexes AST outlines per commit into a Git-backed graph. Query what changed structurally — which symbols were added, removed, or renamed — without reading a single byte of source. No checkout required.
+
+- **Session governance.** The `GovernorTracker` watches for anti-patterns: runaway tool loops, late-session large reads, edit/bash thrash. Tripwire signals surface in receipts so agents and operators can act before context is exhausted.
+
+- **Industrial-grade daemon.** A same-user local runtime manages multi-repo authorization, background indexing, and shared worker pools. WARP graphs stay warm in memory across sessions. Multi-repo work happens without file conflicts.
+
+---
 
-Graft has three official entry points:
+## Four Official Surfaces
 
-- **API** for direct in-process integration
-- **CLI** for operator and debugging workflows
-- **MCP** for agent transport integration
+Graft exposes the same core capabilities through four integration points. Choose based on your deployment context.
+
+### 1. CLI — Operator and Debugging Workflows
 
-### 1. Bootstrap a Repo
-Scaffold `.graftignore`, setup git hooks, and seed agent instructions.
 ```bash
-npx @flyingrobots/graft init --write-claude-hooks --write-codex-mcp
+npx @flyingrobots/graft read safe src/app.ts
+npx @flyingrobots/graft struct since HEAD~3
+npx @flyingrobots/graft struct dead-symbols --limit 20
+npx @flyingrobots/graft symbol history createUser --path src/users.ts
+npx @flyingrobots/graft review --base HEAD~1
+npx @flyingrobots/graft review cooldown --pr 48
 ```
 
-### 2. Repo-Local Stdio MCP
-This is the simplest per-repo path for most clients. The current
-checkout is the authority, and there is no separate workspace binding
-step.
+Stateless. Print and exit. Good for scripting, spot-checking policy decisions, and inspecting structural history.
+
+### 2. MCP Stdio — Repo-Local Agent Sessions
+
+The simplest path for single-repo agent work. The current checkout is the authority. No workspace binding required.
+
 ```bash
 npx @flyingrobots/graft serve
 ```
 
-### 3. Standalone CLI
-Enforce policy on a single read or inspect structural history.
+Point your MCP client at this process. Graft speaks JSON-RPC over stdin/stdout. The same binary auto-detects non-TTY stdio and enters serve mode automatically — so `npx @flyingrobots/graft` with no arguments works as an MCP server when piped.
+
+### 3. MCP Daemon — Multi-Repo and Multi-Session
+
+A persistent same-user runtime for long-running or multi-repo agent work. WARP graphs stay warm between sessions.
+
 ```bash
-npx @flyingrobots/graft read safe src/app.ts
-npx @flyingrobots/graft struct since HEAD~3
+npx @flyingrobots/graft daemon
 ```
 
-### 4. Direct Library API
-Embed Graft in-process when you want direct access without MCP transport
-or CLI process orchestration.
-```ts
-import { createRepoLocalGraft, callGraftTool } from "@flyingrobots/graft";
+Daemon sessions start unbound. The normal agent flow:
 
-const graft = createRepoLocalGraft({ cwd: process.cwd() });
-const outline = await callGraftTool(graft, "file_outline", { path: "src/app.ts" });
-```
+1. `workspace_open` with the target repo's `cwd`
+2. Optionally `workspace_list_opened` to inspect active workspaces
+3. Use repository-scoped tools: `safe_read`, `file_outline`, `graft_diff`, etc.
+
+See [docs/SETUP.md](./docs/SETUP.md) for client-specific bootstrap and daemon control-plane configuration.
 
-This uses the same repo-local core as the CLI and MCP server, but it
-lets host tools call Graft directly inside the same process.
+### 4. Library API — In-Process Integration
 
-When you want a direct repo-local read surface instead of tool receipts,
-use the workspace API:
+Embed Graft directly when you want structural reads or syntax data without spawning a subprocess or going through MCP transport.
+
+**Governed repo reads** (same policy enforcement as MCP, no receipts):
 ```ts
 import { createRepoWorkspace } from "@flyingrobots/graft";
 
 const workspace = await createRepoWorkspace({ cwd: process.cwd() });
-const first = await workspace.safeRead({ path: "src/app.ts" });
-const second = await workspace.safeRead({ path: "src/app.ts" });
-const outline = await workspace.fileOutline({ path: "src/app.ts" });
+const result = await workspace.safeRead({ path: "src/app.ts" });
+// result.projection: "content" | "outline" | "refused"
 ```
 
-This exposes the same governed repo-local read behavior that the MCP
-surface uses for `safe_read`, `file_outline`, `read_range`, and
-`changed_since`, but without going through MCP receipts at all.
-
-For close editor integration, use the buffer-native surface directly:
+**In-process tool calls with receipts** (full MCP behavior, no subprocess):
 ```ts
-import { createProjectionBundle, createStructuredBuffer } from "@flyingrobots/graft";
+import { createRepoLocalGraft, callGraftTool } from "@flyingrobots/graft";
 
-const buffer = createStructuredBuffer("src/app.tsx", liveEditorText, {
-  basis: { kind: "editor_head", headId: "head-42", tick: 17 },
-});
-const spans = buffer.syntaxSpans({
-  viewport: {
-    start: { row: 0, column: 0 },
-    end: { row: 80, column: 0 },
-  },
-});
-const context = buffer.nodeAt({ row: 24, column: 12 });
-const rename = buffer.renamePreview({
-  position: { row: 24, column: 12 },
-  nextName: "nextValue",
-});
+const graft = createRepoLocalGraft({ cwd: process.cwd() });
+const outline = await callGraftTool(graft, "file_outline", { path: "src/app.ts" });
+```
 
-// Every warm result now carries the basis it was derived from.
-console.log(spans.basis);
+**Editor-native syntax highlighting** (Tree-Sitter WASM, no I/O, viewport-aware):
+```ts
+import { createProjectionBundle, ensureParserReady } from "@flyingrobots/graft";
+
+await ensureParserReady();
 
 const bundle = createProjectionBundle("src/app.tsx", liveEditorText, {
   basis: { kind: "editor_head", headId: "head-42", tick: 17 },
@@ -104,40 +136,51 @@ const bundle = createProjectionBundle("src/app.tsx", liveEditorText, {
     end: { row: 80, column: 0 },
   },
 });
-
-console.log(bundle.parseStatus.status);
+// bundle.syntax.spans — highlight ranges for the visible viewport only
 ```
 
-### 5. Shared Daemon Runtime
-Start the same-user execution authority for multi-session or multi-repo
-work.
+`createProjectionBundle` owns the WASM buffer lifecycle internally. Use `createStructuredBuffer` directly if you need to hold a buffer across multiple operations and manage `dispose()` yourself.
+
+---
+
+## Quick Start
+
 ```bash
-npx @flyingrobots/graft daemon
+# 1. Bootstrap the repo: scaffold .graftignore, seed agent instructions
+npx @flyingrobots/graft init --write-claude-hooks --write-codex-mcp
+
+# 2. Start serving (repo-local stdio MCP)
+npx @flyingrobots/graft serve
 ```
 
-Daemon sessions start `unbound`. If your client connects through the
-daemon instead of repo-local stdio, the first repo-scoped flow is:
+## Contributing with public visibility
 
-1. `workspace_authorize` for the target repo/worktree
-2. `workspace_bind` for the active daemon session
-3. then use repository-scoped tools such as `safe_read`
+For bugs, capability requests, and ideas, start at
+[GitHub Issues](https://github.com/flyingrobots/graft/issues).
+That queue is the public view for priorities and discussion. Internal execution and design rigor still lives in
+`docs/method/backlog/` and `docs/design/` so details remain deterministic for contributors.
 
-Use [docs/SETUP.md](./docs/SETUP.md) for the exact client bootstrap and
-daemon control-plane posture.
+---
 
 ## Documentation
 
-- **[Guide](./GUIDE.md)**: Orientation, the fast path, and agent bootstrap.
-- **[Setup Guide](./docs/SETUP.md)**: Client-specific MCP setup, daemon posture, and workspace binding.
-- **[Advanced Guide](./ADVANCED_GUIDE.md)**: Deep dives into the pipeline, worldlines, and daemon mechanics.
-- **[Architecture](./ARCHITECTURE.md)**: The authoritative structural reference (Ports, Adapters, WARP).
-- **[Public API Contract](./docs/public-api.md)**: The semver-public root import surface and stability policy.
-- **[Repo Topology](./docs/repo-topology.md)**: Where API, CLI, MCP, and the core live in the source tree.
-- **[Three-Surface Capability Matrix](./docs/three-surface-capability-matrix.md)**: Current API / CLI / MCP baseline and peer posture.
-- **[Security Model](./docs/strategy/security-model.md)**: Same-user daemon trust boundaries, authz, and observability posture.
-- **[Causal Provenance](./docs/strategy/causal-provenance.md)**: Transport sessions, causal workspaces, strands, and handoff truth.
-- **[Vision](./docs/VISION.md)**: Core tenets and the provenance-aware mission.
-- **[Method](./METHOD.md)**: Repo work doctrine and the cycle loop.
+| Document | What it covers |
+|----------|---------------|
+| [Technical Teardown](./docs/TECHNICAL_TEARDOWN.md) | Zero-to-hero deep dive: entry points, golden paths, data schemas, policy engine, WARP, session governance, trade-offs |
+| [Guide](./GUIDE.md) | Orientation, the fast path, and agent bootstrap |
+| [Setup Guide](./docs/SETUP.md) | Client-specific MCP setup, daemon posture, and workspace binding |
+| [Advanced Guide](./ADVANCED_GUIDE.md) | Pipeline internals, worldlines, and daemon mechanics |
+| [Architecture](./ARCHITECTURE.md) | Authoritative structural reference: Ports, Adapters, WARP |
+| [Public API Contract](./docs/public-api.md) | Semver-public root import surface and stability policy |
+| [Three-Surface Capability Matrix](./docs/three-surface-capability-matrix.md) | API / CLI / MCP feature baseline and peer posture |
+| [Repo Topology](./docs/repo-topology.md) | Where API, CLI, MCP, and core live in the source tree |
+| [Security Model](./docs/strategy/security-model.md) | Same-user daemon trust boundaries, authz, and observability |
+| [Causal Provenance](./docs/strategy/causal-provenance.md) | Transport sessions, causal workspaces, strands, and handoff truth |
+| [North Star](./NORTHSTAR.md) | Long-term stack position and Continuum-shaped direction |
+| [Vision](./docs/VISION.md) | Core tenets and the provenance-aware mission |
+| [Method](./METHOD.md) | Repo work doctrine and the cycle loop |
+| [Issue visibility and backlog mapping](./docs/github-issues-mirroring.md) | Public issue triage plus internal backlog synchronization |
 
 ---
+
 Built with precision by [FLYING ROBOTS](https://github.com/flyingrobots)

package/dist/adapters/fake-echo-kernel-transport.d.ts

@@ -0,0 +1,33 @@
+import { type EchoKernelTransport } from "../ports/echo-kernel-transport.js";
+export interface FakeDeadSymbolFixture {
+    readonly name: string;
+    readonly kind: string;
+    readonly filePath: string;
+    readonly exported: boolean;
+    readonly removedInCommit: string;
+}
+export interface FakeSymbolReferenceFixture {
+    readonly symbol: string;
+    readonly filePath: string;
+    readonly referenceCount: number;
+    readonly referencingFiles: readonly string[];
+}
+export interface FakeQueryObstructionFixture {
+    readonly code: string;
+    readonly message: string;
+    readonly recovery?: string;
+}
+export interface FakeEchoFixture {
+    readonly basisId?: string;
+    readonly deadSymbols?: readonly FakeDeadSymbolFixture[];
+    readonly symbolReferences?: readonly FakeSymbolReferenceFixture[];
+    readonly rejectImportBatchIds?: readonly string[];
+    readonly admissionObstructedBatchIds?: readonly string[];
+    readonly queryObstruction?: FakeQueryObstructionFixture;
+    readonly retainedEvidencePosture?: "retained" | "missing" | "obstructed";
+}
+export interface CreateFakeEchoKernelTransportOptions {
+    readonly fixture?: FakeEchoFixture;
+}
+export declare function createFakeEchoKernelTransport(options?: CreateFakeEchoKernelTransportOptions): EchoKernelTransport;
+//# sourceMappingURL=fake-echo-kernel-transport.d.ts.map

package/dist/adapters/fake-echo-kernel-transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fake-echo-kernel-transport.d.ts","sourceRoot":"","sources":["../../src/adapters/fake-echo-kernel-transport.ts"],"names":[],"mappings":"AAUA,OAAO,EAEL,KAAK,mBAAmB,EACzB,MAAM,mCAAmC,CAAC;AA0B3C,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;CAClC;AAED,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,gBAAgB,EAAE,SAAS,MAAM,EAAE,CAAC;CAC9C;AAED,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,qBAAqB,EAAE,CAAC;IACxD,QAAQ,CAAC,gBAAgB,CAAC,EAAE,SAAS,0BAA0B,EAAE,CAAC;IAClE,QAAQ,CAAC,oBAAoB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAClD,QAAQ,CAAC,2BAA2B,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACzD,QAAQ,CAAC,gBAAgB,CAAC,EAAE,2BAA2B,CAAC;IACxD,QAAQ,CAAC,uBAAuB,CAAC,EAAE,UAAU,GAAG,SAAS,GAAG,YAAY,CAAC;CAC1E;AAED,MAAM,WAAW,oCAAoC;IACnD,QAAQ,CAAC,OAAO,CAAC,EAAE,eAAe,CAAC;CACpC;AAkDD,wBAAgB,6BAA6B,CAC3C,OAAO,GAAE,oCAAyC,GACjD,mBAAmB,CA6JrB"}