@phyzess/pappra 0.0.0-stage → 0.1.0-beta.10

package/skills/pappra/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: pappra
+description: Use Pappra workspace knowledge, checkpoint/resume, and selected-repository code intelligence from any supported coding agent. Use when a task needs durable handoff context, workspace documents, or bounded code navigation.
+---
+
+# Pappra
+
+Pappra keeps workspace knowledge, continuity, and code navigation outside the
+host transcript. Use the installed `pappra` CLI for durable operations; hooks
+only record bounded lifecycle observations and never start a model, download,
+index, or new writer.
+
+## Start here
+
+1. Read `references/lifecycle.md` before relying on a host lifecycle event.
+2. Read `references/hosts.md` when the host surface is Pi, Codex, or Claude.
+3. Use `pappra checkpoint` / `pappra resume` for handoffs. A stored checkpoint
+   is context, not permission to execute or to trust a previous session.
+4. Use `pappra docs`, `pappra code`, `pappra runtime` and `pappra host` only for
+   the workspace selected by the current root. Never infer a workspace from an
+   unrelated session. `pappra docs scan --apply` registers discovered documents;
+   `pappra runtime install --apply` keeps a durable copy of this package.
+5. For a new bounded collaboration request, build an explicit
+   `pappra/collaboration-goal/1` from the user's objective and named choices,
+   run `pappra collab prepare --goal <file> --domain-root <dir>`, admit against a fresh capability
+   card, then use `pappra collab run` with the reviewed controller. `--controller
+pi-rpc` launches a real owned Pi session and is verified for Pi 1.3.0. Never
+   turn prose into identity, approval, or capability claims.
+
+## One-request collaboration
+
+`pappra collab prepare --goal <file> --domain-root <dir>` requires an explicit
+shared domain. It validates the canonical domain/tasks/task/private namespace
+before writing any task metadata and again around each write, so a task-root or
+mid-write directory redirect fails closed instead of scattering artifacts. It
+then writes a private task record, assignment, prompt, and resource claims; read
+resources stay read claims. The captured identities also guard live query, finish, disposal and lower RPC artifact writes; after a redirect, no new query/execution/proof/current-result pathname is written. `pappra collab run` requires an explicit `--controller <fixture|pi-rpc>`,
+performs the single admitted launch, and accepts bounded
+`pappra/collaboration-command/1` JSONL on stdin; it emits
+`pappra/collaboration-event/1` JSONL. `query` reads persisted history only and
+reports live ownership as unknown. A `finish` produces one deterministic REPORT;
+only a result whose stored classification was `applied` for the same fixed
+identity/attempt/input may repeat successfully as a duplicate — repeated
+rejections stay rejected. Cancel records and validates intent first: a denied
+intent never calls the native controller. Claims are retained and stop proof is
+never invented.
+
+Use `--controller fixture` only for deterministic, no-model tests; it is a
+restricted explicit fixture, never a silent default. The optional `pi-rpc` controller
+uses the existing owned Pi RPC daily path and preserves required skills, tools,
+MCP, hooks, and model settings; missing capabilities or stale/forged admission
+fail before launch. A native run reports only the current prompt-correlated
+result: terminal success requires a supported terminal reason and no pending
+tool call, so text-plus-toolUse/intermediate, tool-only, empty, old, malformed or
+missing answers are `unknown`; an explicit error is `failed` and an abort is
+`cancelled`. The current result must be published as validated
+`native-current-result/1` evidence; EIO/conflict/symlink/partial publication
+makes delivery `unknown`, not success, and repeated finish reuses verified
+content instead of overwriting it. A clean transport exit is not task success.
+No approval is auto-answered, no cancel is inferred from an acknowledgement, and no new thread or
+arbitrary PID is adopted. Do not launch a model or real user session without
+the task's explicit authorization.
+
+## Boundaries
+
+- Hooks are local and bounded. They do not read transcripts, run commands,
+  call models, fetch the network, or continue a conversation.
+- Missing semantic context stays missing; do not fabricate summaries.
+- Treat unknown ownership, stale bundles, untrusted hooks, and changed host
+  versions as visible conditions, not silent fallbacks.
+- Preserve user settings and unrelated keys when integrating a host.

package/skills/pappra/references/hosts.md

