kairos-chain 3.34.0 → 3.35.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a393cfbac08011bdd6f7b8cd3129177f535c7507868215d6b85ef2af732e8521
-  data.tar.gz: 202af122d66197111412f5cdfc48287872713781602fe7f5f428ec40f3e111a9
+  metadata.gz: 790cf38c2263e065c856211e0dce54a56a4e9599b2b028dbd3335405f78d069f
+  data.tar.gz: 3a568dc9d900c4aefc24572657043c82d94ea62027a349f6c3e20094d778cbb7
 SHA512:
-  metadata.gz: 880c1f5206e0e84ab3b448abd25e5ec3a2fd012840a0f0f2b1d67bd8883fc54da27a945e451de3c2dfc96c36628658db625190b8a8ad8dd8796b1c5b7cbf2eb1
-  data.tar.gz: 4a2187976ddddc4e4a27ef51075f38ddeff13539f60c8928150bce1d3d97d607b6bb09aa327179569209ddcf440cae575b53b1460e5f9f350553d2760a6e4a7a
+  metadata.gz: a3d7d364ecfe3512de1ca75375eefe890002b4c228f7dd3245ea00277abe1552030261a3916ef27ec3c1e968381646ac73a0811672016a8d16d6fab282954c31
+  data.tar.gz: 1bc3370f34c14841d0b57c471ff9e71185521bfe36b583c788732f6513d453c619a07e53070bb6e4d674b6b3b2ae4ec716663f53247d65e9a380a968e942752c

data/CHANGELOG.md

