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

package/skills/pappra/SKILL.md

@@ -0,0 +1,68 @@
+---
+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` and `pappra code` only for the workspace selected by the
+   current root. Never infer a workspace from an unrelated session.
+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. 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,30 @@
+# Host surfaces
+
+## Pi
+
+The integration installs a project extension plus a copied `pappra` skill.
+Pi extensions run with host permissions. Load only a trusted copy from this
+workspace/target; the generated entrypoint imports the fixed Pappra runtime by
+absolute file URL and registers lifecycle handlers only.
+
+## Codex
+
+The integration installs a command-hook entry and merges only Pappra-owned
+entries into `hooks.json`. Existing hooks and unrelated keys are preserved.
+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 integration installs a command-hook entry and merges only Pappra-owned
+entries into `settings.json`. `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.

package/skills/pappra/references/lifecycle.md

@@ -0,0 +1,37 @@
+# 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.
+
+## 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,14 @@
+# Operations reference
+
+- `pappra init` plans or applies workspace configuration.
+- `pappra doctor` is passive: it does not install hooks, start hosts, or fix
+  state.
+- `pappra checkpoint` writes a task checkpoint; `pappra resume` reads a
+  stored snapshot and reports whether execution is allowed.
+- `pappra docs` manages knowledge documents.
+- `pappra code` operates on an explicitly selected repository and keeps
+  index mutations behind an explicit `--apply`.
+
+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.