Phase Track P / P0 — Agent identity & signed provenance (Thinking freeze)

Status: Reviewed → pass (P0-r2). P0 is spec-only and now frozen; the P1 Auto build is cleared to start against this contract. No code landed under P0.

phase: TRACK-P-P0
outputs:
- id: track-p-p0-agent-provenance
  path: docs/archive/phases/PHASE-TRACK-P-P0-AGENT-PROVENANCE.md
  frozen: true
frozen_inputs:
- id: k9a-l1-l2-module-freeze
  path: docs/archive/phases/PHASE-K9A-L1-L2-MODULE-FREEZE.md
- id: honesty-ledger-impl
  path: tools/honesty/ledger.py
- id: honesty-canonical-hash
  path: tools/honesty/canonical.py
- id: honesty-validate
  path: tools/honesty/validate.py
- id: layered-honesty-vision-l3
  path: docs/archive/thinking/OVERSEER-KIT-LAYERED-HONESTY-VISION.md#24-l3--musehub-substrate-optional-deepen
- id: muse-social-domain-provenance
  path: https://staging.musehub.ai/gabriel/musehub/issues/6
review_stamp:
  reviewed_at: '2026-07-12T16:57:14Z'
  verdict: pass
  reviewer_mode: agent
  reviewer_model: thinking-high
  reviewer_provider: local
  kit_version: 0.1.0
  artifact_digest: sha256:7db8681257bcefc51fa211079052cb50d5b190aa3cd3f7f9e3117e6eb2244d4a

Downstream edge: Track P / P1 (Auto build) and the Muse social domain both consume this provenance schema as ground truth. Per SPEC §6 this is a mandatory reviewed freeze before P1 builds. Track P / P0 has no {step}b Auto build of its own.

Review record (§6.2): every freeze-review finding MUST cite file+line per SPEC §6; uncited findings are invalid. Fixes during the loop are Tier 1 (feature branch); merge to main is Tier 3.

§P0.0 — Simple summary

Right now the honesty ledger records what happened (a verdict passed, an artifact was approved) and chains entries so history cannot be silently rewritten. It does not record who produced each entry in a cryptographically verifiable way. Under git-only that identity is "soft" — a session string an agent can type. The Muse social domain (already Phases 00–02 on the muse repo) solves the same problem for social posts: every post carries agent_id, model_id, and an Ed25519 signature that traces back to a human owner's root key.

Track P / P0 freezes one shared primitive: an optional, additive provenance envelope on ledger entries — the same trust chain the Muse social domain uses. Soft (unsigned) under git-only; hard (Ed25519-signed, Muse-verified) under muse+git-mirror / muse-only. This is the L3 "signed human/agent identity" row from the vision doc, made concrete and testable.

