proofpress 0.1.0-alpha.1 → 0.1.0

package/README.md

@@ -7,16 +7,24 @@
 # Proofpress
 
 [//]: # (ob:e667d986)
-Proofpress is a verifiable `log.md` for knowledge work: a shared history of who
-changed what, when, and why, checked against the artifact itself.
+Proofpress is the trust layer for multiplayer AI: an open, agent-native ledger
+that travels with the artifact.
 
 [//]: # (ob:0e0e9d9a)
-Agents can produce a document quickly, but the reasoning that shaped its final
-form is usually scattered across chat sessions, Slack, meetings, and somebody's
-memory. Git is excellent when the work already lives in Git; most knowledge
-artifacts do not. Proofpress keeps the accepted version history and consequential
-decisions attached to a Markdown or static HTML artifact so that history can
-travel with it.
+Humans and agents can produce a document quickly, but the decisions that shaped
+its final form are usually scattered across chat sessions, Slack, meetings, and
+somebody's memory. Git is excellent when the work already lives in Git; most
+knowledge artifacts do not. Proofpress keeps a shared, checkable record of
+accepted changes, stated reasons, consequential rejections, and their relation
+to the artifact itself—so that history can travel with the work.
+
+[//]: # (ob:cc376e2b)
+Think C2PA, but for knowledge work: a portable, inspectable record of the
+history admitted into an artifact. This is an analogy, not a claim of C2PA
+compatibility, signed authorship, or complete capture.
+
+[//]: # (ob:6ef36a68)
+> Git made code collaborative. Proofpress makes intelligence cumulative.
 
 [//]: # (ob:169d8523)
 ## Status
@@ -36,7 +44,7 @@ plus repository setup command. Python 3 and Git are required:
 
 [//]: # (ob:7b197ac1)
 ```sh
-npm install --save-dev proofpress@next
+npm install --save-dev proofpress
 npx --no-install proofpress --version
 npx --no-install proofpress setup --agent codex
 ```
@@ -46,6 +54,20 @@ npx --no-install proofpress setup --agent codex
 `.proofpress/manifest.json`. It is idempotent and supports `codex`, `claude`,
 `cursor`, or `all`. Portable history remains opt-in per artifact.
 
+[//]: # (ob:da019dfc)
+`proofpress@0.1.0` is the current stable release channel. The deprecated
+`0.0.1` placeholder is no longer the default install.
+
+[//]: # (ob:4273537d)
+## Verify a portable handoff in five minutes
+
+[//]: # (ob:1160e434)
+The [portable handoff demo](examples/portable-handoff/) contains one neutral
+community-planning document with a real, embedded v1 → v2 ledger. In a clean
+Git repository, install `proofpress`, copy only `strategy.md`, then run
+`inspect`, `import`, and `verify`. The recipient needs neither the source
+repository nor the original session.
+
 [//]: # (ob:2b655d31)
 To add a visible, transparent distribution mark to a repository README:
 
@@ -109,7 +131,7 @@ authorship or protection from wholesale malicious replacement.
 [//]: # (ob:839fc8a1)
 Portable carriers include a non-rendering discovery marker with
 `Verifiable revision history by Proofpress` and the project URL. The capsule's
-canonical discovery object also names `proofpress@next`. An agent may explain
+canonical discovery object names `proofpress@latest`. An agent may explain
 this provenance and offer installation, but must obtain user consent before
 downloading or executing anything.
 
@@ -136,7 +158,8 @@ python3 proofpress.py verify launch-plan.html
 This is a static-HTML carrier MVP, not a framework or CMS integration. Proofpress
 does not yet promise round-trip preservation through React/Vue builds, HTML
 sanitizers, editors, or CMS pipelines; if they strip transport data, the file
-degrades to an ordinary HTML artifact.
+degrades to an ordinary HTML artifact — `identify` can still recognize it
+locally, but its provenance does not come back.
 
 [//]: # (ob:226a29fd)
 ## What gets recorded
@@ -149,9 +172,12 @@ against the actual artifact diff.
 
 [//]: # (ob:5e0b34ed)
 It does not automatically store raw prompts, transcripts, tool traces, casual
-brainstorming, or every save. A fallback hook can preserve an otherwise missed
-version, but identifies itself only as `recorded_by`; it does not guess who
-wrote the content or why.
+brainstorming, or every save. A fallback hook checks Git candidates and current
+paths already admitted to the ledger, including Git-ignored artifacts. It can
+preserve an otherwise missed version, but identifies itself only as
+`recorded_by`; it does not guess who wrote the content or why. Harness skills
+can also capture a specific existing file before an agent edits it, keeping
+unattributed human drift separate from the agent's revision.
 
 [//]: # (ob:d8387b0b)
 ## Privacy modes
@@ -201,6 +227,35 @@ Use `--rejected` only for consequential dead branches that future collaborators
 should not repeat. Source code stays in Git; Proofpress is for Markdown and
 static HTML knowledge artifacts.
 
+[//]: # (ob:59769c11)
+## Merged lineage and stripped copies
+
+[//]: # (ob:91a8deb1)
+When one document merges several Proofpress-managed sources, record the
+upstream references — identity, head version, and digest, never copied
+history:
+
+[//]: # (ob:100c5aa7)
+```sh
+python3 proofpress.py merge-lineage proposal.md \
+  --from research-a.md --from research-b.md
+```
+
+[//]: # (ob:144c3d60)
+When a copy lost its metadata and capsule (pasted as plain text, reformatted,
+sanitized), the ledger can still recognize it by a deterministic content
+fingerprint:
+
+[//]: # (ob:28dec45f)
+```sh
+python3 proofpress.py identify pasted-copy.md
+```
+
+[//]: # (ob:b705ac38)
+`identify` answers identity — "this is that artifact" — on a machine holding
+the ledger. It does not restore history or prove the copy was never altered,
+and a copy with wording changes intentionally does not match.
+
 [//]: # (ob:2a955c60)
 ## Surfaces
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "proofpress",
-  "version": "0.1.0-alpha.1",
-  "description": "Verifiable revision provenance for Markdown and static HTML knowledge artifacts",
+  "version": "0.1.0",
+  "description": "The trust layer for multiplayer AI: an open, agent-native ledger for knowledge artifacts",
   "license": "Apache-2.0",
   "bin": {
     "proofpress": "bin/proofpress.js"

package/proofpress.py

@@ -13,14 +13,16 @@ Commands:
   show <file-or-version> [--json]
   verify <file> [<version>] [--json]     claim 校验:exit 0 ✓ / 1 ⚠ / 2 无 claims
   ingest <file>                          从 git commit 历史回填账本版本
+  merge-lineage <file> --from a.md --from b.md   多父溯源:记录 ingredient 引用
+  identify <file>                        软绑定反查:capsule 被剥离后认回身份
   policy / inspect / import / clean / capture
   anchor / blocks / init / sync
 """
 
-import argparse, base64, difflib, hashlib, json, os, re, secrets, subprocess, sys, tempfile, zlib
+import argparse, base64, difflib, hashlib, html, json, os, re, secrets, subprocess, sys, tempfile, zlib
 from datetime import datetime, timezone
 
-__version__ = "0.1.0-alpha.1"
+__version__ = "0.1.0"
 LEDGER_REF = "refs/proofpress/ledger"
 
 # ---------- terminal rendering ----------
@@ -139,9 +141,22 @@ CAPSULE_DISCOVERY = {
     "label": DISCOVERY_LABEL,
     "project_url": DISCOVERY_URL,
     "package": "proofpress",
-    "dist_tag": "next",
+    "dist_tag": "latest",
     "requires_user_consent": True,
 }
+LEGACY_CAPSULE_DISCOVERIES = (
+    {
+        "label": DISCOVERY_LABEL,
+        "project_url": DISCOVERY_URL,
+        "package": "proofpress",
+        "dist_tag": "next",
+        "requires_user_consent": True,
+    },
+)
+
+
+def known_capsule_discovery(value):
+    return value == CAPSULE_DISCOVERY or value in LEGACY_CAPSULE_DISCOVERIES
 
 
 def _b64e(data):
@@ -499,6 +514,30 @@ def version_id(version):
                                    ensure_ascii=False).encode()).hexdigest()[:8]
 
 
+# ---------- soft binding(剥离元数据后仍可识别的确定性指纹) ----------
+
+_FP_RAWTEXT = re.compile(r"(?is)<(script|style)\b[^>]*>.*?</\1>")
+_FP_TAG = re.compile(r"<[^>]+>")
+_FP_MD_LINK = re.compile(r"!?\[([^\]]*)\]\([^)]*\)")
+
+
+def soft_fingerprint(blocks):
+    """Tier-1 exact soft binding: hash of the visible text skeleton.
+
+    Deterministic, model-free. Normalization is deliberately harsh — strip
+    HTML tags, markdown link targets and all syntax/punctuation, collapse
+    whitespace — so the fingerprint survives formatting drift (plain-text
+    copy, re-rendering, whitespace mangling) but flips on any wording
+    change. It proves identity ("this is pp_xxx"), never tamper-freedom."""
+    text = "\n".join(b["text"] for b in blocks)
+    text = _FP_RAWTEXT.sub(" ", text)
+    text = _FP_TAG.sub(" ", text)
+    text = _FP_MD_LINK.sub(r"\1", text)
+    text = html.unescape(text)
+    skeleton = " ".join(re.findall(r"[^\W_]+", text))
+    return "ppsb1:" + hashlib.sha256(skeleton.encode()).hexdigest()
+
+
 # ---------- 块身份匹配(锚点缺席时的相似度兜底;v0 只有兜底) ----------
 
 def assign_ids(new_blocks, old_version):
@@ -677,6 +716,40 @@ def versions_of(path):
     return out
 
 
+def latest_at_recorded_path(path):
+    """Return the newest event projected at path, even if file metadata is gone.
+
+    Normal edits carry artifact identity in the file.  A whole-file replace can
+    strip that transport, so path continuity is the deterministic local
+    fallback: the replacement is another version of the artifact last recorded
+    at that path.
+    """
+    target = os.path.normcase(os.path.abspath(path))
+    for event in ledger_events():
+        if event.get("event") != "version_created":
+            continue
+        recorded = event.get("artifact")
+        if recorded and os.path.normcase(os.path.abspath(recorded)) == target:
+            return event
+    return None
+
+
+def read_artifact_for_update(path):
+    """Read a carrier and recover stripped identity from its recorded path."""
+    body, meta, capsule, errors = read_artifact(path)
+    recovered = False
+    if meta is None and "invalid_meta" not in errors:
+        prior = latest_at_recorded_path(path)
+        if prior and prior.get("artifact_id"):
+            policy = prior.get("policy", "local")
+            meta = new_meta(policy if policy in POLICIES else "local")
+            meta["artifact_id"] = prior["artifact_id"]
+            recovered = True
+        else:
+            meta = new_meta()
+    return body, meta, capsule, errors, recovered
+
+
 def latest_for(path):
     vs = versions_of(path)
     return vs[0] if vs else None
@@ -703,9 +776,19 @@ def write_event(event, version=None):
 
 # ---------- commands ----------
 
+def check_attribution_basis(basis):
+    # `signed` is the reserved top rung of the attribution ladder. Until
+    # cryptographic signing lands, accepting it would grade attribution
+    # above what is actually attested — a false claim by construction.
+    if basis == "signed":
+        raise SystemExit("attribution_basis 'signed' is reserved until "
+                         "signing is implemented; use harness_attested or below")
+
+
 def do_snapshot(path, author, kind, session, note, claims=None, context=None,
                 text=None, ts=None, source_commit=None, artifact_id=None,
-                policy="local", actors=None, attribution_basis="unknown"):
+                policy="local", actors=None, attribution_basis="unknown",
+                ingredients=None):
     """Core snapshot: file → block tree → ledger. Returns event or None (no change).
 
     `claims` is the author's structured self-description of the change
@@ -714,7 +797,12 @@ def do_snapshot(path, author, kind, session, note, claims=None, context=None,
     verified, never trusted.
 
     `text`/`ts`/`source_commit` let `ingest` replay historical git commits
-    into the ledger with their original content, author date and commit sha."""
+    into the ledger with their original content, author date and commit sha.
+
+    `ingredients` is a list of upstream-artifact references (id + head +
+    digest, never copied history) recorded when this version merges other
+    Proofpress artifacts; the linear `parent` chain is unaffected."""
+    check_attribution_basis(attribution_basis)
     if text is None:
         text = open(path).read()
     prev_ev = latest_for(path)
@@ -737,7 +825,10 @@ def do_snapshot(path, author, kind, session, note, claims=None, context=None,
         "stats": stats,
         "changes": changes,
         "policy": policy,
+        "soft_fingerprint": soft_fingerprint(blocks),
     }
+    if ingredients:
+        event["ingredients"] = ingredients
     if actors:
         event["actors"] = actors
     event["attribution_basis"] = attribution_basis
@@ -772,6 +863,7 @@ def _actors_from_args(a):
 
 def make_checkpoint_capsule(path, body, meta, recorded_by=None,
                             attribution_basis="self_asserted"):
+    check_attribution_basis(attribution_basis)
     prev_ev = latest_for(path)
     prev_v = read_version(prev_ev["_commit"]) if prev_ev else None
     blocks = assign_ids(parse_blocks(body, carrier_for_path(path)), prev_v)
@@ -791,6 +883,7 @@ def make_checkpoint_capsule(path, body, meta, recorded_by=None,
         "note": "portable lineage checkpoint", "policy": "portable",
         "ts": datetime.now(timezone.utc).isoformat(timespec="seconds"),
         "stats": stats, "changes": changes,
+        "soft_fingerprint": soft_fingerprint(blocks),
         "portable_checkpoint": True,
         "portable_lineage_id": lineage,
     }
@@ -814,7 +907,7 @@ def validate_capsule(body, meta, capsule, carrier="markdown"):
     if capsule.get("proofpress_capsule") != 1:
         errors.append("unsupported_capsule")
     if ("discovery" in capsule and
-            capsule.get("discovery") != CAPSULE_DISCOVERY):
+            not known_capsule_discovery(capsule.get("discovery"))):
         errors.append("invalid_capsule_discovery")
     if capsule.get("artifact_id") != meta.get("artifact_id"):
         errors.append("artifact_id_mismatch")
@@ -882,12 +975,15 @@ def append_capsule(path, body, meta, capsule, event, version):
 
 
 def cmd_snapshot(a):
-    body, meta, capsule, errors = read_artifact(a.file, create_meta=True)
+    body, meta, capsule, errors, recovered = read_artifact_for_update(a.file)
     if errors:
         raise SystemExit("invalid Proofpress metadata: " + ", ".join(errors))
     if meta["policy"] == "ignored":
         print(f"skipped: {a.file} policy is ignored")
         return
+    if recovered:
+        print(f"recovered identity: {a.file} -> {meta['artifact_id']} "
+              "(matched previous ledger path)")
     if getattr(a, "base_version", None):
         current = (capsule or {}).get("head")
         if current is None:
@@ -917,8 +1013,18 @@ def cmd_snapshot(a):
     ev = do_snapshot(a.file, a.author, a.kind, a.session, a.note,
                      claims=claims, context=context, text=body,
                      artifact_id=meta["artifact_id"], policy=meta["policy"],
-                     actors=actors, attribution_basis=a.attribution_basis)
+                     actors=actors, attribution_basis=a.attribution_basis,
+                     ingredients=getattr(a, "ingredients", None))
     if not ev:
+        if meta["policy"] == "portable" and capsule is None and recovered:
+            capsule = make_checkpoint_capsule(
+                a.file, body, meta,
+                recorded_by=(actors.get("recorded_by") or [a.author])[0],
+                attribution_basis=a.attribution_basis)
+            meta["portable_head"] = capsule["head"]
+            write_artifact(a.file, body, meta, capsule)
+            print(f"repaired capsule: {a.file} -> {capsule['head']}")
+            return
         if meta["policy"] == "portable" and capsule is not None:
             latest = latest_for(a.file)
             if latest and capsule.get("head") != latest.get("version"):
@@ -996,6 +1102,23 @@ def change_label(c):
     return (ctx or c.get("preview", "")[:48]), ""
 
 
+def verify_label(change, fallback):
+    """Make a claim target distinguishable from its heading context.
+
+    A Markdown heading and every block beneath it share ``context``.  Verify
+    output therefore needs the block type and, for non-headings, a short
+    preview so adjacent rows are not mistaken for duplicate blocks.
+    """
+    if not change:
+        return fallback
+    ctx = change.get("context", "")
+    block_type = change.get("type", "block")
+    preview = (change.get("preview") or "").strip().replace("\n", " ")[:56]
+    if block_type == "heading" or not preview:
+        return f"{ctx or fallback} / {block_type}"
+    return f"{ctx + ' / ' if ctx else ''}{block_type}: {preview}"
+
+
 def cmd_diff(a):
     evs = versions_of(a.file)
     if len(evs) < 2 and not (a.va and a.vb):
@@ -1143,6 +1266,98 @@ def cmd_ingest(a):
     print(f"ingested {made}, skipped {skipped} (already known / older than ledger / no content change)")
 
 
+def _ingredient_ref(path):
+    """Reference + digest for an upstream artifact — never its history."""
+    if not os.path.isfile(path):
+        raise SystemExit(f"ingredient not found: {path}")
+    _, meta, capsule, errors = read_artifact(path)
+    if errors:
+        raise SystemExit(f"ingredient {path}: invalid metadata: " + ", ".join(errors))
+    if not meta:
+        raise SystemExit(f"ingredient {path} is not proofpress-managed "
+                         "(snapshot or import it first)")
+    ref = {"artifact": path, "artifact_id": meta["artifact_id"]}
+    latest = latest_for(path)
+    if latest:
+        ref["version"] = latest["version"]
+        ref["body_digest"] = body_digest(read_version(latest["_commit"]))
+    elif capsule:
+        ref["version"] = capsule.get("head")
+        ref["body_digest"] = capsule.get("body_digest")
+    else:
+        raise SystemExit(f"ingredient {path} has no ledger history or capsule "
+                         "to reference")
+    if meta.get("portable_lineage_id"):
+        ref["portable_lineage_id"] = meta["portable_lineage_id"]
+    return ref
+
+
+def cmd_merge_lineage(a):
+    """Record that this version merges multiple upstream Proofpress artifacts.
+
+    C2PA-ingredient style: each --from source is stored as a reference
+    (artifact_id + head version + body digest) on the merge event only.
+    Upstream history is never copied, and the linear parent chain of the
+    target artifact is untouched — ingredients are additive provenance."""
+    a.ingredients = [_ingredient_ref(p) for p in a.source]
+    if a.note is None:
+        a.note = "merged lineage from " + ", ".join(
+            r["artifact_id"] for r in a.ingredients)
+    cmd_snapshot(a)
+    latest = latest_for(a.file)
+    if not latest or latest.get("ingredients") != a.ingredients:
+        raise SystemExit(
+            "merge-lineage records ingredients on a new version, but the file "
+            "content is unchanged from the ledger tip — write the merged "
+            "content into the file first, then re-run")
+    for r in a.ingredients:
+        print(f"  ingredient: {r['artifact_id']} @ {r.get('version', '?')}"
+              f"  ({r['artifact']})")
+
+
+def cmd_identify(a):
+    """Soft-binding lookup: recognize a file whose Proofpress metadata and
+    capsule were stripped, using the local ledger as the fingerprint index.
+
+    Answers identity ("this is pp_xxx"), not integrity — a match does not
+    prove the content was never altered, only that this exact visible text
+    skeleton was admitted before. Exit 0 found, 1 not found."""
+    carrier = carrier_for_path(a.file)
+    body, meta, _, _ = split_transport(open(a.file).read(), carrier)
+    fp = soft_fingerprint(parse_blocks(body, carrier))
+    matches = {}
+    for ev in ledger_events():  # newest first — keep first hit per artifact
+        if ev.get("event") != "version_created":
+            continue
+        evfp = ev.get("soft_fingerprint") or soft_fingerprint(
+            read_version(ev["_commit"])["blocks"])  # pre-fingerprint events
+        if evfp == fp:
+            matches.setdefault(ev.get("artifact_id") or ev.get("artifact"), ev)
+    found = list(matches.values())
+    if a.json:
+        print(json.dumps({
+            "file": a.file, "soft_fingerprint": fp,
+            "status": "identified" if found else "not_found",
+            "matches": [{"artifact_id": e.get("artifact_id"),
+                         "artifact": e.get("artifact"),
+                         "version": e["version"], "ts": e["ts"]}
+                        for e in found]}, ensure_ascii=False, indent=2))
+        sys.exit(0 if found else 1)
+    if not found:
+        print(f"identify {a.file}: no ledger version matches this content "
+              "(rewritten, or never admitted here)")
+        sys.exit(1)
+    print(f"identify {B(a.file)} " + C("dim", f"({fp[:22]}…)"))
+    for e in found:
+        marker = ""
+        if meta and meta.get("artifact_id") == e.get("artifact_id"):
+            marker = C("dim", "  (identity intact in file)")
+        print(f'  {C("add", "✓")} {e.get("artifact_id") or "?"} @ {e["version"]}'
+              f'  {C("dim", e["ts"][:16].replace("T", " "))}'
+              f'  {e.get("artifact", "")}{marker}')
+    sys.exit(0)
+
+
 def cmd_export(a):
     """Write an artifact's ledger chain as one self-contained JSON bundle.
 
@@ -1233,7 +1448,7 @@ def cmd_anchor(a):
 
 
 def cmd_policy(a):
-    body, meta, capsule, errors = read_artifact(a.file, create_meta=True)
+    body, meta, capsule, errors, _ = read_artifact_for_update(a.file)
     if errors:
         raise SystemExit("invalid Proofpress metadata: " + ", ".join(errors))
     if a.policy is None:
@@ -1263,6 +1478,58 @@ def cmd_policy(a):
     print(f"{a.policy}: {a.file} (capsule removed from this copy; old copies unchanged)")
 
 
+def _matching_ledger_version(events, digest):
+    """Return the newest recorded version with this visible-body digest."""
+    for event in events:
+        if body_digest(read_version(event["_commit"])) == digest:
+            return event
+    return None
+
+
+def _worktree_ledger_state(path, body, meta):
+    """Compare a local carrier with the ledger head, even without transport.
+
+    Portable artifacts already have a capsule body digest. Local artifacts do
+    not, which used to let ``verify`` validate an old event while silently
+    ignoring an overwritten worktree. A stripped carrier falls back to the
+    last recorded path so the warning remains useful after whole-file replace.
+    """
+    latest = latest_for(path) if meta else latest_at_recorded_path(path)
+    if not latest:
+        return None
+    expected = read_version(latest["_commit"])
+    current_blocks = parse_blocks(body, carrier_for_path(path))
+    actual_digest = body_digest({"blocks": current_blocks})
+    expected_digest = body_digest(expected)
+    expected_fp = latest.get("soft_fingerprint") or soft_fingerprint(expected["blocks"])
+    actual_fp = soft_fingerprint(current_blocks)
+    events = (versions_of(path) if meta else
+              [e for e in ledger_events()
+               if e.get("event") == "version_created" and
+               e.get("artifact_id") == latest.get("artifact_id")])
+    matched = _matching_ledger_version(events, actual_digest)
+    errors = []
+    if meta is None:
+        errors.append("unmanaged_worktree")
+    elif meta.get("artifact_id") != latest.get("artifact_id"):
+        errors.append("ledger_identity_mismatch")
+    # Exact digest intentionally sees carrier formatting. The soft fingerprint
+    # is the documented formatting-tolerant boundary: different Markdown table
+    # spacing or emphasis placement is not a content drift.
+    formatting_drift = actual_digest != expected_digest and actual_fp == expected_fp
+    if actual_digest != expected_digest and not formatting_drift:
+        errors.append("worktree_not_at_ledger_head")
+    if not errors and not formatting_drift:
+        return None
+    return {
+        "ledger_head": latest["version"],
+        "observed_version": (matched.get("version") if matched else
+                             (latest["version"] if formatting_drift else None)),
+        "errors": errors,
+        "formatting_drift": formatting_drift,
+    }
+
+
 def inspect_result(path):
     body, meta, capsule, errors = read_artifact(path)
     result = {"artifact": path, "managed": meta is not None,
@@ -1274,10 +1541,19 @@ def inspect_result(path):
         if capsule:
             result["head"] = capsule.get("head")
             result["versions"] = len(capsule.get("records", []))
-            if capsule.get("discovery") == CAPSULE_DISCOVERY:
+            if known_capsule_discovery(capsule.get("discovery")):
                 result["discovery"] = capsule["discovery"]
     elif capsule is not None:
         result["errors"].append("capsule_on_nonportable_artifact")
+    # A portable mismatch is already reported by capsule validation. For local
+    # and stripped carriers, compare the visible worktree to the ledger head.
+    if not (meta and meta.get("policy") == "portable"):
+        worktree = _worktree_ledger_state(path, body, meta)
+        if worktree:
+            result["ledger_head"] = worktree["ledger_head"]
+            result["observed_version"] = worktree["observed_version"]
+            result["formatting_drift"] = worktree["formatting_drift"]
+            result["errors"].extend(worktree["errors"])
     if result["errors"]:
         result["status"] = "mismatch"
     return result
@@ -1294,6 +1570,11 @@ def cmd_inspect(a):
             print(f"  artifact: {result['artifact_id']}")
         if result.get("head"):
             print(f"  capsule: {result['versions']} version(s), head {result['head']}")
+        if result.get("ledger_head"):
+            observed = result.get("observed_version") or "unrecorded/unknown"
+            print(f"  ledger head: {result['ledger_head']} (worktree: {observed})")
+        if result.get("formatting_drift"):
+            print("  note: formatting differs from the ledger head; visible content matches")
         if result.get("discovery"):
             print(f"  provenance: {result['discovery']['label']}")
             print(f"  learn more: {result['discovery']['project_url']}")
@@ -1301,6 +1582,10 @@ def cmd_inspect(a):
                   f"{result['discovery']['dist_tag']} (user consent required)")
         for error in result["errors"]:
             print(f"  error: {error}")
+        if "unmanaged_worktree" in result["errors"]:
+            print(f"  action: run `proofpress identify {a.file}`; reconcile the file before snapshotting")
+        elif "worktree_not_at_ledger_head" in result["errors"]:
+            print("  action: restore or reconcile the ledger head; snapshot only if this edit is intentional")
     if result["status"] != "ok":
         sys.exit(1)
 
@@ -1336,7 +1621,12 @@ def cmd_clean(a):
 
 
 def changed_artifact_files():
-    """Find changed carriers that the fallback hook can safely snapshot."""
+    """Find carriers that the fallback hook can safely reconcile.
+
+    Git remains useful for discovering never-admitted files.  Already-admitted
+    artifacts also come from the ledger, so ignored files and manual edits are
+    still checked when a hook runs.
+    """
     paths = set()
     for pattern in ("*.md", "*.html", "*.htm"):
         commands = [
@@ -1349,20 +1639,44 @@ def changed_artifact_files():
                 paths.update(p for p in git(*args).splitlines() if p)
             except RuntimeError:
                 continue
+    seen = set()
+    for event in ledger_events():
+        if event.get("event") != "version_created":
+            continue
+        identity = event.get("artifact_id") or event.get("artifact")
+        if identity in seen:
+            continue
+        seen.add(identity)
+        path = event.get("artifact")
+        if path and os.path.isfile(path):
+            paths.add(path)
     return sorted(p for p in paths if os.path.isfile(p) and carrier_for_path(p) in ("markdown", "html"))
 
 
+def matches_latest(path, body, meta):
+    latest = latest_for(path)
+    if not latest:
+        return False
+    previous = read_version(latest["_commit"])
+    blocks = assign_ids(parse_blocks(body, carrier_for_path(path)), previous)
+    current = {"artifact": path, "artifact_id": meta["artifact_id"],
+               "blocks": blocks}
+    return version_id(current) == latest["version"]
+
+
 def cmd_capture(a):
-    paths = changed_artifact_files()
+    paths = sorted(set(a.files)) if a.files else changed_artifact_files()
     captured = skipped = 0
     for path in paths:
-        body, meta, _, errors = read_artifact(path, create_meta=True)
+        body, meta, _, errors, recovered = read_artifact_for_update(path)
         if errors:
             print(f"capture warning: {path}: " + ", ".join(errors))
             skipped += 1; continue
         if meta["policy"] == "ignored":
             print(f"capture skipped: {path} is ignored")
             skipped += 1; continue
+        if not recovered and matches_latest(path, body, meta):
+            skipped += 1; continue
         anchor_file(path, quiet=True)
         ns = argparse.Namespace(
             file=path, author=a.recorder, kind="system", session=a.session,
@@ -1463,6 +1777,10 @@ def cmd_show(a):
         print(C("dim", "why: ") + md_term(ctx_ev["why"]))
     for r in ctx_ev.get("rejected", []):
         print(C("dim", "rejected: ") + md_term(r))
+    for ing in ev.get("ingredients", []):
+        print(C("dim", "ingredient: ")
+              + f'{ing.get("artifact_id", "?")} @ {ing.get("version", "?")}'
+              + C("dim", f'  ({ing.get("artifact", "")})'))
     print()
     tagcolor = {"added": "add", "modified": "accent", "moved": "move"}
     for b in v["blocks"]:
@@ -1502,6 +1820,30 @@ def cmd_verify(a):
         raise SystemExit("artifact not in ledger")
     ev = _find(evs, a.version) if a.version else evs[0]
     n = len(evs) - next(i for i, e in enumerate(evs) if e["version"] == ev["version"])
+    # ``verify file`` means the current worktree as well as the recorded
+    # claims. ``verify file <version>`` remains an historical claim check.
+    if (os.path.isfile(a.file) and not a.version and
+            inspection["status"] != "ok"):
+        if a.json:
+            print(json.dumps({"artifact": a.file, "version": ev["version"],
+                              "status": "worktree_mismatch",
+                              "errors": inspection["errors"],
+                              "ledger_head": inspection.get("ledger_head"),
+                              "observed_version": inspection.get("observed_version")},
+                             ensure_ascii=False, indent=2))
+        elif a.md:
+            print("⚠️ **worktree mismatch** — " + ", ".join(inspection["errors"]))
+        else:
+            print(f"verify {a.file} @ {ev['version']} (v{n})")
+            print("  worktree mismatch: " + ", ".join(inspection["errors"]))
+            if inspection.get("ledger_head"):
+                observed = inspection.get("observed_version") or "unrecorded/unknown"
+                print(f"  ledger head: {inspection['ledger_head']} (worktree: {observed})")
+            if "unmanaged_worktree" in inspection["errors"]:
+                print(f"  action: run `proofpress identify {a.file}`; reconcile the file before snapshotting")
+            else:
+                print("  action: restore or reconcile the ledger head; snapshot only if this edit is intentional")
+        sys.exit(1)
     computed = {c["block"]: c for c in ev.get("changes", [])}
     claims = ev.get("claims")
     if claims is None:
@@ -1551,15 +1893,16 @@ def cmd_verify(a):
             note = f' — "{cl["note"]}"' if cl.get("note") else ""
             if r["ok"]:
                 what = cl.get("kind")
-                print(f'  {C("add", "✓")} [{what}] {ctx or cl.get("block", "?")} '
+                label = verify_label(comp, cl.get("block", "?"))
+                print(f'  {C("add", "✓")} [{what}] {label} '
                       f'{C("dim", "(" + cl.get("block", "?") + ")")}{C("dim", note)}')
             else:
                 actual = comp["kind"] if comp else "unchanged"
                 print(f'  {C("move", "⚠")} claimed {B(cl.get("kind", "?"))} but computed '
-                      f'{B(actual)}: {ctx or "?"} {C("dim", "(" + cl.get("block", "?") + ")")}{C("dim", note)}')
+                      f'{B(actual)}: {verify_label(comp, "?")} {C("dim", "(" + cl.get("block", "?") + ")")}{C("dim", note)}')
         for c in undisclosed:
             print(f'  {C("move", "⚠")} undisclosed change: [{c["kind"]}] '
-                  f'{c.get("context") or c.get("preview", "")[:40]} {C("dim", "(" + c["block"] + ")")}')
+                  f'{verify_label(c, "?")} {C("dim", "(" + c["block"] + ")")}')
         print()
         verdict = (C("add", f"{n_ok} verified") if not n_bad and not undisclosed
                    else C("move", f"{n_ok} verified, {n_bad} mismatch, {len(undisclosed)} undisclosed"))
@@ -1608,6 +1951,29 @@ def main():
     vf.set_defaults(f=cmd_verify)
     an = sub.add_parser("anchor"); an.add_argument("file"); an.set_defaults(f=cmd_anchor)
     ig = sub.add_parser("ingest"); ig.add_argument("file"); ig.set_defaults(f=cmd_ingest)
+    ml = sub.add_parser("merge-lineage",
+                        help="snapshot a file that merges other Proofpress artifacts, recording ingredient references")
+    ml.add_argument("file")
+    ml.add_argument("--from", dest="source", action="append", required=True,
+                    metavar="ARTIFACT", help="upstream artifact merged into this file (repeatable)")
+    ml.add_argument("--author", default="unknown")
+    ml.add_argument("--kind", default="human", choices=["human", "agent", "system"])
+    ml.add_argument("--session", default=None); ml.add_argument("--note", default=None)
+    ml.add_argument("--base-version", default=None)
+    ml.add_argument("--claims", default=None)
+    ml.add_argument("--why", default=None)
+    ml.add_argument("--rejected", action="append", default=None)
+    ml.add_argument("--requested-by", action="append", default=None)
+    ml.add_argument("--produced-by", action="append", default=None)
+    ml.add_argument("--edited-by", action="append", default=None)
+    ml.add_argument("--recorded-by", action="append", default=None)
+    ml.add_argument("--attribution-basis", choices=ATTRIBUTION_BASES,
+                    default="self_asserted")
+    ml.set_defaults(f=cmd_merge_lineage)
+    idn = sub.add_parser("identify",
+                         help="recognize a stripped file by its soft-binding fingerprint")
+    idn.add_argument("file")
+    idn.add_argument("--json", action="store_true"); idn.set_defaults(f=cmd_identify)
     ex = sub.add_parser("export"); ex.add_argument("file")
     ex.add_argument("-o", "--output", default=None); ex.set_defaults(f=cmd_export)
     ini = sub.add_parser("init"); ini.set_defaults(f=cmd_init)
@@ -1629,6 +1995,9 @@ def main():
     cl.add_argument("-o", "--output", required=True); cl.set_defaults(f=cmd_clean)
     ca = sub.add_parser("capture")
     ca.add_argument("--recorder", required=True); ca.add_argument("--session", default=None)
+    ca.add_argument("files", nargs="*",
+                    help="specific Markdown/HTML files to reconcile; "
+                         "default: Git candidates plus admitted ledger paths")
     ca.set_defaults(f=cmd_capture)
     a = p.parse_args(); a.f(a)
 

package/skills/README.md

@@ -11,13 +11,18 @@ Git.
 | 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` |
+| Hook / `capture` | Git candidates, admitted ledger paths, or explicit files | 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:666c5555)
+Before editing an existing target, run `capture --recorder
+<harness>-preflight <file>` so any human drift becomes a separate unattributed
+version. Then:
+
 [//]: # (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
@@ -62,7 +67,7 @@ that use `npx --no-install`, so agents never download the package implicitly:
 
 [//]: # (ob:5ee2d540)
 ```sh
-npm install --save-dev proofpress@next
+npm install --save-dev proofpress
 npx --no-install proofpress setup --agent codex
 ```
 

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

@@ -1,5 +1,5 @@
 {
-  "//": "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.",
+  "//": "Merge into .claude/settings.json. This best-effort fallback checks Git candidates plus current paths already admitted to the ledger. It records only the hook identity as recorded_by; it does not infer who authored the content or why.",
   "hooks": {
     "Stop": [
       {

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

@@ -13,6 +13,11 @@ testimony and verification. Do not snapshot every conversational turn.
 [//]: # (ob:d8284708)
 ## Workflow
 
+[//]: # (ob:78295d28)
+Before editing an existing target, run
+`python3 proofpress.py capture --recorder claude-preflight <file>`. This
+preserves any human drift without guessing its author or reason. Then:
+
 [//]: # (ob:04e1285c)
 1. Read `python3 proofpress.py policy <file>`. If the user asks for portability,
 
@@ -58,7 +63,7 @@ testimony and verification. Do not snapshot every conversational turn.
 [//]: # (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
+canonical project URL, and ask whether to install `proofpress`. Never
 download or execute it without explicit consent. If the CLI is available, run
 `inspect` before trusting the capsule and then `import`.
 

package/skills/codex/AGENTS-snippet.md

@@ -9,6 +9,12 @@ For accepted, meaningful revisions to Markdown or static HTML knowledge
 artifacts—never source code—close this loop. Do not snapshot every
 conversational turn.
 
+[//]: # (ob:af9efd22)
+Before editing an existing target, run
+`python3 proofpress.py capture --recorder codex-preflight <file>`. This
+preserves any human drift as a separate version without guessing its author or
+reason. Then:
+
 [//]: # (ob:d181cc6e)
 1. Read `python3 proofpress.py policy <file>`. If the user asks for portability,
 
@@ -54,7 +60,7 @@ conversational turn.
 [//]: # (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
+canonical project URL, and ask whether to install `proofpress`. Never
 download or execute it without explicit consent. If the CLI is available, run
 `inspect` before trusting the capsule and then `import`.
 

package/skills/codex/config-hooks.toml

@@ -1,5 +1,5 @@
 # Merge into ~/.codex/config.toml (Codex hooks GA since v0.124).
-# Best-effort fallback: capture changed, staged, and untracked Markdown and static HTML files.
+# Best-effort fallback: capture Git candidates and current admitted ledger paths.
 # The hook identifies itself only as recorded_by; it does not pretend to know
 # who wrote the content or why.
 

package/skills/cursor/proofpress/SKILL.md

@@ -13,6 +13,11 @@ testimony and verification. Do not snapshot every conversational turn.
 [//]: # (ob:e14e12ad)
 ## Workflow
 
+[//]: # (ob:0d9e887a)
+Before editing an existing target, run
+`python3 proofpress.py capture --recorder cursor-preflight <file>`. This
+preserves any human drift without guessing its author or reason. Then:
+
 [//]: # (ob:42fd42e7)
 1. Read `python3 proofpress.py policy <file>`. If the user asks for a portable
 
@@ -61,7 +66,7 @@ testimony and verification. Do not snapshot every conversational turn.
 [//]: # (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
+canonical project URL, and ask whether to install `proofpress`. Never
 download or execute it without explicit consent. If the CLI is available, run
 `inspect` before trusting the capsule and then `import`.
 

package/skills/pi/extension-skeleton.ts

@@ -5,9 +5,10 @@
  * 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.
+ * Intent: on session end, run best-effort capture across Git candidates and
+ * current paths already admitted to the ledger. 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";
 

package/skills/pi/proofpress-skill.md

@@ -6,6 +6,11 @@ For accepted, meaningful revisions to Markdown or static HTML knowledge
 artifacts—never source code—close this loop. Do not snapshot every
 conversational turn.
 
+[//]: # (ob:211b5d98)
+Before editing an existing target, run
+`python3 proofpress.py capture --recorder pi-preflight <file>`. This preserves
+any human drift without guessing its author or reason. Then:
+
 [//]: # (ob:87ce54bb)
 1. Read `python3 proofpress.py policy <file>`. If the user asks for portability,
 
@@ -51,7 +56,7 @@ conversational turn.
 [//]: # (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
+canonical project URL, and ask whether to install `proofpress`. Never
 download or execute it without explicit consent. If the CLI is available, run
 `inspect` before trusting the capsule and then `import`.