@@ -4,6 +4,39 @@ All notable changes to the `kairos-chain` gem will be documented in this file.
 
 This project follows [Semantic Versioning](https://semver.org/).
 
+## [3.35.0] - 2026-07-05
+
+### Added — Synoptis: L2 constitutive attestation (Slice 1)
+
+First slice of the L2 attestation capability (design v0.9 FROZEN, 6/6 unanimous),
+extending the Synoptis SkillSet. Enters selected L2 judgments into a dedicated
+append-only attestation ledger — a dated line stating "at moment T, subject X had
+digest D" — with a propose-only activation policy so entries actually get made
+(the system proposes; the human approves).
+
+New constitutive module (siblings to the trust engine; the existing attestation
+engine, verifier, revocation manager, and trust scorer are untouched):
+`constitutive/{content_attestation_entry,subject_ref,attestation_chain,proposal_criterion}`.
+
+Three tools: `l2_attestation_scan` (ACT-5+ACT-2: actively proposes a session's
+judgment-bearing contexts — frontmatter type handoff/decision/debrief — and logs a
+trigger record), `l2_attestation_commit` (ACT-1: `approved: true` two-call human
+gate appends one content-attestation `(subject, digest, moment)`; digest = SHA256
+of the subject's persisted bytes), `l2_attestation_decline` (ACT-4: content-free
+decline record).
+
+Two dedicated append-only stores on Synoptis's FileRegistry chain machinery,
+neither the Meta Ledger (LED-5): `l2_attestation.jsonl` (human-approved) and
+`l2_operational_log.jsonl` (telemetry). FileRegistry gains additive generic
+`append`/`read`; no existing behaviour changed. Posture is flat — workflow-level
+human approval, no cryptographic consent signal, never exceeding the L0/L1 posture
+(LED-6).
+
+Invariants satisfied this slice: LED-1, LED-2a, LED-3, LED-5, ACT-1, ACT-2 (simple
+frontmatter criterion, revisable), ACT-4, ACT-5. Deferred to later slices: LED-2b
+(lineage/supersession), LED-6 (anchoring), ACT-3 (approval-to-digest binding).
+35 unit tests (`test_l2_constitutive_slice1.rb`) green.
+
 ## [3.34.0] - 2026-07-03
 
 ### Added — L1 knowledge (dev repo): loop_validation

data/lib/kairos_mcp/version.rb

@@ -1,4 +1,4 @@
 module KairosMcp
-  VERSION = "3.34.0"
+  VERSION = "3.35.0"
   CHANGELOG_URL = "https://github.com/masaomi/KairosChain_2026/blob/main/CHANGELOG.md"
 end

data/templates/skillsets/synoptis/config/synoptis.yml

@@ -47,6 +47,16 @@ trust_v2:
     integrity_verified: 0.60
     default: 0.50
 
+# Constitutive L2 attestation (Slice 1) — dedicated append-only ledger + operational
+# log on Synoptis's FileRegistry chain machinery (NOT the Meta Ledger). Design v0.9.
+constitutive:
+  digest_alg: sha256
+  # ACT-2 first-cut criterion (revisable): propose only judgment-bearing L2 contexts.
+  judgment_types:
+    - handoff
+    - decision
+    - debrief
+
 challenge:
   response_timeout: 3600      # 1 hour
   max_active_per_subject: 5

data/templates/skillsets/synoptis/lib/synoptis/constitutive/attestation_chain.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require 'time'
+
+module Synoptis
+  module Constitutive
+    # Two dedicated append-only stores on Synoptis's FileRegistry chain machinery
+    # (design v0.9, LED-5). Neither is the Meta Ledger:
+    #
+    #   - l2_attestation      content-attestation entries; human-approved (ACT-1)
+    #   - l2_operational_log  trigger + decline records; telemetry, not approved (ACT-4/5)
+    #
+    # Both inherit FileRegistry's append-only + hash-chain (_prev_entry_hash) discipline
+    # — the bank-ledger integrity model (LED-2a): lines are only ever appended, never
+    # rewritten. The two stores are distinct files, so a judgment-bearing entry and a
+    # telemetry record never share one line definition (the recurring taxonomy defect
+    # the design closed via §Kinds).
+    class AttestationChain
+      LEDGER = :l2_attestation
+      OPLOG  = :l2_operational_log
+
+      def initialize(registry:)
+        @registry = registry
+      end
+
+      # ACT-1: append an approved content-attestation entry to the ledger.
+      def append_content_attestation(entry)
+        @registry.append(LEDGER, entry.to_h)
+      end
+
+      def entries
+        @registry.read(LEDGER)
+      end
+
+      # ACT-5: telemetry that the criterion fired and surfaced N proposals. Subject-free
+      # and content-free, so it neither indexes L2 (LED-4) nor records a per-context
+      # verdict (ACT-4).
+      def append_trigger(surfaced_count:, moment: nil)
+        @registry.append(OPLOG, {
+          record: 'trigger',
+          surfaced_count: surfaced_count,
+          moment: moment || Time.now.utc.iso8601
+        })
+      end
+
+      # ACT-4: telemetry that a proposed subject was declined. Content-free, keyed by
+      # subject id only. An approval writes NO decision record — it is evidenced by the
+      # content-attestation entry it produced.
+      def append_decline(subject_id:, moment: nil)
+        @registry.append(OPLOG, {
+          record: 'decision',
+          decision: 'declined',
+          subject_id: subject_id,
+          moment: moment || Time.now.utc.iso8601
+        })
+      end
+
+      def oplog
+        @registry.read(OPLOG)
+      end
+
+      def verify_chain(type = LEDGER)
+        @registry.verify_chain(type)
+      end
+    end
+  end
+end

data/templates/skillsets/synoptis/lib/synoptis/constitutive/content_attestation_entry.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'digest'
+require 'securerandom'
+require 'time'
+
+module Synoptis
+  module Constitutive
+    # A single content-attestation entry on the L2 attestation chain (design v0.9,
+    # §Kinds / LED-3). It commits (subject_id, digest, moment) and may embed an
+    # optional content snapshot.
+    #
+    # Deliberately carries NO signature and NO ttl: the entry is workflow-approved
+    # (ACT-1), not crypto-gated, and an attestation entry does not expire (design §11).
+    # This is posture parity with L0/L1 (LED-6), not a regression against Synoptis's
+    # signed ProofEnvelope — it is a different kind for a different purpose.
+    class ContentAttestationEntry
+      KIND = 'content_attestation'
+      DEFAULT_DIGEST_ALG = 'sha256'
+
+      attr_reader :entry_id, :subject_id, :digest, :digest_alg, :moment, :snapshot
+
+      def initialize(subject_id:, digest:, moment:, digest_alg: DEFAULT_DIGEST_ALG,
+                     snapshot: nil, entry_id: nil)
+        @entry_id = entry_id || SecureRandom.uuid
+        @subject_id = subject_id
+        @digest = digest
+        @digest_alg = digest_alg
+        @moment = moment
+        @snapshot = snapshot
+      end
+
+      def to_h
+        {
+          kind: KIND,
+          entry_id: @entry_id,
+          subject_id: @subject_id,
+          digest: @digest,
+          digest_alg: @digest_alg,
+          moment: @moment,
+          snapshot: @snapshot
+        }
+      end
+
+      # Deterministic canonical form for hashing. A nil snapshot is retained as JSON
+      # null (no .compact) so the hash is stable regardless of which optional fields
+      # are populated — same discipline as ProofEnvelope#canonical_json.
+      def canonical_json
+        JSON.generate(to_h, sort_keys: true)
+      end
+
+      def entry_hash
+        Digest::SHA256.hexdigest(canonical_json)
+      end
+
+      def self.from_h(hash)
+        hash = hash.transform_keys(&:to_sym) if hash.is_a?(Hash)
+        new(
+          subject_id: hash[:subject_id],
+          digest: hash[:digest],
+          moment: hash[:moment],
+          digest_alg: hash[:digest_alg] || DEFAULT_DIGEST_ALG,
+          snapshot: hash[:snapshot],
+          entry_id: hash[:entry_id]
+        )
+      end
+    end
+  end
+end

data/templates/skillsets/synoptis/lib/synoptis/constitutive/proposal_criterion.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Synoptis
+  module Constitutive
+    # ACT-2 selection criterion (first-cut, revisable). Given a session, proposes the
+    # session's judgment-bearing L2 contexts — those whose frontmatter `type` is in the
+    # configured judgment set (default: handoff / decision / debrief).
+    #
+    # This is intentionally simple and config-driven now; it evolves toward an
+    # LLM-semantic criterion that reads content (design §4 note, §11). Simplicity is safe
+    # because ACT-1 puts a human approval gate after every proposal: a wrong proposal is
+    # declined, never silently attested. Proposals are recommendations only — they create
+    # no attestation and no obligation until approved.
+    class ProposalCriterion
+      DEFAULT_JUDGMENT_TYPES = %w[handoff decision debrief].freeze
+
+      def initialize(context_dir:, judgment_types: DEFAULT_JUDGMENT_TYPES)
+        @context_dir = context_dir
+        @judgment_types = Array(judgment_types).map(&:to_s)
+      end
+
+      # Returns an array of proposals:
+      #   { subject_id:, type:, content_state: }
+      def propose(session_id:)
+        session_dir = File.join(@context_dir, session_id.to_s)
+        return [] unless Dir.exist?(session_dir)
+
+        Dir.children(session_dir).sort.filter_map do |context_name|
+          next unless File.directory?(File.join(session_dir, context_name))
+
+          uri = "context://#{session_id}/#{context_name}"
+          type = SubjectRef.frontmatter_type(uri, context_dir: @context_dir)
+          next unless type && @judgment_types.include?(type.to_s)
+
+          {
+            subject_id: uri,
+            type: type.to_s,
+            content_state: SubjectRef.content_state(uri, context_dir: @context_dir)
+          }
+        end
+      end
+    end
+  end
+end

data/templates/skillsets/synoptis/lib/synoptis/constitutive/subject_ref.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require 'digest'
+require 'yaml'
+
+module Synoptis
+  module Constitutive
+    # Resolves a stable subject identity to its persisted L2 context file and computes
+    # a digest of the ACTUAL persisted bytes (design v0.9, LED-3).
+    #
+    # The subject-id is the `context://<session_id>/<context_name>` URI itself. It is
+    # stable across file rename/relocation because identity is the URI, not the path:
+    # the path is derived from the URI at read time. (If the underlying file is later
+    # moved, path resolution is a mechanism detail deferred to §11; the id is stable
+    # by construction.)
+    #
+    # The digest binds the entry to the fact that specific bytes existed at a moment —
+    # it proves THAT content matched, not WHAT it said (an audit that needs the wording
+    # embeds a snapshot; that is a later slice).
+    module SubjectRef
+      SCHEME = 'context://'
+      DIGEST_ALG = 'sha256'
+
+      module_function
+
+      # "context://<session_id>/<context_name>" -> { session_id:, context_name: }
+      def parse(uri)
+        s = uri.to_s
+        raise ArgumentError, "not a context uri: #{uri}" unless s.start_with?(SCHEME)
+
+        rest = s[SCHEME.length..]
+        session_id, context_name = rest.to_s.split('/', 2)
+        if session_id.nil? || session_id.empty? || context_name.nil? || context_name.empty?
+          raise ArgumentError, "malformed context uri: #{uri}"
+        end
+
+        { session_id: session_id, context_name: context_name }
+      end
+
+      # Layout: context_dir/<session_id>/<context_name>/<context_name>.md
+      def resolve_path(uri, context_dir:)
+        p = parse(uri)
+        File.join(context_dir, p[:session_id], p[:context_name], "#{p[:context_name]}.md")
+      end
+
+      def exists?(uri, context_dir:)
+        File.exist?(resolve_path(uri, context_dir: context_dir))
+      end
+
+      def read_bytes(uri, context_dir:)
+        File.binread(resolve_path(uri, context_dir: context_dir))
+      end
+
+      # SHA256 of the subject's persisted content bytes. Raises if the file is absent
+      # (fail-closed: never attest content that does not exist).
+      def digest(uri, context_dir:)
+        Digest::SHA256.hexdigest(read_bytes(uri, context_dir: context_dir))
+      end
+
+      # A pre-commit snapshot of the subject's persisted state, for surfacing in a
+      # proposal or approval. Content-free about meaning: only size + digest.
+      def content_state(uri, context_dir:)
+        path = resolve_path(uri, context_dir: context_dir)
+        if File.exist?(path)
+          bytes = File.binread(path)
+          { exists: true, bytes: bytes.bytesize,
+            digest: Digest::SHA256.hexdigest(bytes), digest_alg: DIGEST_ALG }
+        else
+          { exists: false, bytes: 0, digest: nil, digest_alg: DIGEST_ALG }
+        end
+      end
+
+      # Best-effort read of the frontmatter `type:` field (nil if absent/unparseable).
+      def frontmatter_type(uri, context_dir:)
+        path = resolve_path(uri, context_dir: context_dir)
+        return nil unless File.exist?(path)
+
+        fm = extract_frontmatter(File.read(path))
+        return nil unless fm.is_a?(Hash)
+
+        fm['type'] || fm[:type]
+      end
+
+      def extract_frontmatter(text)
+        return nil unless text.start_with?('---')
+
+        parts = text.split(/^---\s*$/, 3)
+        return nil if parts.length < 3
+
+        YAML.safe_load(parts[1])
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end

data/templates/skillsets/synoptis/lib/synoptis/registry/file_registry.rb

@@ -3,6 +3,7 @@
 require 'json'
 require 'digest'
 require 'fileutils'
+require 'time'
 
 module Synoptis
   module Registry
@@ -80,6 +81,26 @@ module Synoptis
         apply_filter(records, filter)
       end
 
+      # --- Generic append-only access (constitutive attestation reuse) ---
+      # Append any record to a named store type with the same append-only + hash-chain
+      # discipline as the typed stores above (LED-2a). Returns the stored record (with
+      # the _type / _stored_at / _prev_entry_hash envelope fields). Additive and
+      # non-breaking: the typed proof/revocation/challenge methods are unchanged.
+
+      def append(type, record)
+        full = record.merge(
+          _type: type.to_s,
+          _stored_at: Time.now.utc.iso8601,
+          _prev_entry_hash: last_entry_hash(type)
+        )
+        append_record(type, full)
+        full
+      end
+
+      def read(type)
+        read_records(type)
+      end
+
       # --- Chain verification (Proposition 5) ---
 
       def verify_chain(type)

data/templates/skillsets/synoptis/lib/synoptis/tool_helpers.rb

@@ -31,6 +31,39 @@ module Synoptis
       @_scorer ||= TrustScorer.new(registry: registry, config: synoptis_config)
     end
 
+    # --- Constitutive L2 attestation (Slice 1) ---
+
+    def context_root
+      KairosMcp.context_dir
+    end
+
+    def constitutive_chain
+      @_constitutive_chain ||= Constitutive::AttestationChain.new(registry: registry)
+    end
+
+    def proposal_criterion
+      @_proposal_criterion ||= Constitutive::ProposalCriterion.new(
+        context_dir: context_root,
+        judgment_types: constitutive_config['judgment_types'] ||
+          Constitutive::ProposalCriterion::DEFAULT_JUDGMENT_TYPES
+      )
+    end
+
+    def constitutive_config
+      synoptis_config['constitutive'] || synoptis_config[:constitutive] || {}
+    end
+
+    # Best-effort "current session": the most recently modified session dir under
+    # the L2 context root. Used when a scan is invoked without an explicit session_id.
+    def latest_session_id
+      root = context_root
+      return nil unless Dir.exist?(root)
+
+      Dir.children(root)
+         .select { |c| File.directory?(File.join(root, c)) }
+         .max_by { |c| File.mtime(File.join(root, c)) }
+    end
+
     def resolve_agent_id
       mmp_identity.introduce.dig(:identity, :instance_id)
     rescue StandardError

data/templates/skillsets/synoptis/lib/synoptis.rb

@@ -5,6 +5,10 @@ require_relative 'synoptis/verifier'
 require_relative 'synoptis/attestation_engine'
 require_relative 'synoptis/revocation_manager'
 require_relative 'synoptis/registry/file_registry'
+require_relative 'synoptis/constitutive/content_attestation_entry'
+require_relative 'synoptis/constitutive/subject_ref'
+require_relative 'synoptis/constitutive/attestation_chain'
+require_relative 'synoptis/constitutive/proposal_criterion'
 require_relative 'synoptis/challenge_manager'
 require_relative 'synoptis/trust_identity'
 require_relative 'synoptis/trust_scorer'

data/templates/skillsets/synoptis/skillset.json

@@ -15,7 +15,10 @@
     "KairosMcp::SkillSets::Synoptis::Tools::AttestationList",
     "KairosMcp::SkillSets::Synoptis::Tools::TrustQuery",
     "KairosMcp::SkillSets::Synoptis::Tools::ChallengeCreate",
-    "KairosMcp::SkillSets::Synoptis::Tools::ChallengeRespond"
+    "KairosMcp::SkillSets::Synoptis::Tools::ChallengeRespond",
+    "KairosMcp::SkillSets::Synoptis::Tools::L2AttestationScan",
+    "KairosMcp::SkillSets::Synoptis::Tools::L2AttestationCommit",
+    "KairosMcp::SkillSets::Synoptis::Tools::L2AttestationDecline"
   ],
   "config_files": ["config/synoptis.yml"],
   "knowledge_dirs": ["knowledge/synoptis_protocol"]

