AGENTS.md · MichaelKinsy/PiG

Sections

1. Mission
2. Product-extension boundary
3. Pig-owned format and update policy
4. Extension API porting rules
5. TypeScript-to-Go semantic translation
6. Faithful, general implementations
7. TypeScript async/Promise parity
8. Reward function
9. Loop smells
10. Loop self-report
11. Coverage
12. Reliability contexts
13. Upstream test parity
14. Verification-driven development
15. Done criteria
16. Parity scenario rules
17. Divergences
18. Native Windows development
19. Code and lint policy
20. Commands

First lines (shown under the repo's MIT license)

# AGENTS.md

Operating rules for AI agents maintaining `pig`, the Go port of upstream `pi`. This file is context, not human marketing. Keep it small, current, and enforceable.

## Mission

`pig` must match upstream `pi` observable behavior unless `docs/parity/DIVERGENCES.md` records a numbered, scrutinized exception. Treat the port as a compiler from upstream TypeScript behavior to Go behavior: `docs/parity/PORT_MAP.md` defines the file map, parity scenarios define behavior, `test/parity/coverage.md` reports proof, and gates keep the claims honest.

Source of truth:
- `.upstream/current/` is the upstream mirror.
- `.upstream/pin` is the one upstream pin: a Pi release tag, or a pinned pi-mono commit (`ref`, `commit`, `package_version`, display `version` such as `1.1.0+42a3497d`). `internal/coding/pigversion/pigversion.go` is generated from it (re-exported by `coding/upstream.go` as `coding.UpstreamVersion`, `coding.UpstreamPackageVersion`, `coding.UpstreamCommit`). `PI_UPSTREAM_REF=<tag|commit>` overrides the pin for one run, and `make pin-bump PI_UPSTREAM_REF=<tag|commit>` moves it and regenerates what derives from it (`docs/parity/upstream-pin.md`).
- `docs/parity/PORT_MAP.md` maps upstream files to Go files, deferred entries, or designed-out entries.
- `test/parity/scenarios/<family>/*.toml` define observed behavior.
- `test/parity/interfaces/upstream-v<version>.json` is the compiler-derived public
  package interface denominator; observable adapter inventories such as
  `cli-v<version>.json` extend it for non-package user contracts;
  `mapping-v<version>.json` records each Pig disposition and closure evidence. Generated inventory drift and strict mapping
  are Foundation gates. PORT_MAP remains the file navigation roll-up until
  Foundation I finishes generating its statuses from these ledgers.
- `test/parity/upstream-sync/v<version>.toml` accounts for every changed tracked source file in a version leap.
- `test/parity/async-contracts.toml` accounts for Promise/async semantics across the complete pinned upstream source tree.
- `test/parity/coverage.md` and the generated block below report verification.
- `docs/parity/DIVERGENCES.md` records intentional differences.

No prose status claim overrides those files.

If you change exported Go API, CLI flags, settings, parity scenarios, or docs mirrors, run `make generate` and commit the result. CI's drift gates compare these files. Never hand-edit generated files; regenerate.

When landing a new port, record its full upstream source path in a production
`// Ports packages/.../file.ts` comment and update PORT_MAP in the same change.
The drift gate rejects explicit port claims left not-started, deferred, or n/a.
Use partial until behavioral closure is reviewed; source existence is not proof.

## Product-extension boundary

Stock PiG contains upstream-parity behavior and the inert, product-neutral mechanisms needed to discover, validate, select, build, verify, load, isolate, and run Packages, Resources, extensions, Piglets, and Piglet Binaries. A Piglet selects and activates product behavior. PiG Standard owns branded presentation, opinionated defaults, selected extensions, onboarding, games, and other optional product workflows.

Classify every proposed additive capability before implementation:

1. `required substrate` remains in Stock PiG.
2. `inert capability` remains in Stock PiG only when an extension or Piglet must select it.
3. Composition, presentation, policy, and branded behavior belong in PiG Standard or another explicit Piglet or Package.
4. Caller-free or unneeded behavior is deleted.
5. Behavior that overlaps Pi but differs observably is fixed or recorded in `docs/parity/DIVERGENCES.md` after explicit approval.

Use `product-neutral diagnostics` for generic reports that describe Stock mechanisms. Use `explicit unsafe opt-in` only for a capability that stays off by default, is visible at configuration boundaries, and must not be selected by PiG Standard.

A Piglet cannot supply the parser, resolver, verifier, SDK bridge, isolation boundary, or build machinery needed to load itself. Do not move those bootstrap mechanisms into PiG Standard. Do not activate Standard behavior in Stock PiG. Do not put product UI, Piglet-specific recommendations, workflow-specific logic, or linked extension products under `internal/` or `cmd/` except for the minimum generic host capability.

Additive records use `docs/additive-features.md`. Observable Stock PiG differences use `docs/parity/DIVERGENCES.md`. Place one short typed source marker at each production decision point. Tests do not satisfy the source-marker requirement.

Change the version only with `make set-version VERSION=x.y.z`.

## Pig-owned format and update policy

Pig-owned source, manifest, record, graph/plan, builder, Marketplace,
publication, and subprocess formats have one strict current unversioned shape
while Pig and its clients upgrade atomically. Release/content identity, exact
upstream-owned schema versions, and external-standard versions remain. Do not
add a Pig-owned format discriminator, negotiation, compatibility reader,
migration, redirect, or dual write unless exact upstream regularly versions the
equivalent schema or the user explicitly approves independently deployed
compatibility.

Self-update preserves Pi's command routing but uses one proven native ownership
tier per operation. Standalone download, package-manager, immutable
Piglet Binary, OCI/Image, and unsupported/read-only paths must
not substitute for one another after work starts. Downloads require complete
checksum and overflow-safe size verification; startup checks remain bounded and
best-effort, while explicit update failures remain actionable.

## Extension API porting rules

The pig extension system is a **port** of the upstream pi extension API,
not a replacement for it. Two downstream-only constructs exist so we can
stay subprocess-only without giving up the pi extension API:

- **Multi-language SDK bridges** (`extensions/sdk`, `extensions/sdk-rs`,
  `extensions/sdk-py`): see `docs/additive-features.md` D19 and
  `docs/extension-api-parity.md` “Parity boundary”. All three SDKs target the
  **same current wire contract** in
  `coding/extension/host/subprocess/protocol.go` and the same
  registration/host-call/tool-result shapes. The wire has no independent
  version or compatibility negotiation. The conformance suite in
  `test/extension-conformance/` is the
  authority: a new SDK feature is only “done” when it matches the
  in-process Go reference there.

  Every SDK exposes the same extension API. Separate the three axes:

  - **Interface**: the set of capabilities and their parameters and return
    meaning. Identical across SDKs, modulo the naming convention.
  - **Behavior**: what a call returns for a given host state, including
    error and edge cases. Identical across SDKs.
  - **Implementation**: how an SDK produces that answer: host call versus
    replicated state, sync versus async internals, threading, allocation,
    borrowing, error representation. Free to differ per language.

  Implementation variance is expected and needs no record. Interface or
  behavior variance is drift. Returning a constant where another SDK
  returns host data is a behavior divergence even though the interface
  matches, and it is worse than a missing method: a missing method fails
  loudly at the call site, while a plausible constant is silently believed.
  A stub is therefore not an acceptable resting state, and "the host call
  is async but this API is sync" is a reason to replicate the value into
  state, not a reason to fabricate one.

  An extension is portable between SDKs by rewriting it, not by
  rearchitecting it or dropping a feature. A capability landing in one SDK
  is unfinished until it lands in all of them with a conformance row that
  fails when any one is broken. Bind that row to a value distinguishable
  from each SDK's fallback, or an SDK that never makes the call passes by
  defaulting.
- **Packed runtime cells** (`coding/extension/host/subprocess/cell_plan.go`,
  `coding/extension/host/runtimecell/`): see `docs/additive-features.md` D20. These
  are a host-side optimization. Each contained extension keeps its own
  socket and its own `register` handshake. Packed mode must
  be observationally identical to isolated mode from the extension’s
  point of view; if a difference appears, fix the host or add a numbered
  divergence: do not change the SDK API to paper over it.

Do not, without an explicit approved spec:
- add a WASM or embedded-JS extension runtime,
- add a dynamic Go plugin / `plugin.Open` extension loader,
- add a linked/in-process production extension runtime, except the compiled-in extension factory form of `docs/specs/extension-factory-trust.md`: an `extension.ExtensionFactory` that the source of the binary's own `main` package passes to the loader by value (Stock PiG's built-in rows, or an embedding program's own factories). A Piglet member, including a D31 fused extension, never uses it. Settings and `-e builtin:<name>` may select or disable a registered built-in by name, as Pi does; no user, project, Package, file, settings entry, Piglet, or wire peer can supply or add factory code,
- introduce multi-register (`RegisterPayload.Extensions`,
  `RequestPayload.TargetExtension`): packed cells deliberately stay on
  one socket and one registration per extension,
- diverge SDK semantics from the in-process Go reference without first
  numbering the divergence and citing a failing conformance test.

When adding a host-side feature, first read `docs/extension-authoring.md`.
The implementation order is: upstream pi behavior → protocol shape in
`protocol.go` → host wiring in `coding/extension/host/subprocess/` → SDK
ergonomics in each `extensions/sdk*/` → conformance test row → parity
matrix row in `docs/extension-api-parity.md` → numbered divergence if
needed.

`extensions/sdk-ts` is a declaration-only adapter. It re-exports the exact
pinned Pi extension declarations and augments them with PiG-only types. The
Node subprocess runtime remains the implementation, so do not duplicate Pi's
TypeScript runtime in this package. Keep its Pi dependency equal to
`coding.UpstreamVersion` and verify it with `make test-sdk-ts`.

Extension authoring has two source forms. A conventional factory uses the one
standard symbol for its language; an exact standalone is always isolated. Pig
derives wire, SDK, runner, placement, and registration details. Runtime
registration owns identity and capabilities. Do not add an authored extension
manifest or another global extension configuration plane. Isolated, packed, and
fused realizations of one factory must pass the same conformance behavior.

## TypeScript-to-Go semantic translation

Read `docs/typescript-to-go-porting.md` before translating a new behavior
family or changing a parity-facing Go representation. Port observed semantics,
not TypeScript syntax: account explicitly for omitted/undefined/null state,
closed unions, insertion order, UTF-16/code-point/terminal-cell units, numeric
conversion, exceptions, callback ownership, Node path/URL/regex/JSON behavior,
and every state or wire effect that callers observe. A TypeScript `interface`
does not imply a Go interface; use a struct for data and a small consumer-owned