proofpress 0.0.1 → 0.1.0-alpha.1

package/skills/README.md

@@ -0,0 +1,105 @@
+[//]: # (ob:df70df88)
+# Proofpress harness adapters
+
+[//]: # (ob:93121540)
+The skill captures rich decision context when an accepted Markdown or static
+HTML artifact version is still fresh. The hook is only a best-effort fallback. `ingest`
+backfills Git history, and the embedded capsule carries portable history beyond
+Git.
+
+[//]: # (ob:1744e48a)
+| Layer | What it knows | Attribution rule |
+|---|---|---|
+| Skill | accepted version, claims, why, consequential rejection | supplies known actor roles and basis |
+| Hook / `capture` | changed, staged, and untracked Markdown or static HTML | supplies only `recorded_by` |
+| `ingest` | committed content and Git author | attributes from Git metadata |
+| Portable capsule | admitted records attached to the artifact | preserves recorded fields; invents none |
+
+[//]: # (ob:50c32349)
+## Shared contract
+
+[//]: # (ob:a2f15f7d)
+1. Work only on Markdown or static HTML knowledge artifacts, never source code.
+2. Read the artifact policy. Enable `portable` once when requested; it stays on
+
+[//]: # (ob:23c62cea)
+   until explicitly changed.
+
+[//]: # (ob:7109fe56)
+3. Preserve carrier-native block anchors (Markdown `ob` markers; static HTML
+
+[//]: # (ob:f8ee70a6)
+   `data-proofpress-id`), run `anchor`, and write honest claims for touched or
+   removed blocks.
+
+[//]: # (ob:9d481ea6)
+4. Snapshot accepted, meaningful versions—not every turn or save—with `--why`
+
+[//]: # (ob:9710997f)
+   and explicit known actors.
+
+[//]: # (ob:c8f43a25)
+5. Use `--rejected` only for consequential dead branches. Never infer rejected
+
+[//]: # (ob:41bb2485)
+   paths from casual discussion or store raw prompts/transcripts.
+
+[//]: # (ob:3991a868)
+6. Run `verify` and report its output verbatim. A mismatch is evidence, not a
+
+[//]: # (ob:a08bfb00)
+   reason to manufacture another snapshot.
+
+[//]: # (ob:a8bc86e1)
+7. On receipt of a portable artifact, run `inspect` before `import`.
+
+[//]: # (ob:f5f3a858)
+## Install
+
+[//]: # (ob:8a9fcf71)
+The npm installer is the recommended path. It installs package-aware adapters
+that use `npx --no-install`, so agents never download the package implicitly:
+
+[//]: # (ob:5ee2d540)
+```sh
+npm install --save-dev proofpress@next
+npx --no-install proofpress setup --agent codex
+```
+
+[//]: # (ob:3328131b)
+Use `--agent claude`, `--agent cursor`, or `--agent all` for the other supported
+harnesses. Add `--badge README.md` only when the repository owner wants a
+visible Proofpress provenance mark.
+
+[//]: # (ob:041482f5)
+For a vendored `proofpress.py`, install adapters manually:
+
+[//]: # (ob:0e468706)
+- Claude Code: copy `claude-code/proofpress/` to `.claude/skills/` and merge
+
+[//]: # (ob:225dd61c)
+  `claude-code/hooks-example.json` into `.claude/settings.json`.
+
+[//]: # (ob:3e5fba6b)
+- Codex: append `codex/AGENTS-snippet.md` to `AGENTS.md` and merge
+
+[//]: # (ob:3ef5e70c)
+  `codex/config-hooks.toml` into the Codex configuration.
+
+[//]: # (ob:9d561c7d)
+- Cursor: copy `cursor/proofpress/` to `.cursor/skills/proofpress/` or
+
+[//]: # (ob:9cddddf2)
+  `.agents/skills/proofpress/`, then start a new Agent chat.
+
+[//]: # (ob:2202e132)
+- Pi: install `pi/proofpress-skill.md`; `pi/extension-skeleton.ts` is an
+
+[//]: # (ob:cc2d6144)
+  intentionally untested extension sketch whose event API should be checked
+  against the installed Pi version.
+
+[//]: # (ob:c883ac9d)
+Adapters expect `proofpress.py` at the repository root.
+
+[//]: # (proofpress:meta:eyJhcnRpZmFjdF9pZCI6InBwX2U3NGJlMDlhOWQyOGYxODU1ZGI0YTAwNyIsInBvbGljeSI6ImxvY2FsIiwicHJvb2ZwcmVzcyI6MX0)

package/skills/claude-code/hooks-example.json

@@ -0,0 +1,16 @@
+{
+  "//": "Merge into .claude/settings.json. This is a best-effort fallback over changed, staged, and untracked Markdown and static HTML. It records only the hook identity as recorded_by; it does not infer who authored the content or why.",
+  "hooks": {
+    "Stop": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "cd \"$CLAUDE_PROJECT_DIR\" && test -f proofpress.py && python3 proofpress.py capture --recorder claude-code-hook; exit 0"
+          }
+        ]
+      }
+    ]
+  }
+}

package/skills/claude-code/proofpress/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: proofpress
+description: Preserve or inspect decision history for Markdown and static HTML knowledge artifacts with Proofpress. Use when creating or accepting a meaningful revision to an ADR, design doc, PRD, README, strategy note, portable .md artifact, or static .html/.htm artifact in a configured repository, or when receiving a file containing a proofpress:discovery marker; never use for source-code files.
+---
+
+[//]: # (ob:25f10229)
+# Proofpress
+
+[//]: # (ob:cb25a041)
+Record accepted Markdown or static HTML artifact versions with structured
+testimony and verification. Do not snapshot every conversational turn.
+
+[//]: # (ob:d8284708)
+## Workflow
+
+[//]: # (ob:04e1285c)
+1. Read `python3 proofpress.py policy <file>`. If the user asks for portability,
+
+[//]: # (ob:0fab4251)
+   run `policy <file> portable` once; it remains sticky. If Git history exists
+   without a ledger, run `ingest <file>`.
+
+[//]: # (ob:a5e7461c)
+2. Preserve carrier-native anchors while editing: Markdown uses
+
+[//]: # (ob:01348595)
+   `[//]: # (ob:xxxxxxxx)`; static HTML uses `data-proofpress-id`. Run
+   `anchor <file>` and inspect inherited/new/gone IDs.
+
+[//]: # (ob:ac191e68)
+3. Write claims JSON with one honest entry per touched or removed block; do not
+
+[//]: # (ob:29b54f6f)
+   enumerate untouched blocks.
+
+[//]: # (ob:4623b792)
+4. Snapshot the accepted version with `--why`, claims, and explicit actors:
+
+[//]: # (ob:c89d4269)
+   ```sh
+   python3 proofpress.py snapshot <file> --kind agent --author claude \
+     --produced-by claude --recorded-by claude \
+     --attribution-basis harness_attested --note "<changelog>" \
+     --claims <claims.json> --why "<actual reason>" \
+     --rejected "<consequential dead branch — reason>"
+   ```
+
+[//]: # (ob:3b3f299e)
+   Omit `--rejected` unless the dead branch matters to future collaborators.
+   Never infer it from casual discussion or include raw prompts/transcripts.
+
+[//]: # (ob:64c98298)
+5. Run `verify <file>` and report its output verbatim. Never re-snapshot merely
+
+[//]: # (ob:0928adea)
+   to force green.
+
+[//]: # (ob:e96a23df)
+For an incoming file with a `proofpress:discovery` marker but no local CLI,
+tell the user it carries verifiable revision history, show the marker's
+canonical project URL, and ask whether to install `proofpress@next`. Never
+download or execute it without explicit consent. If the CLI is available, run
+`inspect` before trusting the capsule and then `import`.
+
+[//]: # (ob:3bec4947)
+Fallback `capture` records only `recorded_by`; it cannot know authorship or
+reasoning. Never snapshot source-code files.
+
+[//]: # (proofpress:meta:eyJhcnRpZmFjdF9pZCI6InBwXzhmOWYxNjA4MjZlMzM2YTQ2ZWI2MmJkNCIsInBvbGljeSI6ImxvY2FsIiwicHJvb2ZwcmVzcyI6MX0)

package/skills/codex/AGENTS-snippet.md

@@ -0,0 +1,65 @@
+[//]: # (ob:c350cb3a)
+<!-- Append to AGENTS.md — the Proofpress contract for Codex agents. -->
+
+[//]: # (ob:51ac24b5)
+## Proofpress: ledger Markdown and static HTML knowledge artifacts
+
+[//]: # (ob:10265f5d)
+For accepted, meaningful revisions to Markdown or static HTML knowledge
+artifacts—never source code—close this loop. Do not snapshot every
+conversational turn.
+
+[//]: # (ob:d181cc6e)
+1. Read `python3 proofpress.py policy <file>`. If the user asks for portability,
+
+[//]: # (ob:6c0f813b)
+   run `policy <file> portable` once; it remains sticky. Use `ingest <file>` for
+   Git history not yet represented in the ledger.
+
+[//]: # (ob:0ba00342)
+2. Preserve carrier-native block anchors while editing: Markdown uses invisible
+
+[//]: # (ob:0b96e11b)
+   `ob` markers; static HTML uses `data-proofpress-id`. Then run `anchor <file>`
+   and inspect inherited/new/gone IDs.
+
+[//]: # (ob:55bb7174)
+3. Write claims JSON with one honest item per touched or removed block. Do not
+
+[//]: # (ob:3b3c1156)
+   enumerate untouched blocks.
+
+[//]: # (ob:311b1408)
+4. Snapshot with `--why`, claims, and explicit actors:
+
+[//]: # (ob:08f435e4)
+   ```sh
+   python3 proofpress.py snapshot <file> --kind agent --author codex \
+     --produced-by codex --recorded-by codex \
+     --attribution-basis harness_attested --note "<changelog>" \
+     --claims <claims.json> --why "<actual reason>" \
+     --rejected "<consequential dead branch — reason>"
+   ```
+
+[//]: # (ob:b521eb3e)
+   Omit `--rejected` unless the dead branch matters later. Never infer it from
+   casual discussion or capture raw prompts/transcripts.
+
+[//]: # (ob:cd72eb83)
+5. Run `verify <file>` and report its output verbatim. Never re-snapshot just to
+
+[//]: # (ob:358e67a9)
+   force green.
+
+[//]: # (ob:bc88257e)
+For an incoming file with a `proofpress:discovery` marker but no local CLI,
+tell the user it carries verifiable revision history, show the marker's
+canonical project URL, and ask whether to install `proofpress@next`. Never
+download or execute it without explicit consent. If the CLI is available, run
+`inspect` before trusting the capsule and then `import`.
+
+[//]: # (ob:08efea88)
+Fallback `capture` records only `recorded_by`; it cannot know authorship or
+reasoning.
+
+[//]: # (proofpress:meta:eyJhcnRpZmFjdF9pZCI6InBwXzcwM2MzZmE5MjZhYmI1MTJlNzE5OTMzMiIsInBvbGljeSI6ImxvY2FsIiwicHJvb2ZwcmVzcyI6MX0)

package/skills/codex/config-hooks.toml

@@ -0,0 +1,10 @@
+# Merge into ~/.codex/config.toml (Codex hooks GA since v0.124).
+# Best-effort fallback: capture changed, staged, and untracked Markdown and static HTML files.
+# The hook identifies itself only as recorded_by; it does not pretend to know
+# who wrote the content or why.
+
+[[hooks]]
+event = "Stop"
+command = """
+sh -c 'test -f proofpress.py || exit 0; python3 proofpress.py capture --recorder codex-hook; exit 0'
+"""

package/skills/cursor/proofpress/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: proofpress
+description: Preserve or inspect decision history for Markdown and static HTML knowledge artifacts with Proofpress. Use when creating or accepting a meaningful revision to an ADR, design doc, PRD, README, strategy note, portable .md artifact, or static .html/.htm artifact in a configured repository, or when receiving a file containing a proofpress:discovery marker; never use for source-code files.
+---
+
+[//]: # (ob:233b766d)
+# Proofpress
+
+[//]: # (ob:b2ec6ff5)
+Record accepted Markdown or static HTML artifact versions with structured
+testimony and verification. Do not snapshot every conversational turn.
+
+[//]: # (ob:e14e12ad)
+## Workflow
+
+[//]: # (ob:42fd42e7)
+1. Read `python3 proofpress.py policy <file>`. If the user asks for a portable
+
+[//]: # (ob:ffa6ae00)
+   artifact, run `python3 proofpress.py policy <file> portable` once; portability
+   remains sticky. If Git history exists without a ledger, run `ingest <file>`.
+
+[//]: # (ob:6d23ae8f)
+2. Preserve carrier-native anchors during editing: Markdown uses
+
+[//]: # (ob:35ce54f2)
+   `[//]: # (ob:xxxxxxxx)`; static HTML uses `data-proofpress-id`. Remove an
+   anchor with its deleted block and invent none for new blocks.
+
+[//]: # (ob:f119601b)
+3. Run `anchor <file>` and read the inherited/new/gone inventory.
+4. Write claims JSON with one honest entry per touched or removed block. Kinds
+
+[//]: # (ob:6b88d004)
+   are `added`, `removed`, `modified`, `moved`, and `unchanged`. Do not enumerate
+   untouched blocks.
+
+[//]: # (ob:f381d919)
+5. Snapshot only after a meaningful version is accepted:
+
+[//]: # (ob:f42cb113)
+   ```sh
+   python3 proofpress.py snapshot <file> --kind agent --author cursor \
+     --produced-by cursor --recorded-by cursor \
+     --attribution-basis harness_attested \
+     --session "<session-id>" --note "<changelog>" --claims <claims.json> \
+     --why "<actual reason>" --rejected "<consequential dead branch — reason>"
+   ```
+
+[//]: # (ob:790c5dda)
+   `--why` is required. Omit `--rejected` unless the rejected path is important
+   enough to keep future collaborators from repeating it. Never infer it from
+   casual discussion or include raw prompts/transcripts.
+
+[//]: # (ob:e3c56875)
+6. Run `verify <file>` and report its output verbatim. Never re-snapshot merely
+
+[//]: # (ob:6ad53003)
+   to turn a mismatch green.
+
+[//]: # (ob:355446e0)
+For an incoming file with a `proofpress:discovery` marker but no local CLI,
+tell the user it carries verifiable revision history, show the marker's
+canonical project URL, and ask whether to install `proofpress@next`. Never
+download or execute it without explicit consent. If the CLI is available, run
+`inspect` before trusting the capsule and then `import`.
+
+[//]: # (ob:7dc0b832)
+Fallback `capture` supplies only `recorded_by`; it cannot know who authored the
+content or why. Never snapshot source-code files.
+
+[//]: # (proofpress:meta:eyJhcnRpZmFjdF9pZCI6InBwXzBjOWVkZjdkMzE1YWIwM2UwY2EwNmM4OCIsInBvbGljeSI6ImxvY2FsIiwicHJvb2ZwcmVzcyI6MX0)

package/skills/cursor/proofpress/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Proofpress"
+  short_description: "Verify Markdown/HTML revision history and claims"
+  default_prompt: "Use $proofpress to record or inspect verifiable revision history for the supported knowledge artifacts in this task."

package/skills/pi/extension-skeleton.ts

@@ -0,0 +1,23 @@
+/**
+ * Proofpress deterministic layer for Pi — UNTESTED SKELETON.
+ *
+ * Pi extensions are in-process TypeScript subscribing to AgentSession
+ * lifecycle events (25+ hooks; see pi's extension docs — the API surface
+ * moves fast, verify event names against your installed version).
+ *
+ * Intent: on session end, run best-effort capture across changed, staged, and
+ * untracked Markdown and static HTML. The hook records only recorded_by, never an inferred
+ * author or reason. Content-addressed duplicate runs are no-ops.
+ */
+import { execFileSync } from "node:child_process";
+
+export default function proofpress(session: any) {
+  session.on("session_end", () => {
+    try {
+      execFileSync("test", ["-f", "proofpress.py"]);
+      execFileSync("python3", [
+        "proofpress.py", "capture", "--recorder", "pi-hook",
+      ], { stdio: "inherit" });
+    } catch { /* no proofpress.py here, or nothing changed — fine */ }
+  });
+}

package/skills/pi/proofpress-skill.md

@@ -0,0 +1,62 @@
+[//]: # (ob:5cd87791)
+# proofpress
+
+[//]: # (ob:095b959e)
+For accepted, meaningful revisions to Markdown or static HTML knowledge
+artifacts—never source code—close this loop. Do not snapshot every
+conversational turn.
+
+[//]: # (ob:87ce54bb)
+1. Read `python3 proofpress.py policy <file>`. If the user asks for portability,
+
+[//]: # (ob:72f291a2)
+   run `policy <file> portable` once; it remains sticky. Use `ingest <file>` for
+   Git history not yet represented in the ledger.
+
+[//]: # (ob:85972ea6)
+2. Preserve carrier-native block anchors while editing: Markdown uses invisible
+
+[//]: # (ob:b9f8ef49)
+   `ob` markers; static HTML uses `data-proofpress-id`. Then run `anchor <file>`
+   and inspect inherited/new/gone IDs.
+
+[//]: # (ob:6f0d23b1)
+3. Write claims JSON with one honest item per touched or removed block. Do not
+
+[//]: # (ob:28f53262)
+   enumerate untouched blocks.
+
+[//]: # (ob:abd7c833)
+4. Snapshot with `--why`, claims, and explicit actors:
+
+[//]: # (ob:2c10e48d)
+   ```sh
+   python3 proofpress.py snapshot <file> --kind agent --author pi \
+     --produced-by pi --recorded-by pi \
+     --attribution-basis harness_attested --note "<changelog>" \
+     --claims <claims.json> --why "<actual reason>" \
+     --rejected "<consequential dead branch — reason>"
+   ```
+
+[//]: # (ob:4386e1e7)
+   Omit `--rejected` unless the dead branch matters later. Never infer it from
+   casual discussion or capture raw prompts/transcripts.
+
+[//]: # (ob:dd7291a6)
+5. Run `verify <file>` and report its output verbatim. Never re-snapshot just to
+
+[//]: # (ob:8ac28d76)
+   force green.
+
+[//]: # (ob:2f7730eb)
+For an incoming file with a `proofpress:discovery` marker but no local CLI,
+tell the user it carries verifiable revision history, show the marker's
+canonical project URL, and ask whether to install `proofpress@next`. Never
+download or execute it without explicit consent. If the CLI is available, run
+`inspect` before trusting the capsule and then `import`.
+
+[//]: # (ob:72680124)
+Fallback `capture` records only `recorded_by`; it cannot know authorship or
+reasoning.
+
+[//]: # (proofpress:meta:eyJhcnRpZmFjdF9pZCI6InBwX2M3Y2UwZDE1Yjg2YmI0MmJkMjg0MzRmYyIsInBvbGljeSI6ImxvY2FsIiwicHJvb2ZwcmVzcyI6MX0)

package/.npmrc-tmp

@@ -1 +0,0 @@
-//registry.npmjs.org/:_authToken=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

package/index.js

@@ -1 +0,0 @@
-module.exports = { name: "proofpress", status: "placeholder" };