Project agent memory

This file is the project's committed home for project-intrinsic agent knowledge: build, test, release, architecture, and sharp-edge notes that should travel with the code.

• VISION.md at the repo root is the project's acceptance policy: what this product owns, what it refuses, and the accept/resist tests a change is measured against. Read it before proposing a feature or a policy change.
• The judge question set, score(), floorFor() and the TYPESAFE_BASE resolver typesafeEndpoint() (https for any host, http only for 127.0.0.1, [::1] or localhost) must stay byte-identical across packages/pi-extension/src/judge.ts, packages/claude-mod/lib/judge.ts, packages/codex-plugin/src/judge.ts, and packages/grok-plugin/lib/judge.ts; the TypeSafe request/response log line builders in each package's log.ts must match, as must the cooldownReason gates in each package's state.ts, the redaction helpers in context.ts/snapshot.ts, disable.ts, and the judge-profile parser in profile.ts. packages/pi-extension/test/lockstep.test.ts and test/profile.test.ts enforce all of it across every host package. Tune every copy or none.
• shellWrittenPaths() — the conservative parser that recognises files written through shell redirection, tee, and in-place sed for the savedArtifacts limb — is another byte-identical quad copy: packages/pi-extension/src/context.ts, packages/claude-mod/lib/snapshot.ts, packages/codex-plugin/src/rollout.ts, packages/grok-plugin/lib/snapshot.ts; lockstep.test.ts compares its outputs. Only the host wiring differs: pi watches tool name bash, Claude Bash, Grok run_terminal_command, Codex shell/local_shell/unified_exec plus the exec program wrapper, whose input is a const r = await tools.exec_command({cmd: "...", ...}); text(r.output); program the recognised-shape parser in rollout.ts reads the shell line out of (all extracted in rollout.ts into the tool use's paths, with the codex snapshot's WRITE_TOOLS listing those names). A Codex host contributes shell-written artifacts only when it emits one of those names, and an exec program beyond that one shape still yields nothing.
• Claude Code $.env.get takes a literal variable name, never a constant, and every name it reads must also be listed in packages/claude-mod/scripts/validate.mjs (claude plugin validate --strict compares them).
• Claude Code hooks cannot import "node:fs" and the plugin-test isolate has no process; $.fs.write replaces the whole file, so Claude writes one jsonl per session (~/.claude/compact-adviser-requests-<sessionId>.jsonl). Pi TypeSafe jsonl writes use appendFileSync (O_APPEND) in packages/pi-extension/src/log.ts.
• Every package README is generated from the root README.md; never hand-edit them. See "Package READMEs" in CONTRIBUTING.md for the mechanism (scripts/generate-package-readme.mjs, npm run sync-readmes, and the drift checks in each package's check).
• CI: .github/workflows/ci.yml runs a check-* and an e2e-* job per host package on push/PR. Pin every host binary in .github/host-versions.env.
• Grok host facts, measured against 1.0.34 and asserted by packages/grok-plugin/scripts/live-e2e.mjs: Grok lists a plugin's hooks/hooks.json but never loads it into a session, so compact-adviser install registers the same handlers in ${GROK_HOME:-~/.grok}/hooks/; the status row is the only hint surface and only the user's own config.toml can enable it; signals.json field names are undocumented, so unreadable usage takes the strictest floor. The e2e drives the real grok agent … stdio offline through --xai-api-base-url plus XAI_API_KEY, answering the OpenAI Responses API shape. lastPromptId skips a later serial Stop of the same turn but is not an atomic claim, so concurrent plugin+user-hook starts can both ask TypeSafe; follow up with a session-state claim only if Grok starts loading plugin hooks (live-e2e would then see hook_count above 6).
• packages/grok-plugin ships as TypeScript with no build step and no dependencies: Node's own type stripping runs it, so nothing there may use non-erasable syntax (no enums, no constructor parameter properties).
• Release: release-please at repo root with extra-files version bumps; npm publish --access public --provenance from packages/pi-extension via GitHub OIDC. No NPM_TOKEN. See CONTRIBUTING.md.
• Do not hand-edit CHANGELOG.md or .release-please-manifest.json.

Maintaining this file

Keep this file for knowledge useful to almost every future agent session in this project. Do not repeat what the codebase already shows; point to the authoritative file or command instead. Prefer rewriting or pruning existing entries over appending new ones. When updating this file, preserve this bar for all agents and keep entries concise.