# EDC for Pi

EDC adds repository architecture maps, agent context, and context-aware code review workflows to [Pi](https://pi.dev). Run `/edc` to build context, then review full repos or diffs through security, delivery/architecture, and quality lenses.

## Install

```bash
pi install npm:@sgtbeatdown/edc
```

EDC supports global installs only. Pi's `--local`/`-l` mode is unsupported.

Git/source installs still work and remain global:

```bash
pi install git:github.com/almogdepaz/edc
bash pi/install.sh --from-source
```

Manage the package with pi's normal package commands:

```bash
pi list
pi update npm:@sgtbeatdown/edc
pi remove npm:@sgtbeatdown/edc
```

Use a pinned git ref when you need reproducible installs, e.g. `pi install git:github.com/almogdepaz/edc@v1.1.4`. Pi records the global package in `~/.pi/agent/settings.json`.

## Requirements and permissions

Orchestrated pi reviews require:

- `pi`, `git`, and `node` on `PATH`
- shell access for background build/update/review/delivery-review/quality-review subprocesses
- write access to `AGENTS.md`, `edc-context/`, `.git/edc/`, and `review-*.md`, plus the global install location during installation

Permission gates, plan/read-only modes, path guards, sandboxes, and SSH tool replacements may intentionally block or redirect those operations. EDC does not try to bypass them.

## Quick path

1. Start `pi` in a git repository.
2. Run `/edc`.
3. Choose **build context** once.
4. Choose **changes vs default branch** → **combined review**.
5. Check progress with **job status**.

## Command

Pi exposes one interactive command:

| Command | Purpose |
|---|---|
| `/edc [--no-context-refresh\|--ignore-context]` | Open the EDC menu; optional flags apply to every review scope/lens |

Menu actions:

- full repo review — choose a lens, then review the current tracked repo
- changes vs default branch — choose a lens, then review `HEAD` against the detected default branch
- changes vs custom base — enter refs, choose a lens, then review that diff
- lenses: combined, security, delivery, or quality
- job status — shows the current background job status
- build context — starts a background context build
- force rebuild context — discards generated context and starts a full background rebuild
- update context — refreshes from the context manifest's recorded source commit to `HEAD`; review base selection is never used
- doctor / validate context

`/edc` is interactive-only. For non-interactive use, use the terminal CLI:

```bash
edc review full --agent pi
edc review diff --agent pi
edc security full --agent pi
edc delivery diff <base> --agent pi
edc quality full --agent pi
edc build --agent pi
edc build --agent pi --force
edc update --agent pi
```

The unified installer (`bash install.sh --agent pi`) also adds `~/.edc/scripts` to `PATH` in `~/.zshrc` or `~/.bashrc` when possible. Restart your shell after install, or run `export PATH="$HOME/.edc/scripts:$PATH"` for the current shell. Use `--no-path` to skip shell rc edits.

Review actions first ask for scope, then lens. When a differential scope has reviewable working-tree changes, Pi also asks whether to review the complete working tree, review committed changes only, or cancel. Complete mode passes `--include-working-tree`; committed mode passes `--committed-only`. `diff` without a base uses the detected default branch. Combined review runs security, delivery, then quality against one candidate by default; exact `EDC_PARALLEL=1` enables concurrent lenses and module workers. Quality diff audits only modules owning changed files; quality full audits all modules. Default reviews prompt before refreshing stale/missing context. Declining cancels and prints no-build CLI examples for the selected lens.

Run `/edc --no-context-refresh` or `/edc --ignore-context` before selecting any full/diff scope and lens to opt out of context generation. No-refresh permits existing context as optional navigation, but falls back to explicit source files when context is absent, stale, incomplete, or malformed; new/unmapped files remain in scope. Ignore-context also forbids generated-context analysis reads/routing and takes precedence when both flags are present. Neither option builds, updates, or repairs context.

Workers gather only necessary source/supporting evidence and ordinary specs/docs, then report policy and coverage limitations. Existing report paths, candidate/dirty policies, and review checks remain unchanged; direct reviews do not need module fanout or a generated manifest.

## Background job state

Review, build, update, and quality-review/audit run in the background so the TUI stays usable. EDC keeps exactly one current job slot per git repo:

| File | Purpose |
|---|---|
| `.git/edc/status` | Machine-readable current job status (`kind`, `status`, `run_id`, `pid`, `args`, `started_head`, `finished_head`, `repo_changed`, `failure_reason`, `failure_hint`, `final_review`, etc.) |
| `.git/edc/<kind>.log` | Raw stdout/stderr from the current `edc-<kind>.sh` run (`review.log`, `delivery-review.log`, `build.log`, `update.log`, or `audit.log`) |

Both paths are resolved with `git rev-parse --git-path`, so they work with normal repos and worktrees. They are under git metadata, not the worktree, so they are never tracked and need no `.gitignore` entry. Starting a new background job overwrites the previous status and that job kind's log.

`edc-context/` remains disposable generated context. Recovery may wipe and rebuild it; active pi job status/logs survive because they live under `.git/edc/`. If a background job fails, `/edc` → Job status reports structured result fields when available: status, code, scope/base/target, failed phase, outputs, reason, hint, and child result. `success-with-warning` means durable outputs validated even though the agent transport reported an odd/nonzero finish; `failed` means durable outputs did not validate.

## Skills

Pi exposes only the human-facing EDC methodology skills globally:

| Skill | Use |
|---|---|
| `edc-review` | Apply the EDC security/adversarial review methodology directly in chat, without running the full orchestrator. |
| `edc-audit` | Apply the EDC quality-review methodology directly in chat. |
| `edc-delivery-review` | Apply the EDC goal/spec delivery + architecture-fit review methodology directly in chat. |

Hidden implementation prompt bundles (`edc-module-context-impl`, `edc-build-impl`, `edc-update-impl`) are available from the installed package or `~/.edc/skills` for orchestrator subprocesses, but are not advertised in pi's TUI skill list. The extension validates and executes only its package source or the managed global runtime. It never reads, repairs, creates, or executes repo-local `.edc/`; legacy caches are ignored and can be removed manually.

## Compatibility with other pi packages

EDC registers one `/edc` command, does not override built-in tools, and exposes only the human-facing skills above. It should coexist with provider packages and command-only helper packages.

Known interactions:

- Context-pruning packages are safest with EDC's default `advisory` mode. In `inject` mode, EDC intentionally adds repo/module context messages to the session.
- Permission gates, plan/read-only modes, path guards, sandboxes, and SSH tool replacements may block or redirect EDC's normal `bash`, `edit`, and `write` activity. That is expected plugin behavior, not an EDC bypass target.
- Build/update/review/delivery-review/quality-review need the requirements and write permissions listed above.

### Observing EDC pi workers

EDC pi workers use `--no-extensions` to prevent arbitrary extension discovery. To load one explicitly approved prompt-neutral observer, configure its absolute entrypoint:

```text
# ~/.edc/config
EDC_PI_EXTENSION_PATH=/absolute/path/to/agent_observer/src/extension.ts
EDC_PARALLEL=0
# Used only when EDC_PARALLEL=1:
EDC_MAX_CONCURRENCY=4
```

EDC then invokes each worker with `--no-extensions -e <path>`. The observer can register every coordinator-launched worker while unrelated global/project extensions remain disabled. EDC orchestration is serial unless exact `EDC_PARALLEL=1` opts into lens/module concurrency; `EDC_MAX_CONCURRENCY` is validated and applied only after that opt-in. Run/task/phase/module provenance is also available in `EDC_RUN_ID`, `EDC_TASK_ID`, `EDC_TASK_PHASE`, and `EDC_TASK_MODULE`. Worker artifacts live under `.git/edc/runs/<run-id>/`.

## Modes

EDC has two runtime modes, controlled by `edc-context/manifest.json` `policy.defaultMode`:

- **`advisory`** (default) — pure docs. Hooks no-op. Zero per-tool token overhead.
- **`inject`** — when `edc-context/manifest.json` exists and opts into inject mode, `session_start` surfaces `edc-context/index.md`; `tool_call` (bash/edit/write) auto-injects the relevant `edc-context/modules/<name>.md` once per session. Missing EDC context is silent; use `/edc` explicitly to build or manage context.

Toggle (run from the root of the repository whose context you want to change; the path of install.sh is the path of your EDC checkout or package):

```bash
bash pi/install.sh --context-mode advisory
bash pi/install.sh --context-mode inject
```

You can also toggle from the shared CLI after context exists:

```bash
edc mode
edc mode advisory
edc mode inject
```

## Troubleshooting

| Symptom | What to check |
|---|---|
| `bash` not found | Install or restore the system Bash executable on `PATH`. macOS `/bin/bash` 3.2 is supported. |
| `node: command not found` | Install Node; EDC orchestrators use it for manifest, routing, and stream handling. |
| `/edc` job fails immediately under plan/read-only/sandbox packages | Check whether another extension blocked `bash` or writes to `AGENTS.md`, `edc-context/`, `.git/edc/`, or `review-*.md`. This is expected for strict guard packages. |
| Review says context is missing or stale | Run `/edc` → **Build context** once, or `/edc` → **Update context from default branch** after HEAD moves. Use `/edc` → **Job status** and inspect `.git/edc/<kind>.log` for recovery details. |
| Background review reports provider websocket/transport failure | The nested pi subprocess lost provider transport. Rerun the job; if it repeats, run `edc update --agent pi` separately or reduce context/update scope. |
| Wrong model in nested pi subprocesses | EDC forwards the active pi model as `EDC_PI_MODEL` when `ctx.model.provider` and `ctx.model.id` are available. Check the job log for the propagated model and set explicit model env vars only if you need to override it. |

## How it maps to pi

| EDC feature | Pi mechanism |
|---|---|
| Interactive menu | `pi.registerCommand("edc", …)` + `ctx.ui.select` |
| `SessionStart` hook | `pi.on("session_start", …)` |
| `PreToolUse` hook | `pi.on("tool_call", …)` filtered to `bash|edit|write` |
| Skills | `pi.on("resources_discover", …)` returning only `edc-review`, `edc-audit`, and `edc-delivery-review` |
| Per-session dedup | `ctx.sessionManager.getSessionId()` + tmp file |

The injection logic is shared with the Claude Code / Cursor hooks via `plugins/edc/hooks/lib/route.mjs` — single source of truth, no drift.

## Source layout

`pi/` is the pi package surface and implementation home.
