kairos-chain 3.42.0 → 3.42.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 07f782a3ef998bf91435a2e35cde051338c6f1c2fa8f2e037fbba4427c400ccf
-  data.tar.gz: 8cd549860f69e91fa94bf50a41121cb3b7625686f2438c2c665c83192f081f27
+  metadata.gz: 45fd1079aa951da3ac40d0dcd9763e02c2a15413753d5452dab4fc07e928a3cb
+  data.tar.gz: 93e3969307c08b26782c81804c9b5b10c475407e4770962a04ec29ab227a7951
 SHA512:
-  metadata.gz: e1ec23c12c08cff2ce324b34715d8eedd0277863a4e561b439c7161bd6e1b08eb10936c36db603ba621544e424953fe24247fe553917d3d4fcb6e844867d7f42
-  data.tar.gz: 738519ef9bc54544c058f59661d08288b22d60904527dbfb7f99f501f89b35d1a80c095b2b5090750f9aff69d592acc46357fe4069064302db344659b68b5642
+  metadata.gz: e0d95027c4457cb89a1dee063b3637dc568fce57735e2be211119ace92d684b42451b03b176887202bc2eb797d71cb49af9e3ca49f0e0e9e00689c88ff74c177
+  data.tar.gz: fd1ac48f63e671ce7df974bab3efd35e2f3af8b626aeba655f56d3bffa933903d269f3d5775ae877203f9ef3050c66c5a3d5cbf69811ec113b9f5235b35d6574

data/CHANGELOG.md

@@ -4,6 +4,49 @@ All notable changes to the `kairos-chain` gem will be documented in this file.
 
 This project follows [Semantic Versioning](https://semver.org/).
 
+## [3.42.2] - 2026-07-14
+
+### Knowledge — loop_engineering_patterns §B: Model/Effort budget allocation
+
+Extended the `loop_engineering_patterns` L1 entry (0.3 → 0.4) with a §B
+design-craft note distilled from Anthropic's *Model and Effort in Claude Code*
+post:
+
+- Model (intelligence ceiling) and effort (per-request thoroughness) are
+  distinct levers; raise model when logic/knowledge is the wall, raise effort
+  when the loop skips steps.
+- Because a loop compounds turns, uniform high effort multiplies latency —
+  concentrate high effort on the verify/judgment/decision gates, keep mechanical
+  dispatch turns low.
+- The lever is the *orchestrator's*; a worker in a separate process (hermes body
+  subprocess, `agent`-skillset step) carries its own config and is unaffected.
+- KairosChain delta: the non-bypassable gates (Prop 10 consent/audit floor,
+  INV-5 layer guard, verdict track) are where effort must not be cut — a stop
+  there is an irreversible Kairos moment (Prop 5), not a throughput step.
+
+Added the `effort-allocation` tag and a "high/low effort for a long run?"
+entry-point line. No code or behavior change.
+
+## [3.42.1] - 2026-07-14
+
+### Fixed — SectionWriter auto-chunk completeness & duplicate tail
+
+Two follow-ups to the v3.42.0 auto-chunk on output-uncapped providers
+(e.g. the `claude_code` CLI):
+
+- **Completeness.** v3.42.0 added a per-chunk "rewrite ONLY these paragraphs"
+  bound to avoid a trailing duplicate. On `claude_code` that bound backfired —
+  the model under-produced and dropped the section tail, leaving long sections
+  incomplete. Removed the bound.
+- **Duplicate tail (provider-agnostic).** Some providers "finish the section"
+  from the first chunk; the remaining passes then appended duplicate content.
+  `SectionWriter` now stops chunking once the assembled output already covers
+  ~the whole source (`section_complete_fraction`, default 0.85). Providers that
+  rewrite each chunk faithfully (e.g. API adapters, where `max_tokens` is
+  honoured) never trip this and still run every chunk. Net: a single clean,
+  complete section on both provider kinds. `chunks` in the result now reports
+  the number of passes actually run.
+
 ## [3.42.0] - 2026-07-14
 
 ### Fixed / Improved — agent SkillSet self-drive on long document sections

data/lib/kairos_mcp/version.rb

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

data/templates/knowledge/loop_engineering_patterns/loop_engineering_patterns.md

@@ -1,8 +1,8 @@
 ---
 name: loop_engineering_patterns
 description: Use before designing or classifying an agent loop in KairosChain — to pick a loop type, apply loop-design craft, and place each loop at the right layer under the Prop 10 floor. Claude Code's four loop types + design principles, extended with the governance constraint Anthropic omits.
-version: "0.3"
-tags: [loops, agent, autonomy, taxonomy, layer-placement, provenance]
+version: "0.4"
+tags: [loops, agent, autonomy, taxonomy, layer-placement, provenance, effort-allocation]
 ---
 
 # Loop Engineering Patterns
