Keep AI coding agents inside the task, preserve project decisions across sessions, and know when the work is done.
PSG gives coding agents a persistent task boundary and project state instead of making every model rediscover the repository and redefine the scope from scratch.
python -m pip install "psg-runtime[mcp] @ git+https://github.com/niansia/PSG.git@v1.1.4"; psg setuppython3 -m pip install "psg-runtime[mcp] @ git+https://github.com/niansia/PSG.git@v1.1.4" && psg setupThen, inside a Git project:
psg init
That's it. Use Codex, Claude Code, or Gemini CLI normally.
psg status
psg on
psg off
Without PSG, a coding agent can keep discovering more files, more refactors, and more review suggestions until a small task becomes a project-wide rewrite.
PSG gives every task a boundary:
- Context boundary — what the agent needs to read.
- Mutation boundary — what it may change.
- Review boundary — which findings may block this task.
- Completion boundary — when the task is done and review must stop.
A reviewer may still discover unrelated bugs or future improvements, but PSG records them as follow-up work instead of silently expanding the current task.
Review the task, not the universe.
A task that only needs to fix A does not automatically become A + B + C + D because another model noticed more things that could be improved.
Accepted decisions, constraints, frozen boundaries, and known debt do not need to be explained again every time the agent or session changes.
Only a regression caused by the current patch, an acceptance-criterion violation, or a project-constraint violation can block the current task. Other findings remain visible as follow-up work without reopening it.
When acceptance criteria, deterministic verification, guardrails, and current-task blockers all agree, the gate returns:
SHIPPABLE
General review stops there.
Evidence status: Superseded.
This run is preserved for transparency, but it is not evidence of current-version performance. Codex loaded an older installed PSG Skill than the runtime under test, and the retrieval integration has since changed.
The historical run contains 10 matched Codex CLI task pairs using the same model, prompt, and repository baseline.
| Metric | PSG OFF | PSG ON |
|---|---|---|
| Task success | 9 / 10 | 10 / 10 |
| Non-target edits | 10 | 2 |
| Regressions | 0 | 0 |
False SHIPPABLE |
0 | 0 |
The historical result showed better task-boundary discipline, but with measurable token and latency overhead. Because the run is superseded, it is not evidence of current-version performance. PSG currently claims no token or time savings from it.
See the benchmark protocol, raw results, and disclosed limitations.
Git remains the implementation source of truth. PSG stores durable decisions and task state instead of full conversations. Context may expand when needed; write authority does not silently expand with it.
| Mode | Hosts | Capability |
|---|---|---|
| Full execution | Codex, Claude Code, Gemini CLI | Read, edit, verify, enforce, and ship |
| Review / handoff | ChatGPT, Claude, Gemini | Review against the same Task Contract |
All hosts can use the same Task Boundary; execution hosts additionally receive runtime enforcement. Use psg handoff to create a compact review pack for another model or teammate.
- Rich symbol indexing is Python-first; other languages receive file-level indexing.
- The included agentic benchmark uses a small generated repository, not production projects.
- A fresh matched A/B run is still required for the current localization behavior.
- PSG has no authenticated external CI attestation adapter yet.
- PSG governs and evaluates changes; the coding agent still performs the edits.
- Installation and host setup
- Task Contract and review boundary
- Trust and security model
- CLI and MCP reference
- Architecture
- Acceptance and release evidence
- Benchmarks
- Research
A separate mechanics regression benchmark verifies that routing can reduce selected context when the relevant target is already known. It is not an end-to-end agent token-savings claim.
PSG is also being evaluated as a long-horizon software-agent research system. See the evaluation plan.