Generated from HELIX docs. Source:docs/helix/01-frame/features/FEAT-004-session-provenance.md. Edit the source, not this file orsite/HTML.
Source frontmatter
ddx:
id: innsigle.feat.004
type: feature-specification
links:
- target: innsigle.prd
kind: informed_by
- target: innsigle.feat.002
kind: informed_by
- target: innsigle.design.session-provenance
kind: informed_by
- target: innsigle.contract.001
kind: informs
- target: innsigle.adr.001
kind: informed_by
- target: innsigle.adr.003
kind: informed_by
status: draft
activity: 01-frame
created: 2026-07-24
Feature Specification: FEAT-004 — Automatic session provenance
Feature ID: FEAT-004 Status: Specified (P1 implemented: CLI + fixture multi-agent driver; P2 implemented per PLAN-001: transcript import, provenance sync, seal --auto) Priority: P1 (after FEAT-001–003 core path) Owner: Operator Covered PRD Subsystem(s): UC-AI-docs; Tooling; Sign and Verify Covered PRD Requirements: FR-1–4a, FR-8–12, FR-18–19 (extends with automation) Cross-Subsystem Rationale: Agent/skill capture feeds colo + optional signed claim without laundering authorship.
Overview
When an agent (e.g. Claude) with an Innsigle-aware skill produces a file, the system can automatically capture session metrics and tool/model/skill use, propose a detailed colophon, and optionally publish + sign provenance bound to the content digest.
Ideal Future State
Operator enables a skill. After a session that writes page.md, they run (or the skill offers) “build provenance → propose colo → review → sign.” Public claim includes composition, named tools, prompt counts, and a link/digest to a session provenance document. Verify still fails closed on content tamper. Transcripts stay local unless explicitly published.
Problem Statement
- Current situation: Colo is hand-authored; sample is static; no harness integration.
- Pain points: Detailed “how many prompts / which skill” is lost; manual bills under-specify agent work.
- Desired outcome: Spec + schemas + phased CLI/skill path for automatic L2 provenance and L1 colo proposal.
Requirements
Functional
PROV-01. System defines a session provenance document (L2) with metrics including at least user_prompts, models, skills/tools, and primary artifact digests. PROV-02. Capturing skill/harness records a local structured journal of session events. PROV-03. Tooling builds L2 from journal with redaction of secrets before any publish path. PROV-04. Tooling proposes colo (L1) from L2 including named models/tools and capturing skill; composition suggestion is conservative (FR-4a). PROV-05. Operator review is required before publish or sign. PROV-06. Colo MAY reference L2 via provenance.uri + provenance.digest (JCS+SHA-256). PROV-07. Claim/sign/verify of content remains ADR-001/CONTRACT-001; L2 optional to verify. PROV-08. Auto-publish of L2 and auto-sign are off by default. PROV-09. Published L2 MUST NOT require raw transcript bodies; transcript URI is opt-in. PROV-10. Skill MUST NOT set human-authored solely due to rewrite/cleanup tools. PROV-11. Tooling MAY compute a human-input measure (hi1, FR-20) from journal char/prompt/review evidence; it records raw counts, is omitted when evidence is absent (never invented), and is shown during PROV-05 operator review.
Non-Functional
- Works without Innsigle-hosted cloud.
- L2 publish uses same host classes as ADR-003 D7 (gist/Pages/free HTTPS).
- Golden tests for propose-colo from fixture journal.
Acceptance sketches
| ID | Scenario | Expect |
|---|---|---|
| PROV-04 | Fixture journal: 5 user prompts, Claude, file write | Colo lists model + skill; user_prompts reflected in L2; composition ≠ human-authored if model wrote content |
| PROV-05 | Skill offers sign without review | Blocked / requires confirm |
| PROV-06 | L2 bytes changed after claim | Provenance digest mismatch when checked |
| PROV-10 | Journal includes sloptimizer only | Composition not upgraded to human-authored |
| PROV-11 | Journal with char evidence | L2 human_input percent recomputable from recorded counts; journal without char fields → measure null in L2 and omitted from colo |
Dependencies
- FEAT-001 colo language
- FEAT-002 claim/sign/verify
- ADR-001 / ADR-003
docs/helix/02-design/session-provenance.md
Out of scope (this FEAT)
- Full multi-harness support day one (one reference harness is enough for P2)
- Real-time streaming provenance UI
- Court-grade forensic logs
Innsigle seal: model-primary by Innsigle (build key)
Signature covers the markdown source of this page, not these HTML bytes. This render quotes that seal.
- Composition
- model-primary
- Issuer
- Innsigle
innsigle - Signing key
ed25519:050bf4d0361a96aa3b6baa3fc2ffd0cb(build key)- Signed source
docs/website/content/generated/artifacts/features/feat-004-session-provenance.md- Signed
- 2026-09-30T20:48:46Z
- Content digest
sha256:4423f0e4…c0591bba
Endorsed by the human key for seal recognition (ADR-003).
Raw attestation JSON
{
"payload": {
"innsigle": "1",
"type": "https://innsigle.dev/claim/colophon/v1",
"issued_at": "2026-09-30T20:48:46Z",
"issuer": {
"id": "innsigle",
"name": "Innsigle",
"key_id": "ed25519:050bf4d0361a96aa3b6baa3fc2ffd0cb",
"key_url": "https://documentdrivendx.github.io/innsigle/.well-known/innsigle/keys.json"
},
"subjects": [
{
"uri": "https://documentdrivendx.github.io/innsigle/reference/artifacts/features/feat-004-session-provenance/",
"digest": {
"alg": "sha256",
"value": "4423f0e4774eca4d3f7b7f6b82628a0010375bc39ed2e9b0371dac9ac0591bba"
}
}
],
"colophon": {
"schema_version": "1",
"composition": "model-primary",
"ingredients": [
{
"kind": "model",
"name": "Claude",
"role": "draft"
},
{
"kind": "tool",
"name": "sloptimizer",
"role": "rewrite"
},
{
"kind": "human",
"name": "operator",
"role": "structure-edit"
}
],
"notes": null
}
},
"payload_encoding": "json",
"signatures": [
{
"key_id": "ed25519:050bf4d0361a96aa3b6baa3fc2ffd0cb",
"alg": "ed25519",
"sig": "vVoSg5e-cY3y1Oe7PR-WQwOn0sU7i_syZD40YbewUtK1vc1n7gWuigggFf_ThO1XgOBH6JExbTSU9q-z77-BAQ",
"signed_at": "2026-09-30T20:48:46Z"
}
]
}