@@ -14,6 +14,7 @@ Open *before* designing or classifying an agent loop — not a runtime tool:
 - New agent loop / autonomous cycle → pick a §A type, apply §B craft, then place it via §C.
 - "Which layer owns this loop?" (harness vs gem/SkillSet, plus the cross-cutting L0 governance floor) → §C table + the L0 note below it.
 - Strengthening the `agent` OODA loop (self-verification, semantic stop) → §B + §C evaluator/verifier notes.
+- "High/low effort for a long run?" → §B budget-allocation note (concentrate effort on §C's non-bypassable gates).
 - Explaining why KairosChain's autonomous mode keeps human checkpoints → §C Prop 10 floor.
 - Not for: skill lifecycle/maturation → [[agent_skill_evolution_guide]]; general layer rules → [[layer_placement_guide]].
 
@@ -29,6 +30,8 @@ Micro (small) and macro (broad) loops compose; match loop complexity to problem
 ## B. Design craft (universal — adopt as-is)
 Output quality tracks the surrounding harness, not the model alone. Keep the codebase clean so the loop follows existing patterns. **Encode verification as a skill with quantitative checks** so the loop measures its own work. Keep docs accessible/current. **Use a second, independent agent for review** (fresh context, separate session/model). Set explicit success/stop criteria and max-turn caps to bound cost; script deterministic steps instead of re-reasoning them; monitor token spend.
 
+**Allocate reasoning budget by phase, not uniformly.** Model and effort are distinct levers ([Model and Effort in Claude Code](https://claude.com/blog/claude-model-and-effort-level-in-claude-code), Anthropic, 2026): model sets the intelligence ceiling — raise it when logic or knowledge is the wall; effort sets per-request thoroughness (files read, tests run, verification passes) — raise it when the loop skips steps, not when it lacks intelligence. Because a loop compounds turns, uniform high effort multiplies latency across every cycle: concentrate high effort on the verify / judgment / decision gates and keep mechanical dispatch turns low. Note this is the *orchestrator's* lever — it governs how carefully the loop monitors, verifies, and decides; it does not raise the quality of a worker running in a separate process (e.g. a hermes body subprocess or an `agent`-skillset step), which carries its own model/effort config. In KairosChain the non-bypassable gates — the Prop 10 consent/audit floor, the INV-5 layer guard, the verdict track — are exactly where effort must not be cut, since a stop there is an irreversible Kairos moment (§C, Prop 5), not a throughput step.
+
 ## C. KairosChain reading (layer placement + the floor Anthropic omits)
 The four types are harness-framed (`/goal`, `/loop`, `/schedule`, `/usage`, auto mode are Claude Code mechanisms). KairosChain already implements most of the substance across layers — so the work is mostly *placement*, not adoption; one item is still design-stage (flagged in the table):
 

data/templates/skillsets/document_authoring/lib/document_authoring/section_writer.rb

@@ -23,20 +23,27 @@ module KairosMcp
           # paragraph boundaries and generate each chunk in its own pass, appending the
           # results. Short contexts stay a single pass (chunks == [context_text]).
           chunks = split_context(context_text, chunk_target)
+          source_chars = context_text.to_s.gsub(/\s+/, '').length
+          complete_at = (source_chars * complete_fraction).ceil
 
           total_units = 0
           total_chars = 0
+          chunks_written = 0
           chunks.each_with_index do |chunk, idx|
             first = idx.zero?
+            # Provider-agnostic de-duplication: some output-uncapped providers (e.g. the
+            # claude_code CLI) "finish the section" from the first chunk. Once the assembled
+            # output already covers ~the whole source, stop — further passes would only
+            # append duplicate content. Providers that rewrite each chunk faithfully never
+            # trip this (their per-chunk output tracks per-chunk input), so all chunks run.
+            break if !first && total_chars >= complete_at
+
+            # Continuation chunks must not repeat the section heading. (A stronger
+            # "rewrite only these paragraphs" bound was tried but backfired on the
+            # claude_code CLI — it then under-produced and dropped the section tail.)
             chunk_instructions =
-              if chunks.length > 1
-                # Bound EVERY chunk to its own paragraphs. Without this, providers that
-                # "finish the section" (e.g. claude_code) regenerate the whole section from
-                # the first chunk, so later chunks duplicate content. Continuation chunks
-                # also must not repeat the heading.
-                notes = [bounded_note(language)]
-                notes << continuation_note(language) unless first
-                "#{instructions}\n\n#{notes.join("\n")}"
+              if chunks.length > 1 && !first
+                "#{instructions}\n\n#{continuation_note(language)}"
               else
                 instructions
               end
@@ -49,6 +56,7 @@ module KairosMcp
             write_chunk(output_file, gen['content'], first ? append_mode : true)
             total_units += count_units(gen['content'], language)
             total_chars += gen['content'].gsub(/\s+/, '').length
+            chunks_written += 1
           end
 
           {
@@ -60,7 +68,7 @@ module KairosMcp
             # non-whitespace char count so callers never size output from a bogus metric.
             'word_count' => total_units,
             'char_count' => total_chars,
-            'chunks' => chunks.length
+            'chunks' => chunks_written
           }
         end
 
@@ -167,24 +175,20 @@ module KairosMcp
         end
 
         # Auto-chunk threshold. Sized so each pass is small enough that output-uncapped
-        # providers (e.g. claude_code CLI) emit the whole chunk without stopping early —
+        # providers (e.g. claude_code CLI) emit a full section without stopping early —
         # empirically a larger single pass truncates, while ~3000-char passes complete.
-        # The bounded_note keeps chunks from overlapping. Overridable via config.
+        # On such providers the first chunk may "finish the section", so the output can
+        # carry a trailing duplicate fragment; completeness is favoured over that cosmetic
+        # cost. API providers (with max_tokens honoured) produce a clean single section.
+        # Overridable via config.
         def chunk_target
           (@config['section_chunk_target_chars'] || 3000).to_i
         end
 
-        # Appended to EVERY chunk (when chunking) so the model rewrites only the paragraphs
-        # it was given and does not "finish the section" — which would make chunks overlap.
-        def bounded_note(language)
-          if %w[ja zh ko].include?(language.to_s)
-            '重要: 以下に与えた段落だけを推敲せよ。節はいくつかに分けて処理される。' \
-              '与えられていない段落を書き足したり、節の続きをここで完成させたりしてはならない。'
-          else
-            'IMPORTANT: Rewrite ONLY the paragraphs given below. The section is processed ' \
-              'in several passes; do NOT add paragraphs that are not in this input or ' \
-              'finish the rest of the section here.'
-          end
+        # Fraction of the source (by non-whitespace chars) at which the assembled output is
+        # considered to already cover the whole section, so remaining chunks are skipped.
+        def complete_fraction
+          (@config['section_complete_fraction'] || 0.85).to_f
         end
 
         # Appended to a continuation chunk's instructions so the model does not repeat the

data/templates/skillsets/document_authoring/test/test_document_authoring.rb

@@ -468,6 +468,40 @@ assert("T18g: append_mode applies only to the first chunk; later chunks append")
   content.start_with?('PRE') && content.include?("c1\n\nc2\n\nc3")
 end
 
+assert("T18h: stops chunking once output already covers the whole source (no duplicate tail)") do
+  caller = MockCallerTool.new
+  calls = 0
+  caller.define_singleton_method(:invoke_tool) do |tool_name, arguments = {}, context: nil|
+    calls += 1
+    # First pass "finishes the section" (output >= source); a later pass would be a dup.
+    body = calls == 1 ? ('な' * 500) : 'DUPLICATE'
+    [{ text: JSON.generate({ 'status' => 'ok', 'response' => { 'content' => body }, 'snapshot' => {} }) }]
+  end
+  writer = SW.new(caller, { 'section_chunk_target_chars' => 100 })
+  ctx = (1..5).map { ('あ' * 80) }.join("\n\n") # ~400 non-ws source chars, would be 5 chunks
+  out = File.join(TMPDIR, 'earlystop.md')
+  r = writer.write(section_name: 's', instructions: 'i', context_text: ctx,
+                   output_file: out, max_words: 100, language: 'ja', append_mode: false)
+  # chunk1 output (500) >= 0.85 * 400 = 340 → stop after the first pass
+  r['chunks'] == 1 && calls == 1 && !File.read(out).include?('DUPLICATE')
+end
+
+assert("T18i: faithful per-chunk provider still runs all chunks (no premature stop)") do
+  caller = MockCallerTool.new
+  calls = 0
+  caller.define_singleton_method(:invoke_tool) do |tool_name, arguments = {}, context: nil|
+    calls += 1
+    [{ text: JSON.generate({ 'status' => 'ok', 'response' => { 'content' => "p#{calls}" }, 'snapshot' => {} }) }]
+  end
+  writer = SW.new(caller, { 'section_chunk_target_chars' => 100 })
+  ctx = (1..4).map { ('あ' * 80) }.join("\n\n")
+  out = File.join(TMPDIR, 'faithful.md')
+  r = writer.write(section_name: 's', instructions: 'i', context_text: ctx,
+                   output_file: out, max_words: 100, language: 'ja', append_mode: false)
+  # short per-chunk output never reaches the completeness threshold → all chunks run
+  r['chunks'] > 1 && calls == r['chunks'] && File.read(out).include?("p#{calls}")
+end
+
 assert("T18d: max_tokens respects config ceiling override") do
   caller = MockCallerTool.new
   captured = {}

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: kairos-chain
 version: !ruby/object:Gem::Version
-  version: 3.42.0
+  version: 3.42.2
 platform: ruby
 authors:
 - Masaomi Hatakeyama