FE-841: Pi agent foundations — in-process SDK, toolchain profiles

docs/praxis/orchestration-guide.md

@@ -5,11 +5,13 @@ Run `brunch cook` against the brunch repo in codebase (brownfield) mode.
 ## Pre-flight
 
 ```sh
-which pi && pi --version                       # pi >= 0.74
-npm run build                                  # dist/ fresh
+npm run build                                  # dist/ fresh (bundles the in-process pi SDK)
+grep -q '^ANTHROPIC_API_KEY=' .env             # cook feeds this to the embedded agent
 git status --porcelain --untracked-files=no    # must be empty
 ```
 
+`brunch cook` embeds `@earendil-works/pi-coding-agent` in-process (FE-841), so no external `pi` binary on `$PATH` is required — only `ANTHROPIC_API_KEY` in `.env`, which the cook command loads via `--env-file=.env`.
+
 `.brunch/` is already gitignored, so cook artifacts won't appear in `git status`.
 
 ## Author the plan
@@ -28,10 +30,12 @@ Run `/ln-scope` on a `memory/PLAN.md` frontier to produce a scope card (Target B
 
 Extract the frontier section and ask pi for YAML:
 
+The `pi` CLI is no longer a global prerequisite, but it still ships inside the bundled dep — invoke it with `npx pi` (resolves to `node_modules/.bin/pi`):
+
 ```sh
 FRONTIER="<id>"
 awk "/^### $FRONTIER\$/,/^### /" memory/PLAN.md | head -n -1 > /tmp/f.md
-pi -p --no-session --provider anthropic --model claude-haiku-4-5 \
+npx pi -p --no-session --provider anthropic --model claude-haiku-4-5 \
    --tools "read,write" \
    "Translate /tmp/f.md into .brunch/cook/plan.yaml. One epic, one slice per
     Acceptance line (max 2). Each slice needs a verification.target pointing
@@ -118,6 +122,6 @@ Periodic stragglers: `git worktree prune` + `git branch --list 'cook*' | xargs -
 
 ## Known limitations
 
-- **Pi evaluator may short-circuit.** Pi has `read,write,edit,bash` even during `evaluate-done` and may fix the file during evaluation rather than going through write-tests → write-code → run-tests. Non-deterministic.
+- **Agent runs in-process.** Cook drives the agent via the embedded `@earendil-works/pi-coding-agent` SDK (FE-841), not a spawned `pi` CLI. `evaluate-done` is scoped to a read-only tool allowlist (`toolsForAction('evaluate-done')`), so the evaluator cannot fix the file during evaluation (I126-K); `done` comes from executing the verification targets, not an LLM verdict.
 - **No commit on the cook branch.** Modification is in untracked subdirs of the cook branch's worktree, not committed. Promotion is manual `cp -R`.
 - **Plan vs frontier mismatch.** `.brunch/cook/plan.yaml` is orchestrator runtime, not planning vocabulary. `/ln-scope` or pi-assisted translation is the bridge.

memory/PLAN.md

@@ -33,6 +33,7 @@ The May 2026 intent-spec, multi-chat, changeset-ledger, prompt/context, and agen
 6. `cook-mode-from-spec` — **FE-826**; **branch-complete on `ka/fe-826-cook-mode-from-spec`** (stacked on FE-819). Greenfield/brownfield is now spec-derived plan truth: `brunch plan <specId>` writes `specification.mode` into `plan.yaml` (`Plan.mode`); `brunch cook` reads `plan.mode` to pick the worktree strategy — greenfield → empty worktree (generate from scratch), brownfield → cwd clone + clean-tree gate. Resolver split into `resolveCookPlan` (path-only) + `resolveSandboxPlan` (mode-driven). Cook `dir` arg is now optional (defaults to cwd). Reverses the location-keyed reading of Requirement 50, refines I123-K, adds D164-K. Refinement on `cook-codebase-mode` (done) + `spec-to-cook-plan` (FE-800).
 7. `cook-greenfield-single-tree` — **FE-827**; **branch-complete on `ka/fe-827-greenfield-single-tree`** (stacked on FE-826). Cook slice layout is now policy-selected (D165-K): serial greenfield runs one shared accreted tree (verify in place, no `__epic__`); parallel greenfield isolates per-slice + `__epic__` merge (race-safe); brownfield unchanged. Adds greenfield promotion-back (D166-K, I128-K): `--out`/`--force`, completed-gated, commit-on-branch, never silent — serial copy-commits the run tree, parallel commits a whole-plan merge (order-wins, collisions reported). Closes the cook output-promotion gap for greenfield; brownfield promotion stays a follow-on. New seams: `promote-run.ts`, `mergeCompletedSlicesIntoTree`, `promotionSourceDir`. LLM conflict reconciliation → Horizon `parallel-merge-conflict-reconciliation`.
 8. `plan-build-architect` — **FE-829**; **active, building on `ka/fe-829-build-architect`** (stacked on FE-827, draft PR #185). Evolves `brunch plan` from a sequencer into a build-architect emitting fixture-quality, cook-executable `plan.yaml` (target shape = the three reference fixtures). Slice 1 (**done** 2026-06-09): self-contained `PlanContract` (`checkPlan` base/emitted profiles + `repairPlan`) + shared `plan-graph` Kahn helper + `Toolchain` descriptor in the emitter — synthesizes the multi-slice-epic integration seam, closing FE-800's integration-blind / "green checks, no artifact" gap (D167-K, I129-K; no LLM, no D160-K change). Slice 2 (**done** 2026-06-09): toolchain-agnostic cook prompts + runner — `ToolchainTestRunner` + toolchain-driven cook task builders + de-hardcoded `test-writer.md`, resolved from `plan.profile` (I130-K). Slice 3 (**done** 2026-06-09): build-architect LLM stage — the planner prompt now carries each slice's acceptance criteria, spec relation hints projected into slice-id space (`projectPlanningContext`), and the three reference fixtures inlined as comment-stripped few-shot exemplars; output schema unchanged (classify/group/order the existing `req-*` slices only). Slice 4A (**done** 2026-06-09): file-ownership contract — `Slice.writes?: string[]` + single-writer-per-file `checkPlan` finding (`file-write-conflict`, design-class warning, never auto-repaired) + the D160-K coordination-file-layout-namespace amendment (I132-K). Slice 4B (**done** 2026-06-09): the architect now AUTHORS the slice set — `architectPlan` (new schema: authored slices + `writes` + `derivedFrom`) → `materializeArchitectedPlan` (deterministic normalize + requirement-provenance coverage sidecar) → `repairPlan` + `checkPlan` (emitted + generalized coverage), with a deterministic projection fallback when authoring throws/parses-malformed/leaves a requirement uncovered (I133-K; supersedes the slice-3 `planExecutionOrdering` enrichment stage on the mainline). Slice 5 (**done** 2026-06-09): eval harness — `evaluatePlanShape` (`plan-eval.ts`), a deterministic outer-loop acceptance oracle (narrow `verdict` gate + graded structural-feature metrics scored against the abstract fixture-design principles, no id/path/count overfit); the 3 reference fixtures are its self-test and were refreshed (`writes` on every slice + the missing integration seam on the `core` / `pipeline` epics of two of them) to score `overall === 1` (I134-K). Post-slice-5 cleanup (**done** 2026-06-09): retired the dormant `planExecutionOrdering` — deleted `plan-llm-planning.ts` (+ test), relocated the surviving `PlanningEnrichment` type into `plan-reconciliation.ts`, consolidated the duplicate `RunModel` onto `plan-architect.ts` (I131-K retired). Opt-in real-LLM eval smoke (**done** 2026-06-09): `plan-emitter.test.ts` env-gated block (`PLANNING_REAL_LLM=1` + `ANTHROPIC_API_KEY`, `it.skip` otherwise) runs the production architect end-to-end on the `brunch-graphs-snapshot.json` fixture and asserts `evaluatePlanShape(plan).verdict === 'accept'` — restoring the opt-in real-LLM coverage lost with `plan-llm-planning.test.ts` at the I134-K gate. **Branch-complete** (slices 1–5 + post-slice-5 cleanup + opt-in smoke). Refinement on `spec-to-cook-plan` (FE-800).
+9. `toolchain-profile-expansion` — **FE-843**; **branch-complete on `ka/fe-843-toolchain-profiles`** (stacked on FE-841). Expands the FE-829 toolchain contract so cook builds on more technologies. Card 1 (**done** 2026-06-10): data-driven profile registry — profiles are data literals (path templates + argv template + conventions prose) compiled into the unchanged `Toolchain` interface; added `node-vitest`, `node-test`, `node-jest`, `deno`; registry invariants pinned enumerably. Card 2 (**done** 2026-06-10): live + strict selection — `brunch plan --profile=<id>` (validated via `parseProfileId`), emitter resolves the chain once and stamps the id on both authored and fallback plans, `resolveToolchain` throws `UnknownProfileError` on unknown ids (absent stays lenient for fixtures). Card 3 (**done** 2026-06-10): architect-schema profile enum — chain is flag ≫ `snapshot.profile` ≫ architect-classified-from-spec-prose ≫ `bun`; a hallucinated profile fails schema parse → deterministic fallback (D160-K intact). No harness install verb (the cook agent scaffolds per A98) — assumption pending outer-loop validation (greenfield cook smoke `--profile=node-vitest`). I130-K refinement + agent-install assumption → SPEC at ln-sync tie-off. Deferred follow-ons: fail/infra test-outcome split, brownfield drift-check at cook open, `brunch detect`. Refinement on `plan-build-architect` (FE-829).
 
 ### Recently Completed
 
@@ -349,6 +350,20 @@ The May 2026 intent-spec, multi-chat, changeset-ledger, prompt/context, and agen
 - **Traceability:** Requirements 46–50; A97, A100-K; D158-K, D160-K (amended in slice 3), D161-K, D167-K; I129-K, I130-K; Future Direction §Cook plan generation. Refinement on `spec-to-cook-plan` (FE-800) — resolves its integration-blind follow-on. Builds on FE-826, FE-827.
 - **Design docs:** `docs/design/orchestrator.md`; `docs/design/orchestrator-demo-fixtures.md` (reference fixtures); `docs/next/architecture/plan-graph-petri-orchestration.md`.
 
+### toolchain-profile-expansion
+
+- **Name:** Toolchain profile expansion — more TS runtimes + live/strict profile selection
+- **Linear:** FE-843 · branch `ka/fe-843-toolchain-profiles` (stacked on FE-841)
+- **Kind:** structural (selection decision + I130-K refinement); cards 1/3 bounded
+- **Status:** branch-complete (2026-06-10) — all 3 cards landed (1: data-driven registry + 4 TS profiles; 2: selection live + strict; 3: architect classifies profile from spec prose); card queue retired. SPEC promotion (I130-K refinement + agent-install assumption) rides with ln-sync at PR tie-off. Outer-loop validation outstanding: greenfield cook smoke `--profile=node-vitest` (conventions-prose oracle + A98 install assumption).
+- **Objective:** Expand the FE-829 `Toolchain` contract (`project-profile.ts`) so cook builds on more technologies: profiles as data literals compiled into the existing `Toolchain` interface (consumers untouched); profile resolved once at plan time (`--profile` flag ≫ `snapshot.profile` ≫ architect-classified ≫ `bun`), persisted into `plan.yaml`; cook errors on unknown ids (lenient on absent, mirroring the `checkPlan` base/emitted split). The architect's existing schema-constrained call gains an optional profile enum — classification reads projected spec prose only (D160-K intact, no host introspection).
+- **Why now / unlocks:** Today both implemented profiles are TypeScript and the selection path is dead (`snapshot.profile` never populated) — every cook run silently resolves to bun, and a typo'd profile id silently defaults rather than erroring. Without live selection, adding profiles changes nothing at runtime; without more profiles, "brunch builds on different technologies" is false in practice.
+- **Design (ln-design 2026-06-10):** flat data registry (A) over composed axes (B — deferred until real combo demand; retreat is cheap since the consumer surface never changes); no harness install verb — the cook agent scaffolds + installs per A98 (pressure trigger: first profile where the runner fails for missing install). Deferred follow-ons: fail/infra test-outcome split in `ToolchainTestRunner`, brownfield drift-check at cook open (path-neutral by type), `brunch detect` CLI convenience. Durable end-state for selection: the spec interview captures stack as a structured field (the D164-K `mode` pattern); the chain already reserves that rung.
+- **Acceptance:** per cards in `memory/CARDS.md`.
+- **Verification:** inner — `project-profile.test.ts` (registry invariants + command shapes), `plan-runner.test.ts` (flag), `plan-emitter.test.ts` (stamping + chain precedence + fallback), `cook-cli.test.ts` (strict/lenient); middle — contract/eval suites unchanged; outer (follow-on, non-gating) — greenfield cook smoke `--profile=node-vitest` as the conventions-prose oracle.
+- **Traceability:** Requirements 46–50; A98, D160-K, D164-K (pattern), D167-K; refines I130-K (resolved profile persisted; strict-on-unknown). New assumption on build: agent-side install suffices for node profiles. Refinement on `plan-build-architect` (FE-829).
+- **Design docs:** `docs/design/orchestrator.md`; SPEC §Future Direction Cook plan generation.
+
 ### petrinaut-colour-fold
 
 - **Name:** Petrinaut export — colour-fold per-slice subnet