kairos-chain 3.59.0 → 3.61.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 104bc21b4db1c6c438f5e18767df43571d318f5637a878e626f22433b3d46b69
-  data.tar.gz: 57edf1d45e47e26f444e794c5b1e7be1be1e01cbbbd7ed831201265f8bfc18c1
+  metadata.gz: d38191ff3e513822d6183bf4fee4c92e497148978eda3bda064a01b81d0bf95b
+  data.tar.gz: 97999aa9377a086ea092237ad53605fec24b9e01c9691e7c92c24b6329bd565e
 SHA512:
-  metadata.gz: 8c0e5a937839894abada8bf37ad6b226d1b5d357e4a08f2a7a50d0cfac6fbd2aa5fc0fc455729996ef090610e9a19bf7c4be3f368ded7bf44d7c86a7735e3d58
-  data.tar.gz: 490cdba379a4c395cfd704e7e4e96f4f8ee170225afb55d5f7f2c63adbe1f904e09e6b1f5bb4c856fe6b4a44b675e2e07f80ff79294c5f719cd6b5afa5c4088d
+  metadata.gz: eacfebd73445ea5e6a503bb34e8978a0a6c649d34a46810140a885f235e3933b01701d45921341b6771caa64c58f4dac61f51233d2741417e8b59be111196109
+  data.tar.gz: bffb450e4de67e1b3c179de5bd48b86d1d6d3c2bc8e69cd6878fd6d89b6e3346fae29b09cd5ef79ddbb12f16498e0f944da84af4a62b3a36eff0db05ea5b6d96

data/CHANGELOG.md

