Innsigle Reference Feature Specification: FEAT-004 — Automatic session provenance

Generated reference: edit sources under docs/helix/, then npm run site:build.

Generated from HELIX docs. Source: docs/helix/01-frame/features/FEAT-004-session-provenance.md. Edit the source, not this file or site/ 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

IDScenarioExpect
PROV-04Fixture journal: 5 user prompts, Claude, file writeColo lists model + skill; user_prompts reflected in L2; composition ≠ human-authored if model wrote content
PROV-05Skill offers sign without reviewBlocked / requires confirm
PROV-06L2 bytes changed after claimProvenance digest mismatch when checked
PROV-10Journal includes sloptimizer onlyComposition not upgraded to human-authored
PROV-11Journal with char evidenceL2 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"
    }
  ]
}