kairos-chain 3.71.0 → 3.73.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b8cf3acf9bb95eb62a4fc78d85359540a9089973819fce152278a962007e6faa
-  data.tar.gz: bcffe011916e72faecc52aeecc68743a7ef25a96a108b509d9cd80531d04b542
+  metadata.gz: 4344b2bf968bbb0b650c672522c8abdee9ae34daea4f06899e60cfaf815fa489
+  data.tar.gz: e2a99d727e1ca7d404ecdd0945c29e9964220b1ec8aaca8be44f46c55b9a5e77
 SHA512:
-  metadata.gz: 759b4cdfe1cc4d6031708d669820994f090d6bf946191d7b3823b9b1f8a3969f9e11193222e8103e065ae20eea290e218638913262ff83225c6250f5f12640b9
-  data.tar.gz: 8823dd97245c068d475951c908bcdd77807c43b7b0ce6705680d9413ad52bee608bd246c2a97214df6e0253869f87187cce9aaa92f647289a7a1068156c9a01b
+  metadata.gz: 9d47b320473eb188dcc9f57655f11cd152ce0cee6e160c714396ebcd508156a5696c0c0db8eeb7ace61956cfc5e61467507a051ce6d200552d95ebe3a7f9ebf1
+  data.tar.gz: e38d3d417efb9be7c9e0274d9aca36ba7c1fd062f7ef0ecfc204536f86c99a9bbbbf025a52ee31525caab67b94a3dba88c41fcd3ab9d49313d6a609b10a2e0f8

data/CHANGELOG.md

