entwurf AGENTS.md

AGENTS.md — Maintainer Guidelines for entwurf

For agents that own this repo: invariant principles and reproducible verification, not release-story archaeology.

Direction. This repo is the entwurf capability package: a v2 garden-citizen dispatch substrate, native-harness bridges, an ACP plugin, and the pi adapter that hosts that plugin today. entwurf is the subject; pi is one harness adapter. ACP is a plugin, not the boundary (#38). V1 verbs are gone. V2 addresses existing citizens; fresh sibling creation is the separate entwurf_fresh_call capability. Current work and ordering live in NEXT.md.

North Star — One Forged Screwdriver

entwurf는 스위스 아미 나이프나 두 번째 하네스가 아니다. 이것은 담금질된 드라이버 한 자루다: 작고, 명시적이고, 맡은 접점에서만 강해야 한다.

• entwurf가 주어이고 pi는 한 adapter다. pi는 가장 깊게 붙은 하네스지만 다른 하네스보다 높은 정체성 계층이 아니다.
• 다른 하네스의 세션은 형제다. Claude Code, Codex, Antigravity, pi는 각자의 transcript/auth/runtime을 소유한다. 증명된 lifecycle과 transport가 있을 때 같은 garden address space의 citizen이 된다.
• 능력을 surface 이름으로 재단하지 않는다. 도구 이름이나 transport 비대칭은 capability 차이이지 존재의 등급이 아니다.
• substrate는 결정적 dispatch만 맡는다. record에서 identity를 읽고, rail별 liveness와 caller intent로 transport를 고른다. 숨은 hydration, ambient MCP scanning, 근거 없는 tool claim을 만들지 않는다.
• 좁은 tool surface는 규율이다. entwurf가 backend를 몰 때 sub-agent/todo 없이 한 자루 드라이버로 움직인다. 두 번째 orchestrator로 자라지 않게 한다.
• entwurf는 부속품이 아니라 분신을 연다. resumed/spawned session은 runtime-isolated peer이지 disposable worker가 아니다.
• 증거가 말을 훈육한다. README, source, gates, VERIFY, BASELINE이 받치지 않는 강한 주장은 멈춘다.

판단할 때 묻는다:

1. tool 이름을 보는가, capability를 보는가?
2. backend 비대칭을 정직하게 기록하는가, 형제성을 포기하는 핑계로 쓰는가?
3. 두 번째 하네스를 만드는가, 드라이버 한 자루를 단단하게 만드는가?
4. 이미 주어진 방향을 되묻는가, 실행 가능한 다음 증거를 만드는가?

Architecture

• entwurf-core (v2) owns garden-id addressing, peer facts, liveness interfaces, dispatch decisions, rail choice, and delivery evidence.
• Record authority owns citizen identity. Every addressable citizen uses the same V3 MetaIdentity schema. backend selects capability/rail behavior; it does not create an identity hierarchy.
• pi adapter attaches a pi session to a record at session_start, hosts the record-keyed control socket, and exposes the native pi tool surface.
• Native bridges register already-running native sessions without taking over their transcript or auth: Claude Code and Copilot CLI are mailbox/self-fetch (a Claude hook arms the watch; a forked Copilot extension holds it); Antigravity is probe-backed native-push. Codex has archived probe evidence, but its managed native lane was declined because pi already supplies the official GPT provider path; do not duplicate it as a native citizen or ACP backend.
• ACP plugin registers provider entwurf inside a pi host session and drives a backend under an isolated overlay. The host pi session is already a record-backed socket citizen; the plugin does not mint another citizen/socket/peer layer.
• mux is launch-only and deliberately small. Shipped: the tmux placement leaf (mux-placement.ts — inspect/append/close inside the caller's own session), the visible runtime launch composition (mux-launch.ts), the fresh-call composition (mux-fresh-call.ts), and the cwd-aware resume placement composition (mux-resume-call.ts). Fresh call is exposed as entwurf_fresh_call; visible same-id resume is entwurf_resume_call, composed at the two public surfaces by injecting mux-resume-call into the v2-side entwurf-v2-visible-resume.ts. The exact import graph is enumerated in docs/mux-launch-rail.md §11. entwurf_v2 behavior is unchanged and delivery still never imports launch. Fresh call learns a new sibling's garden id from the CALLBACK it makes, never from a lookup — so the pre-injected-token → identity-lookup design (rail §6) is closed, not paused. Do not reopen it without new evidence and explicit GLG re-approval. Fresh-call requires one explicit model and passes it in each runtime's measured CLI dialect (Pi --model <provider/model>, Claude Code --model=<id-or-alias>, Copilot --model <name> beside --interactive <prompt> and the explicit --yolo policy — a GLG width decision, 2026-08-25, after a callback-only --allow-tool grant stopped the sibling at every task tool); the Copilot backend opens through entwurf's OWN managed invocation (entwurf copilot), never the bare vendor, and its four required capabilities — birth, MCP hand, receiver, visible footer — are decided by copilot-fresh-preflight.ts BEFORE the tmux mutation, so a missing unit is a named refusal instead of a dead window; it also takes ONE optional literal absolute cwd (#73 — omitted/"" means the caller's own directory; no trim, no realpath, no project-name resolver; classified by the shared classify-tmux-cwd.ts leaf; the receipt echoes the REQUEST only), so a cross-repo fresh sibling is a fresh-call fact and never a reason to resume a dormant record. Resume takes only an existing target id and gets transcript/model/provider/cwd from its record. Do not grow either narrow carrier into a generic driver, harness profile, arbitrary command/env selection, or a second creation API. Ownership and import prohibitions: docs/mux-launch-rail.md §11.
• One delivery verb: entwurf_v2 addresses an existing garden id. Current routes are live control-socket send, active self-fetch mailbox enqueue, and probe-alive native-push. NO route starts a process: the hidden background resume for a dormant citizen was withdrawn under the visible-first rule, so a dormant in-domain citizen rejects as dormant-fire-forget-unsupported and the intent axis is single-valued. Every other complementary state pair rejects honestly too. Fresh creation is a separate verb — entwurf_fresh_call — and it returns a launch receipt only; the new sibling's address arrives asynchronously as the sender envelope of its nonce callback.