Pi Sych

Visible project state · bounded delegation · human-owned decisions

Public contract and compatibility

This document is the authority for Pi Sych’s supported userland. Shipped source is not automatically public API. The initial compatibility baseline is the documented 4.0.6 behavior; where that baseline is ambiguous, preserve an existing documented workflow rather than retroactively calling it internal. The v8 package targets Pi 0.99.2 or newer; repository checks pass against Pi 0.99.2 and 1.0.0.

Surface classification

Class Supported surface Compatibility promise
Public userland The pi-sych npm identity, MIT docs/LICENSE.md, declared package resources, and the Node/Pi compatibility policy published with the package. The package requires Node 26 or newer and declares the Pi coding-agent peer dependency as >=0.99.2; other Pi interfaces retain *. Its dev dependency range also starts at Pi 0.99.2; use a release that can install and run the declared resources. Installation and documented use remain compatible within the release rules below.
Public userland Seven skills: project, write, analyze, code, review, research, and automation; their documented capability scope and ordinary /skill:<name> invocation. A copied override is user-owned and version-decoupled. Skill names and documented scope are stable. Hidden methods and local module layout are not separately invokable userland.
Public userland Package extension paths extensions/workbench/index.ts and extensions/plannotator/index.ts, for Pi package filtering and pi config. Paths and declared default resources remain usable as documented.
Public userland Tools: project_status (check or acknowledge, optional files and reason) and dispatch_worker (task, tool mode, expected output, context files, and documented optional context mode, model, skill, remote-research, thinking level, timeout, and worker-instructions fields). A context-file path is project-relative or an explicitly supplied readable absolute path; contextMode is clean or trajectory and defaults to clean; optional thinkingLevel is one of off, minimal, low, medium, high, xhigh, or max and omission delegates to the selected model’s default. Input schema, result categories, and material effects are stable: status mechanically checks/acknowledges; dispatch creates one bounded worker, exposes a bounded live projection of its tool starts, and returns the validated terminal result plus reportedFiles, observedChangedFiles, unexpectedChanges, and optional observationError. On interruption or process failure, a structurally valid submitted report may be retained as interruptedReport (report plus warning), never as a successful result; claimed status and paths may be incomplete, inaccurate, or no longer present. The primary error remains. Changed paths are observed after every worker termination; observation does not roll changes back. In Git projects the snapshot reports changed tracked/untracked paths; non-Git project roots use a filesystem snapshot. Trajectory mode branches from persisted supervisor context immediately before the dispatching assistant entry, without mutating the live session, and fails if that boundary is unavailable. Thinking level is passed to Pi via --thinking and model capability may clamp or interpret it; Pi Sych validates only the documented global enum. Optional workerInstructions supplies per-dispatch instructions through Pi’s native AGENTS context-file discovery in a private temporary worker agent directory; omission injects nothing and leaves the configured worker agent directory untouched. The launch-scoped AGENTS.override.md preserves existing worker agent instructions before the supplied guidance, and project/ancestor AGENTS files continue to load by Pi’s normal precedence.
Public userland Commands: /pi-sych-status, /mcp, pi mcp list, pi mcp login, pi mcp logout, /plannotator-last, /plannotator-annotate <project-local-markdown-file> (accepting .md and .mdx), and /plannotator-review [--git|--gitbutler] [--no-local] [PR-URL]. Native MCP commands/status belong to Pi; no Pi Sych MCP status wrapper is provided. Plannotator commands are available when its optional dependencies and compatible adapter are present; otherwise core startup continues. Plannotator remains a review adapter, not plan control or automatic promotion.
Public userland literature_search, available directly to the supervisor and to a dispatched worker whose selected skills include the exact research selector. It accepts a non-empty FTS query and optional limit from 1 to 50, defaulting to 10. Read-only results provide compact readable content and structured data: nullable title, itemType, creators, year, and doi, plus snippet, score, and resolved sourcePath. Results are discovery/provenance, not source verification. Workers without research do not receive it.
Public userland Pi Sych v2 configuration: global <pi-config-root>/pi-sych/config.json, layered with optional project .pi/pi-sych/config.json; supported keys are version, compaction.custom, compaction.thresholdTokens, completionReassessment, and literatureDatabase. Global settings load first and project keys override only matching keys, including nested compaction fields. Unknown keys are rejected. Custom compaction defaults on; the proactive threshold defaults to 150,000 context tokens and is not Pi reserveTokens. Completion reassessment defaults off; when enabled, one hidden prompt may request a single continuation at a safe Pi agent_before_settle boundary, without broadening authorization. The literature path may be absolute or relative: global-relative paths use the global Pi Sych config directory, project-relative overrides use the project root. If absent, the conventional config-directory literature.sqlite fallback applies (with existing project LITERATURE.sqlite discovery). No credentials belong in these files.
Public userland The v7 SQLite papers plus external-content FTS5 papers_fts schema, including item_type, creators_json, and the literature_search metadata result. Pi Sych opens the database read-only and does not migrate it. item_type is text or SQL NULL; creators_json is SQL NULL or JSON text containing a non-null, non-array object of role arrays of non-null, non-array name objects. JSON text null is rejected. Pi Sych checks this structure, not CSL semantics or citation formatting; see configuration for null and failure semantics. v6 databases and consumers require external migration; see the v7 literature migration guide.
Public userland remoteResearch worker intent flag. When true, the worker explicitly loads native Pi MCP and codemode and reads MCP configuration from its worker agent directory. Configure/authenticate it with native Pi MCP commands. Supervisor MCP configuration and tools are not copied; ordinary workers receive neither MCP nor codemode. Exposure does not guarantee working credentials or retrieval.
Public userland Project formats: SYNC.json v2; required headings in the configured project brief (default PROJECT.md); acknowledgement meaning; proposal-line grammar; and stable paths in templates/. Generated locations include the configured inbox path (default INBOX.md), <input>.feedback.md, <projectRoot>/PLANNOTATOR_REVIEW.md, and worker bootstrap settings. Schemas, grammar, templates, configured canonical paths, and documented file behavior are stable. Malformed or unreadable SYNC.json state is reported as unavailable and cannot be acknowledged; extension startup remains available so that state can be inspected.
Public userland Five thin packaged review prompts (review-collaborative, review-adversarial, review-reader-friction, review-structural, and review-verification). Each selects a review lens and defers substantive procedure to the review skill; prompts return findings and do not silently edit, orchestrate agents, or imply approval.
Public userland Packaged public documentation, including the v7 literature migration guide, v7 to v8 migration guide, this contract, COPYING.md, docs/LICENSE.md, and notices in docs/LICENSES/. These documents and notices remain available in the package.
Compatibility-sensitive internal Model-facing supervisor, worker, compaction, completion-reassessment, and persisted-session protocols. Not a TypeScript API. Changes still need migration analysis, regression tests, and release notes when sessions or model behavior may be affected. Custom compaction uses bounded observable messages, retained tail, and canonical snapshots, preserves recorded label attributions without verification, appends only bounded unreviewed inbox proposals, never mutates canonical semantic files, and returns native fallback when no usable required summary exists or model execution fails. It can extract a JSON object surrounded by prose or Markdown fences; omitted or malformed optional memory fields/collections normalize independently, and invalid members are skipped so valid array entries survive mixed output. Required objective/next-action fields and allow-listed provenance remain strict; provenance is never invented. Unsafe inbox destinations or proposal-write failures skip proposals without discarding usable memory. Cancellation during inbox safety/directory awaits is checked before proposal append, and unavailable inbox counts are reported as unavailable rather than zero.
Internal implementation Undocumented TypeScript exports; deep extensions/**/src paths; local modules and hidden methods; fixtures; exact incidental error wording; and benchmark internals. No library-import API is supported unless deliberately documented later. Error category and fail/omit behavior are public; punctuation and incidental wording are not unless machine-readable.

Model prose is not deterministic API. Documented capability scope, human ownership, non-invention boundaries, and material side effects are.

Releases and migration

A release level follows required user migration, not implementation size.

Security or correctness can justify an incompatible change, but not calling it non-breaking: make a major release or publish an exceptional supported migration. Deprecate in a minor and remove only in an authorized major. Changing a default from on to off is breaking when users materially lose behavior. Adding an independently disableable resource while retaining the default is minor. Version 5.0.0 is major because it removes documented PI_SYCH_* configuration overrides and relocates configuration into the unified visible directory. The v8 native-MCP transition removes MCPorter and /pi-sych-mcp; use the worker’s own native Pi MCP configuration and /mcp instead. The v7 to v8 guide documents obsolete config-key removal and new layered behavior.

Before release, name the affected row above, say whether a documented use needs migration, check stored state and default-side-effect changes, and justify the major/minor/patch choice in the changelog. Prepared package metadata and changelog entries do not establish publication; publication status comes from the signed release tag and npm registry metadata. Test public names, schemas, declared resources, templates, and file behavior without creating a second registry or freezing semantic prose into keyword checks.