@@ -0,0 +1,40 @@
+# Host surfaces
+
+## Pi
+
+The project integration installs an extension plus a copied `pappra` skill; the
+generated entrypoint imports the fixed Pappra runtime by absolute file URL.
+`pappra host bundle --host pi` exports a self-contained package instead: the
+entry imports `./runtime.mjs` next to it, so the package survives a moved
+checkout. Pi 1.3.0 was verified in a real session through the packaged extension
+(`pi install <dir> -l -a` + `pi -p -a`).
+
+## Codex
+
+Codex 0.163.0 loads command hooks only from its user configuration directory.
+Wire it with `pappra host install --host codex --scope user`, which merges only
+Pappra-owned entries into `$CODEX_HOME/hooks.json` (existing hooks and unrelated
+keys are preserved) and copies the bundled hook there. Project
+`.codex/hooks.json` and plugin-bundle hooks are not loaded at this version.
+Codex hook definitions are trusted individually; installation is not trust.
+Observed 0.163.0 hook keys do not include a compact event, so compact and
+automatic checkpoint requests remain unsupported.
+
+## Claude Code
+
+The project integration installs a command-hook entry and merges only
+Pappra-owned entries into `settings.json`; the command uses
+`${CLAUDE_PROJECT_DIR}`. `pappra host bundle --host claude --marketplace` exports
+a plugin whose hook uses `${CLAUDE_PLUGIN_ROOT}`; the marketplace validates with
+`claude plugin validate` and startup was verified in a real session. `SessionStart`
+and `PostCompact` are distinct; matchers, trust, timeout, and output behavior
+remain host/version-specific. Installing a command is not proof it ran.
+
+## Common safety
+
+All surfaces use the event's canonical cwd/root, bounded stdin, a one-second
+local deadline, no transcript reads, no arbitrary configured commands, and no
+network/model/index/session side effects. Paths with spaces or Unicode are
+passed as argv/file URLs, never interpolated into a shell. Plugin registration is
+host-specific; never claim a hook is loaded because files were written or a
+validator passed.

package/skills/pappra/references/lifecycle.md

@@ -0,0 +1,41 @@
+# Lifecycle reference
+
+## Supported mapping
+
+Pappra distinguishes four local lifecycle intents:
+
+| Intent               | Pi                           | Codex                                      | Claude                                     |
+| -------------------- | ---------------------------- | ------------------------------------------ | ------------------------------------------ |
+| `startup`            | `session_start`              | `SessionStart` with source `startup`/`new` | `SessionStart` with source `startup`/`new` |
+| `resume`             | `session_start`              | `SessionStart` with source `resume`        | `SessionStart` with source `resume`        |
+| `compact`            | `session_before_compact`     | unsupported in observed 0.163.0 hook keys  | `PostCompact`                              |
+| `checkpoint-request` | explicit Pappra command/hook | unsupported automatic event                | unsupported automatic event                |
+
+The matrix is version-specific. A host version outside the observed support
+range is `unsupported`/`unknown`, not a fallback to name similarity.
+
+Codex 0.163.0 loads these hook keys only from its user configuration directory
+(`$CODEX_HOME/hooks.json`); project `.codex/hooks.json` and plugin bundles are
+not loaded by that version. Claude Code and Pi wire hooks in project scope.
+
+## What a hook does
+
+A hook validates the host payload, resolves the current workspace from the
+event cwd (never from a last-session cache), derives a bounded event identity,
+suppresses a duplicate identity, and records a private local event observation.
+It may print a short advisory context. It never starts a model, fetches,
+indexes, runs arbitrary commands, creates a new agent, or writes a checkpoint
+with invented semantics.
+
+## Manual continuity
+
+`pappra checkpoint --task <id> ...` and `pappra resume <id>` remain available
+without hooks. A hook observation is not a checkpoint and does not grant
+`executionAllowed`. A resume packet is read-only context; an unknown or
+non-stopped writer fails closed.
+
+## Reload and trust
+
+Installing files does not prove the host loaded them or trusted their exact
+definition. Report reload-needed and trust-needed separately. Do not approve a
+host trust prompt on the user's behalf.

package/skills/pappra/references/operations.md

@@ -0,0 +1,27 @@
+# Operations reference
+
+- `pappra init` plans or applies workspace configuration. `--yes` derives
+  selections from discovery, `--print-choices` prints that document without
+  writing, `--reconfigure` rebuilds an existing valid `workspace.json`, and
+  `--no-runtime` leaves the durable runtime action pending.
+- `pappra runtime <install|status|verify|remove>` manages the durable runtime
+  copy. `install --apply` defaults to `--from self`; writes require `--apply`.
+- `pappra doctor` is passive: it does not install hooks, start hosts, or fix
+  state. `runtime verify` is the active runtime check.
+- `pappra checkpoint` writes a task checkpoint; `pappra resume` reads a stored
+  snapshot and reports whether execution is allowed.
+- `pappra docs <list|check|archive|scan>` manages the knowledge catalog.
+  `scan --apply` registers documents found under the configured sources.
+- `pappra code` operates on an explicitly selected repository and keeps index
+  mutations behind an explicit `--apply`.
+- `pappra host <detect|describe|plan|install|verify|bundle>` wires an optional
+  host. Codex 0.163.0 loads hooks only from `$CODEX_HOME/hooks.json`, so use
+  `install --host codex --scope user`; `bundle --marketplace` exports a plugin
+  directory without registering it, and `install --mode plugin` fails closed.
+- `pappra collab <prepare|run|query>` runs one bounded collaboration request.
+  `run` requires `--controller fixture|pi-rpc`; `pi-rpc` launches a real Pi RPC
+  session.
+
+Preserve user bytes. If an operation reports a conflict or residual path,
+inspect that path and resolve ownership before retrying. Never delete an
+unknown file to make a retry succeed.