@@ -4,6 +4,94 @@ All notable changes to the `kairos-chain` gem will be documented in this file.
 
 This project follows [Semantic Versioning](https://semver.org/).
 
+## [3.61.0] - 2026-08-06
+
+### Fixed
+
+- **`multi_llm_review` (SkillSet 0.9.0) — a finding reaches the record whole, and the record
+  stops claiming what it cannot know.** A downstream instance measured, across four real rounds,
+  that 18 of 21 aggregated findings came back at exactly 201 bytes while `reviews[].raw_text` was
+  empty on every row and `raw_text_length` reported the real size. Three bounds were doing it: an
+  inclusive Range (`issue.strip[0..200]`, hence 201) in aggregation, the 500-character display
+  limit applied to the record as well as the prompt, and a serializer row that carried a reply's
+  length but never the reply. A fourth defect discarded a distinct finding on dedup collision
+  without saying so.
+
+  Findings are now bounded in **bytes** at `FINDING_RECORD_MAX_LEN = 8000` for the record, with
+  `DEFAULT_MAX_LEN = 500` still applied by every path taking a finding into a prompt. The dedup key
+  is unchanged at 80 characters — widening it would stop two reviewers describing one defect from
+  merging, which moves the finding count and the convergence denominator — but the surviving text
+  is no longer arbitrary: `issue` comes from a member whose severity equals the merged severity,
+  and distinct texts survive in `issue_variants` (capped at `MAX_ISSUE_VARIANTS = 8`, with
+  `issue_variants_omitted` naming what the cap dropped). Every row now carries `raw_text_excerpt`
+  unconditionally at 4096 bytes, and the reply itself in `raw_text` on request
+  (`include_raw_text`, 65536 bytes). Findings carried into a later round's prompt are sanitised and
+  folded to one line — a path that previously took reviewer text into a prompt with no sanitisation
+  at all.
+
+  **The two evidence fields are sanitised transcriptions, not verbatim records, and the tool
+  schemas now say so** rather than implying otherwise. The text is byte-clamped, NFKC-normalised,
+  stripped of invisible characters, tag-escaped, then byte-clamped again; normalisation rewrites
+  compatibility forms, the strip removes five of Unicode's eight mandatory line breaks, and the tag
+  escape collapses unbounded whitespace. No field states whether a stored text is the whole reply.
+  A completeness flag was implemented for exactly that purpose and then removed: three reviewers
+  measured it wrong in **both** directions — a 4,010-byte reply stored as 18 bytes reported
+  complete, and a reply whose every readable byte survived reported truncated. "Was anything
+  dropped" cannot be answered by byte counts taken around a pass that also rewrites, strips and
+  escapes. On delegated runs the pending-state record keeps each subprocess reply as it arrived; on
+  single-phase runs the returned payload is the only form there is, and the schema distinguishes
+  the two.
+
+  Six review rounds, four pre-flight falsifier passes and forty-plus mutations. Every defect in
+  this change was found by adversarial reading or by mutating the code in a copy outside the
+  repository; **none** by the test suite passing. Known and disclosed rather than closed: the
+  excerpt can store a word the reviewer did not write (normalisation cannot simply be dropped —
+  the delimiter pattern matches ASCII angle brackets, so a fullwidth `＜artifact＞` would pass
+  straight through an escape that no longer normalises, and the escape-without-normalise entry
+  point `stated_text` has been waiting on since R2 does not exist yet); the measured response
+  ceiling of 28.9 MB against a declared 14.4 MB; and thirteen sites that survive deletion with the
+  suite green.
+
+## [3.60.0] - 2026-08-05
+
+### Added
+
+- **`account_manager` (SkillSet 0.1.0) — a jurisdiction-neutral double-entry ledger for a
+  one-person business that is also a household cash book.** One person, two purses: the books must
+  separate for tax, but the money does not — the owner draws from the business and pays business
+  costs from a private card. Six tools (`am_entry`, `am_import`, `am_query`, `am_report`,
+  `am_receipt`, `am_close`), one ledger with two books, one currency, and a bookkeeper-persona
+  sub-agent that transcribes on the way in and reads figures on the way out but cannot post,
+  confirm, discard, close or bind evidence.
+
+  No country's rules appear in any code path. The chart of accounts, tax labels, fiscal year and
+  import profiles are configuration; adding a country means writing one YAML file. The loader has
+  one refusal with a closed list of causes, and a missing ledger configuration is refused rather
+  than substituted by the shipped example.
+
+  Three things carry the design. A **range** is one calendar month derived from the transaction
+  date, so ranges cannot overlap or leave a gap and the rules that would have policed that do not
+  exist. A **proposal** is not a figure: imported rows and transcriptions are visible, counted by
+  no report, and become postings only by an explicit operator call. The **annual close posts, then
+  seals** — it credits each book's own retained earnings dated the fiscal year's last day, then
+  seals every month of that year, and that entry is the one posting permitted into a
+  period-closed (never sealed) range, because refusing it would make the annual close unreachable
+  in ordinary month-by-month use.
+
+  Design review did not converge over three rounds, so the design was implemented rather than
+  argued further; two implementation review rounds followed. Round 1 found a ledger that lost
+  records — an acknowledged posting absent from disk, because each tool cached its own store and
+  saved a stale snapshot over it — plus a refusal idiom that never executed
+  (`def m(id) = h[id] or raise X` parses as `(def …) or raise`), a closing entry that credited the
+  wrong book, and a year sealed as year zero from `'abc'.to_i`. Twenty-seven of its twenty-eight
+  blocking findings are fixed, and three independent reviewers verified the fixes in round 2.
+  Round 2's own findings are recorded and open: twelve are missing test coverage rather than
+  defects, and the remainder sit at configuration edges. Known and unfixed: there is no locking,
+  so the store is safe for one operator on one machine and not beyond it.
+
+  Not auto-installed — `account_manager` is not in `CORE_SKILLSETS`, so it ships in the gem and is
+  installed explicitly, like `project_manager`.
+
 ## [3.59.0] - 2026-08-05
 
 ### Added

data/lib/kairos_mcp/version.rb

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

data/templates/skillsets/account_manager/config/accounts.yml

@@ -0,0 +1,115 @@
+# account_manager — the whole jurisdiction surface, and a worked example of it.
+#
+# This file is a TEMPLATE, not a chart to use. Copy it to
+# .kairos/accounts/<ledger>/config.yml and edit it; the copy is what the tools
+# read, and this one is the fallback so a fresh instance is not dead on
+# arrival. It is deliberately not any country's chart: shipping one would put
+# a jurisdiction in the package by the same route that putting one in the code
+# would (INV-AM-6).
+#
+# Every key below is read by the loader. Nothing else is.
+
+# ISO 4217. XTS is the code reserved for testing — change it before you post
+# anything, because a currency cannot change once postings exist.
+currency: XTS
+
+# One ledger, two books. A household-only ledger is this same file with one
+# book, crossing: none, and tax_labels empty.
+books:
+  - business
+  - private
+
+# How a posting that crosses books is completed so each book still balances
+# alone (INV-AM-2). One account per book, or `none` to refuse crossings.
+crossing:
+  business: owner_account
+  private: business_claim
+
+fiscal_year_start_month: 1
+
+# Both must exist below with type equity. The loader refuses otherwise.
+retained_earnings_account: retained_earnings
+prior_period_adjustment_account: prior_period_adjustment
+
+# `cash: true` marks an account money actually sits in — bank, cash, card.
+# Reconciliation needs it, and so does the refusal of a settlement date on a
+# posting where nothing moved (INV-AM-10).
+chart_of_accounts:
+  - id: cash
+    name: Cash on hand
+    type: asset
+    cash: true
+  - id: bank
+    name: Business bank account
+    type: asset
+    cash: true
+  - id: private_card
+    name: Private credit card
+    type: liability
+    cash: true
+  - id: business_claim
+    name: Claim on the business (private book's side of a crossing)
+    type: asset
+  - id: receivable
+    name: Money owed to the business
+    type: asset
+  - id: payable
+    name: Money the business owes
+    type: liability
+  - id: owner_account
+    name: Owner's account — draws and contributions
+    type: equity
+  - id: retained_earnings
+    name: Retained earnings
+    type: equity
+  - id: prior_period_adjustment
+    name: Prior-period adjustment
+    type: equity
+  - id: income_services
+    name: Services rendered
+    type: income
+    default_tax_label: standard
+  - id: expense_supplies
+    name: Supplies and materials
+    type: expense
+    default_tax_label: standard
+  - id: expense_household
+    name: Household spending
+    type: expense
+
+# Opaque labels. No tool derives a tax amount from one; reports group by them
+# and stop there (INV-AM-8).
+tax_labels:
+  - standard
+  - exempt
+
+# One profile per source. The name is part of every key the profile produces,
+# so two sources numbering their bookings from 1 do not collide (INV-AM-9).
+import_profiles:
+  - name: example_bank
+    account: bank
+    book: business
+    columns:
+      transaction_date: Date
+      settlement_date: Booked
+      description: Text
+      amount: Amount
+      reference: Ref
+    # Which CSV column carries the source's own booking reference. Set it to
+    # nothing (omit the key) for a source with no identifier: its rows are then
+    # keyed by batch and position, and every re-import is reported as one.
+    reference_field: Ref
+    # positive_is_debit: a positive amount is money arriving in `account`.
+    sign: positive_is_debit
+
+  # Dictated lines and transcribed receipts arrive under a profile with no
+  # identifier, so a line dictated twice is proposed twice and the operator
+  # sees both.
+  - name: dictated
+    account: cash
+    book: private
+    columns:
+      transaction_date: date
+      description: description
+      amount: amount
+    sign: positive_is_debit

data/templates/skillsets/account_manager/knowledge/account_manager_guide/account_manager_guide.md

@@ -0,0 +1,200 @@
+---
+name: account_manager_guide
+description: How the account_manager ledger holds together — what a posting is, what a close freezes, why a sealed year is corrected in equity, and which decisions were made in code because prose could not settle them.
+version: 0.1.0
+layer: L1
+author: Masaomi Hatakeyama
+created: 2026-08-05
+---
+
+# account_manager — the working guide
+
+This is the knowledge an operator or an agent needs to use the ledger correctly and to change it
+without breaking it. It is not the design draft: the draft carries five defects this
+implementation fixes, and where they differ, this file and the code are right.
+
+## 1. What the system is
+
+A double-entry ledger for one person with two purses — a sole proprietorship whose owner also buys
+groceries. The books must separate for tax; the money does not separate at all. The owner draws
+from the business and pays business costs from a private card, and a design that models these as
+two unrelated datasets forces the owner to reconcile by hand, which is the work the tool exists to
+remove.
+
+It is not a tax filing engine and it knows no country's rules. It produces the figures and the
+evidence a filing needs; a human or an accountant files.
+
+## 2. The four record types, and which ones are figures
+
+| Record | Counted by a report? | Can it change? |
+|---|---|---|
+| **posting** | yes, always | only while its month is open |
+| **proposal** | never | until decided; a discard can be undone |
+| **closing record** | no — it *freezes* figures | append-only; a re-open appends, it does not erase |
+| **evidence** | no | never removed in v0.1; there is no delete command |
+
+The line between proposal and posting is the system's one real boundary. Everything inferential —
+reading an amount off a photograph, parsing a typed sentence, guessing an account, proposing that
+two rows are one transaction — happens on the proposal side, where it costs a correction. Only an
+explicit operator call moves a proposal across.
+
+## 3. Ranges, and why there is no range table
+
+A **range** is one calendar month of transaction dates. It is derived from the date, not declared:
+
+```
+transaction_date 2026-03-14 ──▶ range "2026-03"
+```
+
+Because ranges are derived, they cannot overlap and cannot leave a gap, so the refusals that would
+have policed those conditions do not exist. The design draft declared ranges as spans and then had
+to forbid overlaps — which made the annual close, written as closing a *year* span, permanently
+refused after any monthly close. Deriving the range deletes the rule and the defect together.
+
+A range is in one of three states, folded from the append-only closing log:
+
+```
+open ──close──▶ closed ──reopen──▶ open
+                   │
+                   └──seal (annual close)──▶ sealed   [terminal]
+```
+
+## 4. The two dates
+
+| | transaction date | settlement date |
+|---|---|---|
+| Means | the day it happened | the day money moved |
+| Places the posting in a range | **yes, alone** | never |
+| Used by P&L and balance sheet | yes | never |
+| Used by reconciliation | no | **only this** |
+| Absent when | never | no money moved |
+
+Three reviewers independently named the ambiguity between these two the worst defect in the design.
+The rule is one sentence: transaction date decides membership, settlement date decides
+reconciliation, and neither ever does the other's job.
+
+A posting for which no money moved carries **no** settlement date, and the tool refuses one. It can
+tell because the chart marks bank, cash and card accounts with `cash: true`. Without that flag the
+refusal would be unimplementable — which is what the design draft left it as.
+
+## 5. Crossing between books
+
+Give the ledger two lines that cross the books and it stores four:
+
+```
+"toner 42.30, business expense, paid on the private card"
+
+  you give:   Dr expense_supplies  42.30  [business]
+              Cr private_card      42.30  [private]
+
+  it stores:  Dr expense_supplies  42.30  [business]
+              Cr owner_account     42.30  [business]   ← added
+              Dr business_claim    42.30  [private]    ← added
+              Cr private_card      42.30  [private]
+
+  business balances alone.  private balances alone.
+```
+
+The pair is configuration (`crossing:`), and a ledger for an entity that must account separately
+sets `crossing: none` and gets a refusal instead.
+
+**The order matters and is load-bearing**: the posting is checked for overall balance *first*, and
+crossed *second*. A crossing redistributes a residue between books; it must never absorb one. If it
+ran first, a posting simply wrong by ten would land as a crossing of ten and the balance invariant
+would hold vacuously. (This was found by a test, not by reading.)
+
+## 6. The annual close
+
+```
+annual_close(2026)
+   │
+   ├─ 1. post the closing entry, dated 2026-12-31
+   │       every income and expense balance ──▶ retained_earnings
+   │       (this is the ONE posting allowed into a period-closed range)
+   │
+   └─ 2. seal every month of the fiscal year
+           2026-01 … 2026-12  ──▶ sealed, terminal
+```
+
+Post first, seal second. Sealing first would leave the entry with nowhere to go.
+
+**Operator decision, 2026-08-05:** the closing entry may be posted into a month that is already
+period-closed, and the annual close is the only operation that may do this. In ordinary use every
+month is closed before the year is, so refusing would make the annual close unreachable — the exact
+defect this ordering exists to fix. The seal record captures each range's final figures, so the
+change is visible rather than hidden.
+
+Without the closing entry, year two's balance sheet is short by year one's result on the first day
+of January, and the balance sheet and the profit-and-loss stop agreeing.
+
+The profit-and-loss **excludes** closing entries. They transfer a result rather than produce one,
+and counting them would make every closed year read as zero.
+
+## 7. Correcting an error
+
+| When the error is found | What to do |
+|---|---|
+| Month still open | Edit the posting in place |
+| Month closed, year open | Re-open the month, edit, close it again. The superseded closing record stays |
+| Year sealed | One **new** posting in an open month, against the prior-period-adjustment account |
+
+The sealed-year correction never touches an income or expense account, and the tool refuses one
+that tries. Those balances are already inside retained earnings; restating them would drop last
+year's error into this year's profit — the precise outcome the correction exists to prevent. One
+side is `prior_period_adjustment` (type `equity`); the other is the balance-sheet account that was
+actually misstated — the bank, a payable. No money moves, so there is no settlement date.
+
+## 8. Import keys
+
+A key is the pair **(profile, reference)**, never the reference alone. Two banks both numbering
+their bookings from 1 would otherwise collide and the second bank's row would be taken for the
+first's.
+
+- A re-import whose key is present and whose content **matches** → reported as already present.
+- A re-import whose key is present and whose content **differs** → reported as *changed*, with both
+  rows, and nothing is written. A bank revising a provisional amount must not leave the stale
+  figure standing because the tool recognised the key and looked no further.
+- A source with no reference field → keyed by batch and position, and every re-import is reported
+  as undeduplicable. A line dictated twice is proposed twice, on purpose.
+- A discarded proposal is **kept**, which is what stops the next re-import proposing it again, and
+  the discard can be undone.
+
+## 9. Configuration is the jurisdiction
+
+No tool's code holds an account name, a tax rate or a country's rule. Adding a country means
+writing one YAML file. A household-only setup is the same file with one book, `crossing: none` and
+no tax labels.
+
+The loader has exactly one refusal, with a closed list of causes: an account removed or retyped
+while postings reference it; a required named account missing or wrongly typed; a currency changed
+while postings exist; an import profile naming a column it does not map. It reports every cause at
+once. Renaming an account is always safe — the chart is editable in use, and a close stores the
+chart it was taken against, so editing never restates a closed period.
+
+## 10. What is deliberately absent
+
+- **More than one currency.** With it went conversion, rates, revaluation and every foreign
+  account. A foreign payment is recorded at what the account was charged; the original amount is a
+  note nothing parses. Multi-currency is a separate design against a ledger that already works.
+- **Value-added-tax derivation.** A registered entity needs the split at posting time, because
+  input tax is a balance-sheet claim and the expense must be recorded net. Registration is a
+  redesign. Labels here are opaque: reports group by them and stop.
+- **Deleting evidence,** and with it any retention setting. A tool that cannot delete cannot delete
+  wrongly.
+- **A "cash movement" report.** Reconciliation covers the need; the scope list named a report no
+  tool ever produced.
+- **A second ledger.** Only the addressing is built.
+
+## 11. Open questions, carried
+
+1. How opening balances are represented — an ordinary posting in a month later closed, or a record
+   type of their own. The spreadsheet migration makes this concrete.
+2. Whether closing-record detection should anchor each record's hash on the attestation chain.
+   Records carry a hash today; nothing external verifies the sequence.
+3. Whether the private book should be excluded from report output by default, so a business report
+   cannot carry household lines into an accountant's hands.
+4. Whether the store should keep an edit history for open-range postings. Today an open-range edit
+   overwrites, so the correction history exists only for months that were closed and re-opened.
+5. Whether a posting may have more than one settlement line. Reconciliation currently assumes not.
+6. Whether a ledger migrated mid-year should mark its first annual close as covering a partial
+   year, so a ten-month result is not read as a twelve-month one.