feat: scenarios for curator/memo-inbox/pi-grok, deploy and backup tooling

Scenarios
- memo-inbox: mirrored by copying; the live directory was not moved or modified
  and the service was not restarted. All four tracked files match byte for byte
  (pi-diff.sh reports SAME). Marked deploy = "mirror" so deploy-scenario.sh
  refuses --apply: applying a mirror would invert the direction of truth and
  could change a service in daily use.
- curator: target configuration, not yet deployed. .pi/SYSTEM.md replaces pi's
  coding-assistant prompt; durable role text is in .pi/APPEND_SYSTEM.md;
  profile.toml is the single source of truth for the launch contract.
- pi-grok: registered only. It is genuinely a coding agent, so the isolation
  baseline does not apply in full.

Corrections to the documentation, found by testing rather than by reading
- AGENTS.override.md does NOT block parent-directory context files; it only
  shadows its own directory. Verified: with an override file in the workspace, a
  marker in /tmp/AGENTS.md still reached the system prompt. The only effective
  switch is --no-context-files, so durable role text must live in
  .pi/APPEND_SYSTEM.md, which is a system-prompt file and unaffected by -nc.
  Verified end state: no coding-assistant framing, no pi-docs block, own
  identity and role text present, no parent pollution, only own skills/tools.
- PI_CODING_AGENT_DIR isolates settings/models/auth/trust/extensions/skills/
  prompts/themes under the agent directory -- stronger than the --no-* flags
  because it also repoints credentials -- but does NOT cover ~/.agents/skills.
  Measured: find-skills, modsearch and summarize still leak. So it complements
  --no-skills rather than replacing it.
- --append-system-prompt accepts a file path, which pi-grok relies on.
- cwd is what anchors .pi discovery: a probe that forgot cwd silently lost
  .pi/SYSTEM.md and kept the coding-assistant persona.

Tooling (all dry-run by default; none of them restarts a service)
- pi-diff.sh: compares tracked config against the live install in both
  directions, with a key-redacted comparison for models.json
- deploy-scenario.sh: installs a workspace and renders profile.toml into
  .pi/launch.json, then checks that every referenced path exists
- deploy-runtime.sh: renders models.json from its template, refusing placeholder
  or missing keys. Verified byte-identical to the live file
- pi-backup.sh / pi-restore.sh: archives outside the repo, sha256 manifest
  verified before any restore, live paths preserved rather than overwritten

Fixed while testing: pi-backup.sh compared the destination against the repo root
literally, so a relative --dest ./backups wrote credential archives into the work
tree. Now canonicalised with realpath; ./backups, an absolute in-repo path and
./docs/../backups are all refused.
This commit is contained in:
Kai
2026-08-26 23:17:12 -07:00
parent 7b5e0b093d
commit 07dd648b5f
20 changed files with 2611 additions and 17 deletions
+26 -2
View File
@@ -37,13 +37,37 @@ guidelines.** If you replace, you own both.
| `.pi/SYSTEM.md` | needs trust (`--approve`) | always in context | Identity. Tool overview. Fact-authority map. Write discipline. Untrusted-data rule. Output format. |
| `.pi/APPEND_SYSTEM.md` | needs trust | always in context | Nothing, normally. Use only when you want to keep pi's default prompt and bolt something on. |
| `AGENTS.md` (workspace) | always | always in context | Durable role, responsibilities, routing, domain defaults, escalation policy. Human-editable narrative. |
| `AGENTS.override.md` | always | always in context | Same as `AGENTS.md`, but also **stops** `AGENTS.md`/`CLAUDE.md` from that directory. Use to make the personality deterministic against stray parent files. |
| `AGENTS.override.md` | always | always in context | Same as `AGENTS.md`, but shadows `AGENTS.md`/`CLAUDE.md` **in its own directory only**. It does *not* stop parent directories — verified. Rarely the right tool. |
| `.pi/skills/<n>/SKILL.md` | needs trust, or explicit `--skill` | **description only** up front; body read on demand | Task-specific procedure that is not needed on every turn. The place for long checklists and worked examples. |
| Per-request prompt | n/a | per call | Only the current inputs and the schema for this one response. |
### Deterministic personality requires `-nc`
Context files layer from `~/.pi/agent/AGENTS.md` and from **every parent
directory** of the working directory. `AGENTS.override.md` shadows only its own
directory, so it cannot protect you: with an override file present in the
workspace, a marker placed in `/tmp/AGENTS.md` still reached the system prompt.
The only switch that stops the upward walk is `--no-context-files` (`-nc`), and it
drops the workspace's own file too. So for an agent whose personality must be
reproducible:
- pass `-nc`;
- put identity in `.pi/SYSTEM.md`;
- put durable role text in `.pi/APPEND_SYSTEM.md`;
- keep no `AGENTS.md` in the workspace at all.
Both `SYSTEM.md` and `APPEND_SYSTEM.md` are system-prompt files, not context
files, so `-nc` does not affect them. Verified: identity and role text present,
parent marker absent.
`AGENTS.md` remains the right slot for a *shared, layered* convention — for
example a repository-wide instruction that every agent working in a source tree
should honour. It is the wrong slot for a single-purpose service agent.
### Rule of thumb
- Needed on **every** turn → `SYSTEM.md` or `AGENTS.md`.
- Needed on **every** turn → `SYSTEM.md` or `APPEND_SYSTEM.md`.
- Needed on **some** turns, and long → `SKILL.md`.
- Changes **per request** → the request.