pi-zense

Spec-gated, human-signed SDLC harness for pi. Human attention is the scarcest resource in AI-driven development — pi-zense concentrates it at exactly two gates: signing the spec and reviewing the result. Everything in between is automated.

"Zense" is Thai for "sign" — every run ships under a human signature.

What you get

• Spec as a contract — a requirements sub-agent drafts machine-checkable acceptance criteria (probed for real, not guessed); nothing gets written to your repo until you 🔏 sign — right in the dialog, full spec rendered inline.
• Isolated sub-agents per phase — compile, grade, and review each run in clean pi -p contexts; watch them live with ctrl+_.
• Worktree-per-session — after signing, work happens in an auto-created git worktree; open two pi sessions in the same repo and they never clobber each other.
• Dual eval — deterministic probes + a grader sub-agent judge every criterion; trajectory heuristics catch reward hacking (test edits, out-of-scope writes, retry storms).
• Human-in-command merge — on eval PASS, work is squashed and applied to main staged-but-uncommitted. You review the staged diff, then accept or discard — the harness never auto-commits on main.
• Memory that feeds back — every flag, escalation, and verdict becomes a lesson that shapes the next spec.
• zense theme — a dark theme on the Zense design system (green → lime → gold over near-black).

Install

pi install git:github.com/zurge-co/pi-zense   # git
pi install npm:pi-zense                       # npm (when published)
pi -e ./pi-zense                              # try without installing

Theme (optional): /settings → theme → zense.

Quick start

1. Tell the agent what to build       → it compiles a spec with checkable criteria
2. 🔏 Sign in the dialog (gate #1)    → read the spec inline, then sign or send back
3. Let it run                         → widget shows phase/turns/tokens; ctrl+_ to watch sub-agents
4. Review the packet (gate #2)        → TL;DR first, spec-debt and trajectory flags highlighted
5. Commit & `/zense accept` — or `/zense discard` to reverse-apply the patch exactly

If the agent tries to write code before the spec is signed, a 3-choice dialog stops it: 🔏 sign & continue / ⚠ one-off override / ⛔ block.

Human cheat sheet

You only have two real jobs (🔏 sign, 📋 review). Everything else:

Command	When	What it does
/zense approve	sign later, if you skipped the dialog	sign the current spec
/zense status	anytime	phase, gate, flags, pending apply
ctrl+_ / /zense agents	while sub-agents run	live tail of grader/reviewer runs
/zense accept	after review & commit	close the pending apply, log post-review edits as lessons
/zense discard	review says no	reverse-apply the stored patch, restoring exact pre-apply state
/zense gate on|off	emergency	toggle the spec gate
/zense memory	anytime	grouped lesson summary (json = raw)
/zense distill	anytime	compact .zense: confirm y/n (impact summary) → read-only distiller sub-agent condenses all of memory.jsonl into one lesson set (same JSONL format, parser untouched) → deletes specs/ + subagents/ history; never touches adr/, configs, or current spec; aborts without deleting if distillation fails

Files

pi-zense/
├── package.json                  # pi manifest
├── extensions/
│   └── zense-harness/ index.ts, README.md   # the harness (full docs here)
└── themes/
    └── zense.json                # Zense dark theme

Per-project runtime artifacts (spec archive, ADRs, memory) live under each repo's .zense/ — spec-as-code, diffable and auditable.

License

MIT