Technical summary: add an optional provenance object to non-genesis ledger entry bodies, carrying agent_id, model_id, and optional sig (Ed25519 over the entry's chain hash). Extend compute_entry_hash to exclude provenance.sig so a signature can cover the chain position without altering it. Add a honesty.require_agent_signature config flag (default false; only meaningful under a Muse-backed regime) and new exit codes for signature failures. Backward-compatible with the frozen v1 ledger: existing unsigned entries verify unchanged.

§P0.1 — Scope

In scope (freeze only):

• The provenance entry envelope schema (§P0.3).
• Canonical-hash + signature rule so signatures are verifiable and chain-stable (§P0.4).
• honesty.require_agent_signature config flag + regime interaction (§P0.5).
• Exit-code additions for signature/provenance failures (§P0.6).
• git-only (soft) vs Muse (hard) capability tiers (§P0.7).
• Seven-tier test matrix the P1 build must satisfy (§P0.8).
• Shared-schema contract note for the Muse social domain (§P0.9).

Out of scope (explicit non-goals — prevent creep):

• Any social network features in the kit — no feeds, timelines, posts, DMs, follows. Those live in the Muse social domain and in Schooling as a consumer UI. The kit only supplies the provenance schema.
• Key management / mnemonic storage / HD derivation implementation — the kit verifies and records signatures; Muse owns key custody and derivation. Under git-only the kit never generates or holds private keys.
• Model routing (P-route) and verification-evidence capture (P-evidence) — deferred; not part of P0. May be freezed as later P slices if prioritized.
• A live "deployment gate" — named as a future candidate only; not scoped here.
• Making any of this required under git-only — K7 guardrail: no core governance feature may be MuseHub-only, and equally, signed identity must never be mandatory for the git-only baseline.

§P0.2 — What exists now (verified, do not redesign)

From tools/honesty/ (K9a/K10, frozen):

P0 must not change genesis, the chain-walk algorithm's structure, existing kinds, or existing exit-code meanings. It only adds an optional envelope and new failure codes.

§P0.3 — The provenance envelope (frozen schema)

Optional object on any non-genesis entry body. Genesis entries MUST NOT carry provenance (consistent with genesis field restrictions in validate.py).

provenance:
  agent_id:   str            # required when provenance present; e.g. "cursor-agent", "claude-code"
  model_id:   str            # required when provenance present; e.g. "gpt-5.6", "claude-opus-4-8"
  human_ref:  str | null     # optional owner handle/DID the agent key derives from (Muse)
  sig:        str | null     # optional "ed25519:<base64>" over the entry chain hash (§P0.4)
  pubkey:     str | null     # optional "ed25519:<base64>" agent public key (or resolved via Muse)

Rules:

1. When provenance is present, agent_id and model_id MUST be non-empty strings.
2. sig and pubkey are optional under git-only (soft identity). When one is present, both MUST be present.
3. provenance is permitted on all non-genesis kinds. For verdict and approval_recorded (the spend/authority-bearing kinds), a Muse-backed regime MAY require a valid sig (§P0.5).
4. Unknown keys inside provenance fail closed (exit 2) — mirrors the strict-key discipline used for config parsing.

§P0.4 — Canonical hash & signature rule (frozen)

To let a signature cover the entry's chain position without changing that position:

1. Chain hash excludes the signature. compute_entry_hash is extended to strip both entry_hash and provenance.sig before canonicalization. Because stripping an absent nested key is a no-op, every existing unsigned entry hashes identically — the v1 chain is unbroken.
2. Signature domain. sig = ed25519_sign(agent_privkey, utf8(entry_hash_hex)). The signature signs the lowercase hex entry_hash string (the chain position), so verification needs only the entry itself plus the public key.
3. Verification. verify recomputes entry_hash (excluding sig), then, when sig present, checks ed25519_verify(pubkey, entry_hash_hex, sig). pubkey comes from the entry (git-only) or is resolved via Muse's key registry / HD derivation from human_ref (Muse regimes).
4. Version stays v: 1. This is a purely additive envelope; no v bump. The frozen validator's v == 1 rule is unchanged.

§P0.5 — Config flag & regime interaction (frozen)

Add to the honesty: config block (additive; default preserves current behavior):

honesty:
  require_agent_signature: false   # default false
  # when true AND regime is muse-backed: verdict + approval_recorded entries
  #   MUST carry a valid provenance.sig, else append refuses (exit 25/26).
  # under git-only: setting true is a config error (26) — signed identity is a
  #   Muse capability; the git-only baseline must never hard-require it (K7 guardrail).

§P0.6 — Exit codes (frozen additions; non-overlapping)

Existing codes 10–11, 20–24 are unchanged. verify_chain still returns 22 for chain breakage; signature failure is the distinct code 25 so operators can tell "history tampered" from "identity unverifiable" apart.

§P0.7 — Capability tiers (frozen)

This is the vision doc's L3 row (§2.4) made concrete. Baseline honesty (L0–L2) remains fully usable on plain GitHub; signatures are the optional Muse deepen.

§P0.8 — Seven-tier test matrix (P1 build must satisfy)

§P0.9 — Shared-schema contract with the Muse social domain (informative)

The Muse social domain (gabriel/musehub issue #6) signs every post with an Ed25519 key derived from a human root via HD derivation, and records agent_id + model_id on agent posts. The provenance envelope frozen here is deliberately the same shape so that:

• An agent's honesty-ledger verdict and its social post share one identity + signature model.
• The social graph's trust chain and the kit's ledger trust chain resolve keys the same way (Muse key registry / human_ref derivation).
• Schooling's social page (a consumer UI over Muse's social feed API, api/social/<handle>) inherits verifiable agent provenance without the kit implementing any social feature.

The kit remains governance/honesty-only. Social protocol = Muse; social UI = Schooling.

§P0.10 — Close-out (execute only when P0 marked DONE)

1. Freeze-review pass recorded in the Review record table above.
2. ROADMAP Track P row: P0 → DONE; add P1 (Auto build) row against this contract.
3. Handover NEXT flips to Track P / P1 (Auto build) with paste-ready prompt + governance gates.
4. Governance sync: ROADMAP + handover in the same commit (SD-17).