data/templates/skillsets/synoptis/test/test_l2_constitutive_slice1.rb

@@ -0,0 +1,189 @@
+# frozen_string_literal: true
+
+# Slice 1 unit + wiring tests for the L2 constitutive attestation module.
+# Pure Ruby: requires only FileRegistry + the constitutive module (no MMP).
+# Run from project root:
+#   ruby -I KairosChain_mcp_server/lib \
+#     KairosChain_mcp_server/templates/skillsets/synoptis/test/test_l2_constitutive_slice1.rb
+
+require 'tmpdir'
+require 'json'
+require 'digest'
+require 'fileutils'
+
+lib = File.expand_path('../lib', __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+
+require 'synoptis/registry/file_registry'
+require 'synoptis/constitutive/content_attestation_entry'
+require 'synoptis/constitutive/subject_ref'
+require 'synoptis/constitutive/attestation_chain'
+require 'synoptis/constitutive/proposal_criterion'
+
+$pass = 0
+$fail = 0
+
+def assert(cond, msg)
+  if cond
+    $pass += 1
+    puts "  PASS: #{msg}"
+  else
+    $fail += 1
+    puts "  FAIL: #{msg}"
+  end
+end
+
+def section(t)
+  puts "\n#{'=' * 60}\nSECTION: #{t}\n#{'=' * 60}"
+end
+
+CAE = Synoptis::Constitutive::ContentAttestationEntry
+SR  = Synoptis::Constitutive::SubjectRef
+AC  = Synoptis::Constitutive::AttestationChain
+PC  = Synoptis::Constitutive::ProposalCriterion
+
+# Build a fake L2 context tree: context_dir/<session>/<name>/<name>.md
+def write_context(context_dir, session_id, name, type, body = "body of #{name}")
+  dir = File.join(context_dir, session_id, name)
+  FileUtils.mkdir_p(dir)
+  fm = "---\ntitle: \"#{name}\"\ntype: #{type}\n---\n\n#{body}\n"
+  File.write(File.join(dir, "#{name}.md"), fm)
+  "context://#{session_id}/#{name}"
+end
+
+Dir.mktmpdir do |root|
+  context_dir = File.join(root, 'context')
+  data_dir = File.join(root, 'synoptis_data')
+  FileUtils.mkdir_p(context_dir)
+  FileUtils.mkdir_p(data_dir)
+  session = 'session_test_0001'
+
+  uri_handoff  = write_context(context_dir, session, 'my_handoff', 'handoff')
+  uri_decision = write_context(context_dir, session, 'my_decision', 'decision')
+  uri_debrief  = write_context(context_dir, session, 'my_debrief', 'debrief')
+  uri_plain    = write_context(context_dir, session, 'my_notes', 'session_summary')
+
+  # ---------------------------------------------------------------
+  section('ContentAttestationEntry — canonical form + hashing')
+
+  e1 = CAE.new(subject_id: uri_handoff, digest: 'abc123', moment: '2026-07-05T00:00:00Z')
+  e1b = CAE.new(subject_id: uri_handoff, digest: 'abc123', moment: '2026-07-05T00:00:00Z',
+                entry_id: e1.entry_id)
+  assert(e1.canonical_json == e1b.canonical_json, 'canonical_json deterministic for equal fields')
+  assert(e1.entry_hash == e1b.entry_hash, 'entry_hash deterministic for equal fields')
+
+  e2 = CAE.new(subject_id: uri_handoff, digest: 'abc124', moment: '2026-07-05T00:00:00Z',
+               entry_id: e1.entry_id)
+  assert(e1.entry_hash != e2.entry_hash, 'entry_hash changes when digest changes')
+
+  h = e1.to_h
+  assert(h[:kind] == 'content_attestation', 'to_h carries kind=content_attestation')
+  assert(h.key?(:snapshot) && h[:snapshot].nil?, 'nil snapshot retained (not compacted)')
+  round = CAE.from_h(e1.to_h)
+  assert(round.entry_hash == e1.entry_hash, 'from_h round-trips entry_hash')
+  assert(!e1.to_h.key?(:signature) && !e1.to_h.key?(:ttl), 'no signature / no ttl fields (posture parity)')
+
+  # ---------------------------------------------------------------
+  section('SubjectRef — parse / resolve / digest / type')
+
+  parsed = SR.parse(uri_handoff)
+  assert(parsed[:session_id] == session && parsed[:context_name] == 'my_handoff', 'parse splits uri')
+  assert_raised = begin; SR.parse('skill://foo'); false; rescue ArgumentError; true; end
+  assert(assert_raised, 'parse rejects non-context uri')
+
+  path = SR.resolve_path(uri_handoff, context_dir: context_dir)
+  assert(File.exist?(path), 'resolve_path points at the persisted file')
+
+  manual = Digest::SHA256.hexdigest(File.binread(path))
+  assert(SR.digest(uri_handoff, context_dir: context_dir) == manual, 'digest = SHA256 of persisted bytes')
+
+  # byte sensitivity: change one byte -> different digest; id unchanged
+  d_before = SR.digest(uri_handoff, context_dir: context_dir)
+  File.write(path, File.read(path) + 'x')
+  d_after = SR.digest(uri_handoff, context_dir: context_dir)
+  assert(d_before != d_after, 'digest changes when one byte changes')
+  assert(SR.parse(uri_handoff)[:context_name] == 'my_handoff', 'subject-id stable across content change')
+
+  assert(SR.frontmatter_type(uri_decision, context_dir: context_dir) == 'decision', 'frontmatter_type reads type')
+  cs = SR.content_state(uri_debrief, context_dir: context_dir)
+  assert(cs[:exists] && cs[:bytes] > 0 && cs[:digest], 'content_state reports exists/bytes/digest')
+
+  fail_closed = begin
+    SR.digest('context://nope/missing', context_dir: context_dir); false
+  rescue StandardError; true; end
+  assert(fail_closed, 'digest fail-closed on missing file (never attest absent content)')
+
+  # ---------------------------------------------------------------
+  section('ProposalCriterion (ACT-2) — judgment types only')
+
+  crit = PC.new(context_dir: context_dir)
+  proposals = crit.propose(session_id: session)
+  subjects = proposals.map { |p| p[:subject_id] }
+  assert(subjects.include?(uri_handoff), 'proposes handoff type')
+  assert(subjects.include?(uri_decision), 'proposes decision type')
+  assert(subjects.include?(uri_debrief), 'proposes debrief type')
+  assert(!subjects.include?(uri_plain), 'does NOT propose non-judgment (session_summary) type')
+  assert(proposals.length == 3, 'exactly 3 judgment contexts proposed')
+  assert(crit.propose(session_id: 'no_such_session') == [], 'empty for unknown session')
+
+  # ---------------------------------------------------------------
+  section('AttestationChain (LED-2a append-only + LED-5 two stores)')
+
+  reg = Synoptis::Registry::FileRegistry.new(data_dir: data_dir)
+  chain = AC.new(registry: reg)
+
+  before_meta = 0 # stand-in: no Meta Ledger touched by this module at all
+
+  ent_a = CAE.new(subject_id: uri_handoff, digest: SR.digest(uri_handoff, context_dir: context_dir),
+                  moment: '2026-07-05T01:00:00Z')
+  chain.append_content_attestation(ent_a)
+  ent_b = CAE.new(subject_id: uri_decision, digest: SR.digest(uri_decision, context_dir: context_dir),
+                  moment: '2026-07-05T02:00:00Z')
+  chain.append_content_attestation(ent_b)
+
+  entries = chain.entries
+  assert(entries.length == 2, 'two appends -> two ledger entries')
+  assert(entries[0][:_prev_entry_hash].nil?, 'first entry has no prev hash')
+  assert(!entries[1][:_prev_entry_hash].nil?, 'second entry links to prev (hash chain)')
+  vc = chain.verify_chain(AC::LEDGER)
+  assert(vc[:valid] && vc[:length] == 2, 'verify_chain valid, length 2')
+
+  ledger_file = File.join(data_dir, 'l2_attestation.jsonl')
+  oplog_file  = File.join(data_dir, 'l2_operational_log.jsonl')
+  assert(File.exist?(ledger_file), 'ledger is its own file l2_attestation.jsonl')
+
+  # ---------------------------------------------------------------
+  section('Operational log (ACT-4 decline / ACT-5 trigger)')
+
+  chain.append_trigger(surfaced_count: 3, moment: '2026-07-05T03:00:00Z')
+  chain.append_decline(subject_id: uri_debrief, moment: '2026-07-05T03:01:00Z')
+  oplog = chain.oplog
+  assert(oplog.length == 2, 'oplog has trigger + decline')
+  trig = oplog.find { |r| r[:record] == 'trigger' }
+  dec  = oplog.find { |r| r[:record] == 'decision' }
+  assert(trig && trig[:surfaced_count] == 3 && !trig.key?(:subject_id), 'trigger record content-free + subject-free')
+  assert(dec && dec[:decision] == 'declined' && dec[:subject_id] == uri_debrief, 'decline keyed by subject')
+  assert(!dec.key?(:digest) && !dec.key?(:content) && !dec.key?(:snapshot), 'decline is content-free (no digest/content)')
+  assert(File.exist?(oplog_file) && ledger_file != oplog_file, 'two distinct store files (LED-5)')
+
+  # ---------------------------------------------------------------
+  section('LED-1 selective — live context untouched by attestation')
+
+  live_before = File.binread(SR.resolve_path(uri_handoff, context_dir: context_dir))
+  chain.append_content_attestation(
+    CAE.new(subject_id: uri_handoff, digest: 'zzz', moment: '2026-07-05T04:00:00Z')
+  )
+  live_after = File.binread(SR.resolve_path(uri_handoff, context_dir: context_dir))
+  assert(live_before == live_after, 'appending an attestation does not modify the live context file')
+
+  # ---------------------------------------------------------------
+  section('Append-only surface — no edit/delete API')
+
+  assert(!chain.respond_to?(:delete) && !chain.respond_to?(:update), 'chain exposes no delete/update')
+  assert(!reg.respond_to?(:delete) && !reg.respond_to?(:overwrite), 'registry exposes no delete/overwrite')
+end
+
+puts "\n#{'=' * 60}"
+puts "RESULTS: #{$pass} passed, #{$fail} failed"
+puts '=' * 60
+exit($fail.zero? ? 0 : 1)

data/templates/skillsets/synoptis/tools/l2_attestation_commit.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module KairosMcp
+  module SkillSets
+    module Synoptis
+      module Tools
+        # ACT-1: appending a content-attestation entry requires human approval on every
+        # path. This is a workflow-level, human-in-the-loop confirmation (the `approved:
+        # true` two-call pattern, as with skills_evolve / skills_audit archive) — the same
+        # posture L0/L1 use, no cryptographic consent signal (LED-6).
+        #
+        #   - Called WITHOUT approved:true  -> returns the proposal (subject + content
+        #     state), writes NOTHING.
+        #   - Called WITH approved:true     -> appends exactly one content-attestation
+        #     entry (subject_id, digest, moment) to the l2_attestation chain.
+        #
+        # The digest is SHA256 of the subject's actual persisted bytes at commit time
+        # (LED-3); the moment is the append moment. (ACT-3 approval-to-digest binding and
+        # supersession arrive with Slice 2; Slice 1 recomputes at commit and attests the
+        # current bytes.)
+        class L2AttestationCommit < KairosMcp::Tools::BaseTool
+          include ::Synoptis::ToolHelpers
+
+          def name
+            'l2_attestation_commit'
+          end
+
+          def description
+            'Append one human-approved content-attestation (subject, digest, moment) for an L2 context to the constitutive attestation ledger. Requires approved: true; without it, returns the proposal and writes nothing (ACT-1).'
+          end
+
+          def category
+            :attestation
+          end
+
+          def usecase_tags
+            %w[attestation commit constitutive l2 approve audit]
+          end
+
+          def related_tools
+            %w[l2_attestation_scan l2_attestation_decline]
+          end
+
+          def input_schema
+            {
+              type: 'object',
+              properties: {
+                subject: { type: 'string', description: 'The L2 context to attest, as a context:// URI (e.g. "context://<session>/<name>").' },
+                approved: { type: 'boolean', description: 'Human approval. Must be true to append. Omitted/false returns the proposal without writing.' }
+              },
+              required: %w[subject]
+            }
+          end
+
+          def call(arguments)
+            subject = arguments['subject']
+            unless subject
+              return text_content(JSON.pretty_generate({ status: 'error', message: 'subject is required' }))
+            end
+
+            state = ::Synoptis::Constitutive::SubjectRef.content_state(subject, context_dir: context_root)
+            unless state[:exists]
+              return text_content(JSON.pretty_generate({
+                status: 'error', message: 'Subject content does not exist; cannot attest absent content.', subject: subject
+              }))
+            end
+
+            unless arguments['approved'] == true
+              return text_content(JSON.pretty_generate({
+                status: 'pending_approval',
+                subject: subject,
+                content_state: state,
+                note: 'Re-call with approved: true to append this content-attestation. Nothing was written.'
+              }))
+            end
+
+            entry = ::Synoptis::Constitutive::ContentAttestationEntry.new(
+              subject_id: subject,
+              digest: state[:digest],
+              digest_alg: state[:digest_alg],
+              moment: Time.now.utc.iso8601
+            )
+            constitutive_chain.append_content_attestation(entry)
+
+            text_content(JSON.pretty_generate({
+              status: 'attested',
+              entry: entry.to_h,
+              entry_hash: entry.entry_hash
+            }))
+          rescue StandardError => e
+            text_content(JSON.pretty_generate({ status: 'error', message: e.message }))
+          end
+        end
+      end
+    end
+  end
+end

data/templates/skillsets/synoptis/tools/l2_attestation_decline.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module KairosMcp
+  module SkillSets
+    module Synoptis
+      module Tools
+        # ACT-4: when the policy proposed a context and the human declined, append a
+        # content-free decision record to the operational log, keyed by subject id. An
+        # approval writes NO decision record — it is evidenced by the content-attestation
+        # entry it produced (via l2_attestation_commit), not duplicated here.
+        #
+        # A decline is not permanent in effect: an evolved criterion may re-propose, and
+        # that is a fresh decision, not a reversal. The record binds no content and no
+        # artifact (LED-1), so a declined context may still be freely edited or die.
+        class L2AttestationDecline < KairosMcp::Tools::BaseTool
+          include ::Synoptis::ToolHelpers
+
+          def name
+            'l2_attestation_decline'
+          end
+
+          def description
+            'Record that a proposed L2 context attestation was declined by the human. Appends a content-free decision record to the operational log (ACT-4). Does not constrain the context.'
+          end
+
+          def category
+            :attestation
+          end
+
+          def usecase_tags
+            %w[attestation decline constitutive l2 audit]
+          end
+
+          def related_tools
+            %w[l2_attestation_scan l2_attestation_commit]
+          end
+
+          def input_schema
+            {
+              type: 'object',
+              properties: {
+                subject: { type: 'string', description: 'The proposed L2 context that was declined, as a context:// URI.' }
+              },
+              required: %w[subject]
+            }
+          end
+
+          def call(arguments)
+            subject = arguments['subject']
+            unless subject
+              return text_content(JSON.pretty_generate({ status: 'error', message: 'subject is required' }))
+            end
+
+            constitutive_chain.append_decline(subject_id: subject)
+
+            text_content(JSON.pretty_generate({
+              status: 'declined',
+              subject: subject,
+              note: 'A content-free decline was logged. The context is unchanged and may still be edited or allowed to die.'
+            }))
+          rescue StandardError => e
+            text_content(JSON.pretty_generate({ status: 'error', message: e.message }))
+          end
+        end
+      end
+    end
+  end
+end

data/templates/skillsets/synoptis/tools/l2_attestation_scan.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module KairosMcp
+  module SkillSets
+    module Synoptis
+      module Tools
+        # ACT-5 (liveness) + ACT-2 (criterion): fire the selection criterion at a trigger
+        # point, surface judgment-bearing L2 contexts as PROPOSALS (no attestation, no
+        # obligation), and append one trigger record to the operational log so that
+        # "fired and surfaced N" is distinguishable from "never ran".
+        #
+        # Propose-only: this tool writes only telemetry (a trigger record). Nothing is
+        # attested here — approval happens in l2_attestation_commit (ACT-1).
+        class L2AttestationScan < KairosMcp::Tools::BaseTool
+          include ::Synoptis::ToolHelpers
+
+          def name
+            'l2_attestation_scan'
+          end
+
+          def description
+            'Propose judgment-bearing L2 contexts (handoff/decision/debrief) from a session for constitutive attestation. Surfaces proposals only; approve each via l2_attestation_commit. Logs a trigger record (ACT-5).'
+          end
+
+          def category
+            :attestation
+          end
+
+          def usecase_tags
+            %w[attestation propose constitutive l2 audit]
+          end
+
+          def related_tools
+            %w[l2_attestation_commit l2_attestation_decline]
+          end
+
+          def input_schema
+            {
+              type: 'object',
+              properties: {
+                session_id: { type: 'string', description: 'Session to scan (default: most recently modified session).' }
+              }
+            }
+          end
+
+          def call(arguments)
+            session_id = arguments['session_id'] || latest_session_id
+            unless session_id
+              return text_content(JSON.pretty_generate({ status: 'error', message: 'No session found to scan.' }))
+            end
+
+            proposals = proposal_criterion.propose(session_id: session_id)
+            constitutive_chain.append_trigger(surfaced_count: proposals.length)
+
+            text_content(JSON.pretty_generate({
+              status: 'proposed',
+              session_id: session_id,
+              surfaced_count: proposals.length,
+              proposals: proposals,
+              note: 'Approve each via l2_attestation_commit(subject:, approved: true), or record a decline via l2_attestation_decline(subject:).'
+            }))
+          rescue StandardError => e
+            text_content(JSON.pretty_generate({ status: 'error', message: e.message }))
+          end
+        end
+      end
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: kairos-chain
 version: !ruby/object:Gem::Version
-  version: 3.34.0
+  version: 3.35.0
 platform: ruby
 authors:
 - Masaomi Hatakeyama
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-03 00:00:00.000000000 Z
+date: 2026-07-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: minitest
@@ -624,6 +624,10 @@ files:
 - templates/skillsets/synoptis/lib/synoptis.rb
 - templates/skillsets/synoptis/lib/synoptis/attestation_engine.rb
 - templates/skillsets/synoptis/lib/synoptis/challenge_manager.rb
+- templates/skillsets/synoptis/lib/synoptis/constitutive/attestation_chain.rb
+- templates/skillsets/synoptis/lib/synoptis/constitutive/content_attestation_entry.rb
+- templates/skillsets/synoptis/lib/synoptis/constitutive/proposal_criterion.rb
+- templates/skillsets/synoptis/lib/synoptis/constitutive/subject_ref.rb
 - templates/skillsets/synoptis/lib/synoptis/meeting_trust_adapter.rb
 - templates/skillsets/synoptis/lib/synoptis/proof_envelope.rb
 - templates/skillsets/synoptis/lib/synoptis/registry/file_registry.rb
@@ -637,6 +641,7 @@ files:
 - templates/skillsets/synoptis/lib/synoptis/trust_scorer.rb
 - templates/skillsets/synoptis/lib/synoptis/verifier.rb
 - templates/skillsets/synoptis/skillset.json
+- templates/skillsets/synoptis/test/test_l2_constitutive_slice1.rb
 - templates/skillsets/synoptis/test/test_synoptis.rb
 - templates/skillsets/synoptis/tools/attestation_issue.rb
 - templates/skillsets/synoptis/tools/attestation_list.rb
@@ -644,6 +649,9 @@ files:
 - templates/skillsets/synoptis/tools/attestation_verify.rb
 - templates/skillsets/synoptis/tools/challenge_create.rb
 - templates/skillsets/synoptis/tools/challenge_respond.rb
+- templates/skillsets/synoptis/tools/l2_attestation_commit.rb
+- templates/skillsets/synoptis/tools/l2_attestation_decline.rb
+- templates/skillsets/synoptis/tools/l2_attestation_scan.rb
 - templates/skillsets/synoptis/tools/trust_query.rb
 - templates/storage/embeddings/knowledge/.gitkeep
 - templates/storage/embeddings/skills/.gitkeep