@@ -4,6 +4,168 @@ All notable changes to the `kairos-chain` gem will be documented in this file.
 
 This project follows [Semantic Versioning](https://semver.org/).
 
+## [3.73.0] - 2026-08-17
+
+### Fixed
+
+- **Round 2 of the same review returned 0 APPROVE of 3 valid seats and thirteen
+  more blocking findings, three of them saying round 1's fixes did not hold. The
+  response was to subtract.** Two of the six guards round 1 added are removed
+  rather than repaired. The `-o` output path is deleted: guarding it by comparing
+  resolved paths failed three ways — a case-only difference on a case-insensitive
+  filesystem, a hardlink, and any read input the check did not enumerate, which
+  included every L2 context and `config/pm.yml` — and each failure destroyed the
+  memo while the run printed that nothing had been written to it. The page now
+  always goes to `<data dir>/log/pm_l2_report.html`, beside the data directory so a
+  relocated instance still finds it, and under a name the operator's own `.gitignore`
+  already knows how to handle. The carried `exclude` is
+  also removed: carrying it was itself a round-1 fix, and since an exclude term is
+  a substring of document names while an inferred term is usually the item's own
+  record name, it suppressed the item's own primary record. It still applies to
+  the authored terms it was written beside, and the row says when it was not
+  applied.
+- **The anti-flood cap bounds the row, not only each term.** Twelve terms each
+  under the twenty-document cap unioned to 124 of 1179 documents for one item, and
+  a note of the ordinary shape reached 23. A row over the cap is refused rather
+  than truncated, because truncation is silent and moves `last_activity` and the
+  headline figures with it; the row reports how many its terms reached.
+- **Paths are derived from the script's own location** instead of by appending a
+  literal `.kairos`, which had reported a populated instance as empty at exit 0 on
+  every session of a relocated data directory. **A row with no comparison names
+  which of five things is missing**, separating an unparseable L2 date from an
+  unparseable memo marker, because they blame different files and collapsing them
+  stated a false fact for the second time. **Nested store shapes are checked**, not
+  only their absence: a `projects` or `items` value that was truthy and not an
+  object reached `.values()` and raised.
+- **The test file is rewritten, not extended.** An audit applied 65 one-line
+  mutations to the round-1 suite and 36 survived — the whole of `main`'s wiring,
+  all cross-item aggregation, and the impossible-date guard the suite was named
+  for, whose fixture built a second document matching the same term so the valid
+  date sorted last and the impossible one never reached the parse point. 53 cases
+  now, and of the 30 mutations that map to a reported finding 29 are killed; the
+  survivor is equivalent. Four habits are stated in the file: exercise guards
+  through `main` in a subprocess, check that a fixture cannot satisfy its own
+  assertion, build several rows when testing aggregation, and assert messages and
+  exit codes by content. Nothing runs the suite automatically — `rake test`
+  collects Ruby files only.
+- **Accepted rather than fixed, and recorded where they happen.** A context
+  declaring a parseable but absurd date such as `9999-12-31` flattens the other lag
+  bars, which is what bars relative to the widest lag mean. And what the report
+  says still depends on which `python3` resolves, since `date.fromisoformat`
+  accepts basic format from 3.11. Separately, two stale `.pyc` files sit inside one
+  installed SkillSet from earlier runs, so its `content_hash` differs from a clean
+  tree's; nothing here removes them.
+- Live data after the change: 28 of 28 items comparable, 19 with L2 more recent,
+  median 29 days, widest 81 — identical to before, so nothing the subtraction
+  removed was carrying coverage.
+
+## [3.72.0] - 2026-08-17
+
+**Built and never published.** Its contents ship in 3.73.0, which carries the second round of fixes to the same feature; the entry is kept because the commits it describes are in the history.
+
+### Fixed
+
+- **Six defects in the session-start report below, all found by a pre-release
+  multi-LLM review and all demonstrated by running code rather than reasoning
+  about it.** The review returned 0 APPROVE of 3 counted seats. Two of the five
+  invariants the change declared were false as stated, which is why they are
+  listed here rather than deferred.
+  - *The read-only promise was prose.* `open(out, "w")` accepted any path, so
+    `-o <memo>` truncated `store.json` while the run printed that nothing had been
+    written to it. The output path is now refused if it resolves to the memo or
+    the mapping, via `realpath`, so a symlink cannot walk around it.
+  - *A read-only report changed the SkillSet's chain-recorded hash.*
+    `exec_module` writes bytecode, and `scripts/__pycache__/l2_scan.cpython-310.pyc`
+    landed inside the SkillSet directory — inside `Skillset#all_file_hashes`, hence
+    inside `content_hash`, hence inside what `skillset_manager` records as
+    `skillset_event` and verifies with `raise SecurityError`. The recorded hash was
+    a function of the local CPython build and of whether the report had run.
+    `sys.dont_write_bytecode` is now set around the import.
+  - *The anti-flood guard was capped on one tier only.* A document's name is
+    `name:` or `title:` or its basename, and 321 of 1177 contexts take it from a
+    free-text `title:`. One context titled `Review` made `review` a search term
+    reaching 351 records; titled `Context`, all 1178. Both tiers are now capped at
+    twenty documents, which costs nothing measurable: of 1125 distinct names none
+    reaches more than 20, and the two items that use inference return the same 2
+    and 17 records.
+  - *A non-string `touched_at` or `due` crashed the report.* `pm_item` writes both
+    through with no check beyond a JSON type and this SkillSet's own Ruby suite
+    writes the integer `20260701` to each, so slicing them raised `TypeError` — the
+    defect `lib/project_manager/parsed_time.rb` exists to prevent, re-acquired at a
+    fifth call site because the reader is in another language. Permanent once
+    triggered, since the value stays in the store.
+  - *One shape-valid impossible date took the whole run down.* `l2_scan` validates
+    that a declared date looks like a date, not that it exists, so `2026-02-30`
+    reached `date.fromisoformat` outside the `try` — the guard covered one end of
+    the interval only. Both ends now go through it.
+  - *An unreadable memo marker was reported as unreadable records.* An item with
+    seventeen perfectly datable records was described as "records found, none
+    datable", and it silently left the denominator: 28/28 matched with median 29
+    became 27/28 with median 28.5. The three causes — no terms, undatable records,
+    unreadable marker — are now counted and worded apart.
+- **Smaller fixes from the same review.** The authored `exclude` is carried into
+  the inference fallback rather than dropped, so a distinction the operator wrote
+  down is not undone by the fallback. A mapping whose `include` is a string rather
+  than a list no longer expands to single-character terms (one of which matched
+  1177 of 1177 documents, displayed as the operator's own authored mapping).
+  `store['projects']`, `mapping['items']` and dependency entries missing `kind` or
+  `ref` no longer raise. `--open` falls back to `xdg-open` and survives neither
+  binary existing, since the gem ships to Linux. The hook reads `KAIROS_DATA_DIR`
+  before `$CLAUDE_PROJECT_DIR/.kairos`, because the data directory is relocatable
+  and a relocated instance got a hook pointing at nothing. The hook no longer
+  discards stderr or forces a zero exit: doing both made every failure
+  indistinguishable from a session where nothing had drifted. Operator-facing text
+  no longer renders a Python list repr, and `--quiet` documents the two lines it
+  prints instead of three.
+- **`test/test_pm_l2_report.py`, 30 cases, 27 of them red against the version that
+  shipped before them.** Of those 27, nine exercise the old behaviour directly and
+  eighteen fail because the guard function did not exist — that distinction is
+  recorded rather than counted as thirty demonstrations. The remaining three cover
+  HTML escaping and a degenerate render, which were already correct and are held
+  as regression guards. The suite drives the real `l2_scan.match` rather than a
+  copy of it, so the two views cannot disagree about what a term matched.
+
+### Added
+
+- **The `project_manager` SkillSet (v0.6.0) reports the memo-versus-L2 drift once
+  per session, and no longer needs a human to author search terms first.** The
+  memo lags the context store and the lag is invisible from whichever side is
+  being read: on the development instance, 19 of 28 items have L2 activity more
+  recent than their last memo touch, median 29 days, widest 81. Derivation could
+  already measure that, but only when someone remembered to run it and only for
+  items a human had authored terms for. Two read-only additions.
+  `scripts/pm_l2_report.py` renders the comparison as one HTML page, and
+  `plugin/hooks.json` declares it as a `SessionStart` hook so the harness runs it
+  without anyone deciding to. `SessionStart` and not `Stop`: this is not a gate,
+  it decides nothing, and only Stop-family payloads carry the once-per-turn brake
+  `kairos_hook_projector`'s gates need. Delivery is by projection — `skillset
+  install` changes no host settings, and the MCP handshake projects on every host
+  start, so no core change was needed to reach the host. Whether the newly
+  written hook fires on that same start or the following one depends on when the
+  host reads its settings relative to the handshake; that ordering is not
+  measured, and `kairos-plugin-project` run by hand settles it. `skillset upgrade
+  --apply` is not a substitute: it projects only when it actually upgrades
+  something, and `project_manager` is not in the core set it upgrades. Measured
+  at 0.18s over 1172 contexts; the script writes exactly one file, its own
+  output, and the memo's hash is unchanged across a run.
+- **Search terms fall back to inference from the item's own title and notes**
+  when the authored mapping has no entry for an item, or its entry matched
+  nothing — so no item goes unreported and L2 is never asked to be relabelled.
+  Inference cannot replace the mapping and does not try: 43 of 53 hand-authored
+  terms appear nowhere in any item's title or notes, having been written from
+  knowledge of the work. What it can do is refuse to flood. Only a token that is
+  itself the name of an existing L2 document, or a compound identifier reaching
+  at most twenty documents, is accepted; a bare English word is refused however
+  rare it looks. Accepting bare words returned 51 and 82 records for the two
+  items that have almost none, because a defect is described with words like
+  store, write, config and yaml, and those match hundreds of unrelated names as
+  substrings. Refusing them, the same two return 2 and 17, and all 28 items
+  become comparable. The cost is misses — inference alone found 87 records across
+  the 24 mapped items where the mapping found 296 — and the trade is deliberate:
+  a miss shows up as a smaller count, a spurious record does not show up at all.
+  Unchanged by this release: nothing writes to the memo (derivation v0.12 §1),
+  and neither the digest's shape nor the secretary's grant moved.
+
 ## [3.71.0] - 2026-08-17
 
 ### Added

data/lib/kairos_mcp/version.rb

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

data/templates/skillsets/project_manager/plugin/SKILL.md

@@ -62,6 +62,94 @@ Prefer the sub-agent for "what needs attention?", at session start, and for sche
 - **Layer discipline.** These tools never write L0 or L1.
 - **World-event dependencies are operator-cleared.** The system never auto-resolves them.
 
+## The session-start L2 comparison
+
+`scripts/pm_l2_report.py` compares the memo against the L2 context store and writes one HTML page,
+to `<data dir>/log/pm_l2_report.html`. `plugin/hooks.json` declares it as a `SessionStart` hook.
+
+**Read-only by having no aim, not by checking one.** There is no output-path argument, so nothing
+can point a write at the memo, the mapping, an L2 context, or `config/pm.yml`. An earlier version
+took `-o` and guarded it by comparing resolved paths; that guard failed three ways — a case-only
+difference on a case-insensitive filesystem, a hardlink, and any read input it did not know about —
+and each failure destroyed the memo while the run printed that nothing had been written to it.
+Deleting the argument closed all three. `sys.dont_write_bytecode` is set around the derivation
+import for the same reason a second guard was not added: a `.pyc` inside the SkillSet sits inside
+`Skillset#all_file_hashes` and therefore inside `content_hash`, the value recorded on chain.
+
+**Paths come from this file's own location**, three levels up from `scripts/`, not from the name
+`.kairos`. `l2_scan` derives its own by appending that literal, which reported a populated instance
+as empty on every session whenever the data dir had been relocated, so its four path constants are
+re-pointed after import.
+
+**Nothing is trusted to have a type.** `pm_item` writes `due` and `touched_at` through with no check
+beyond a JSON type, and this SkillSet's own Ruby suite writes the integer `20260701` to both. Dates
+are parsed in exactly one function, which both ends of every interval go through: `l2_scan`
+validates that a declared date *looks* like a date, never that it exists, so one context declaring
+`2026-02-30` used to take the whole unattended run down.
+
+Delivery is by **projection**, not by install, because install alone changes no host settings:
+
+```
+kairos-chain skillset install project_manager   files land; the host's settings are untouched
+next start of the host                          the MCP handshake projects; the hook is written
+```
+
+Whether the hook then fires on that same start or the following one depends on when the host reads
+its settings relative to the handshake; observed firing on the following one. `kairos-plugin-project`
+run by hand settles it, and `skillset upgrade --apply` is not a substitute — it projects only when
+it actually upgrades something, and this SkillSet is not in the core set it upgrades.
+
+### Where search terms come from
+
+The authored mapping first. When it has no entry for an item, or its entry matched nothing, terms
+are inferred from that item's own title and notes, so no item goes unreported and L2 is never asked
+to be relabelled. Inference cannot replace the mapping and does not try: 43 of 53 hand-authored
+terms appear nowhere in any item's title or notes, having been written from knowledge of the work.
+
+What it can do is refuse to flood, and it took three measurements to get that right, each from a
+reviewer running the code:
+
+| what was accepted | what happened | rule now |
+|---|---|---|
+| bare English words | 51 and 82 records for two items that have nearly none, because a defect is described with words like store, write, config and yaml | only a document name or a compound identifier containing an underscore |
+| an uncapped document-name tier | a context titled `Review` made `review` a term reaching 351 records; titled `Context`, all 1178 | both tiers capped at twenty documents per term |
+| a cap per term but not per row | twelve terms each under the cap unioned to 124 of 1179 documents; an ordinary note reached 23 | the row's whole union is capped too, and inference is **refused** rather than truncated |
+
+Refused and not truncated, because truncation is silent and moves `last_activity` and the headline
+figures with it. A refused row says its terms were too broad and how many they reached, and the page
+shows the terms — a row claiming no term could be built while not showing what it tried is a claim
+the operator cannot check where it is wrong.
+
+**An authored `exclude` stops at the authored terms.** Carrying it into inference was itself a fix
+in an earlier round, and it traded one wrong answer for another: an exclude term is a substring of
+document names, and an inferred term is usually the item's own record name, so carrying it
+suppressed the item's own primary record. The row says so rather than dropping it silently.
+
+The cost of all this is misses — across the 24 mapped items, inference alone found 87 records where
+the mapping found 296 — and the trade is deliberate: a miss shows up as a smaller count, a spurious
+record does not show up at all.
+
+### Five reasons, not one
+
+A row with no comparison names which side is missing: no usable terms, terms too broad, records
+carrying no date, an L2 date that cannot be parsed, or a memo marker that cannot be parsed. The last
+two are separate sentences because they blame different files. Collapsing them produced a false
+statement twice — first an item with seventeen datable records reported as having none, then a memo
+blamed for a date that L2 had written wrong — and each time the item also left the denominator, so
+the headline figures shrank without saying so.
+
+### Tests
+
+`test/test_pm_l2_report.py`. The bar is mutation, not redness against an older commit: breaking a
+guard by one line must make the suite red. An audit of an earlier version applied 65 one-line
+mutations and 36 survived, so guards are now exercised through `main()` in a subprocess, fixtures
+are checked not to satisfy their own assertion, aggregation is tested with several items, and
+messages and exit codes are asserted by content. Of the 30 mutations that map to a reported finding,
+29 are killed; the survivor is equivalent (deleting the absent-derivation branch leaves the generic
+handler producing the same message, exit code and absence of a traceback).
+
+Nothing runs this suite automatically — `rake test` collects Ruby files only.
+
 ## Relation to instruction modes
 
 The tools carry no disposition and depend on no particular instruction mode. This SkillSet does

data/templates/skillsets/project_manager/plugin/hooks.json

@@ -0,0 +1,46 @@
+{
+  "_comment": [
+    "Hooks this SkillSet contributes to the host harness. The plugin projector",
+    "merges this into the host's settings under a _projected_by tag, so",
+    "re-projection replaces only what it put there and leaves hand-written",
+    "hooks alone. Installing the SkillSet and re-projecting is the whole",
+    "delivery -- nobody edits settings.json by hand.",
+    "",
+    "SessionStart, not Stop. A Stop-family gate can brake itself once per turn",
+    "via stop_hook_active, which is why kairos_hook_projector restricts its",
+    "gates to Stop and SubagentStop; this is not a gate. It reports, it decides",
+    "nothing, and it runs once when a session opens.",
+    "",
+    "KAIROS_DATA_DIR before $CLAUDE_PROJECT_DIR/.kairos. The data directory is",
+    "relocatable -- KairosMcp.resolve_data_dir reads that variable, and",
+    "PluginProjector takes data_dir separately from project_root with a guard",
+    "that exists because the two are expected to differ. Hardcoding the second",
+    "form meant that on a relocated instance the hook pointed at nothing and,",
+    "with stderr discarded, said nothing about it.",
+    "",
+    "No 2>/dev/null and no || true. Suppressing both turned every failure --",
+    "absent script, unreadable store, a stored timestamp that is not a string --",
+    "into exit 0 with empty output, which is indistinguishable from a session",
+    "where nothing had drifted. The script now handles its own absences and",
+    "reports each in one line on stdout, so what is left uncaught is a genuine",
+    "defect and should be visible. Measured at 0.18s over 1172 contexts.",
+    "",
+    "The command does not begin with kairos-, so projection prints one",
+    "non-standard-command warning. That is the projector asking a human to look,",
+    "and this is what it looks like: a read-only report that refuses an output",
+    "path resolving to the memo, and writes only its own HTML."
+  ],
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 \"${KAIROS_DATA_DIR:-$CLAUDE_PROJECT_DIR/.kairos}/skillsets/project_manager/scripts/pm_l2_report.py\" --quiet",
+            "timeout": 20
+          }
+        ]
+      }
+    ]
+  }
+}