kairos-chain 3.71.0 → 3.74.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b8cf3acf9bb95eb62a4fc78d85359540a9089973819fce152278a962007e6faa
-  data.tar.gz: bcffe011916e72faecc52aeecc68743a7ef25a96a108b509d9cd80531d04b542
+  metadata.gz: 730e325cdf2caf9ce68964d25d379511f5b1080aa86b86378c928a06156fc567
+  data.tar.gz: 3c7fd4cc597b1fefd8403bd976786eba4e3e02c6665c2097d35940e243d6a2dd
 SHA512:
-  metadata.gz: 759b4cdfe1cc4d6031708d669820994f090d6bf946191d7b3823b9b1f8a3969f9e11193222e8103e065ae20eea290e218638913262ff83225c6250f5f12640b9
-  data.tar.gz: 8823dd97245c068d475951c908bcdd77807c43b7b0ce6705680d9413ad52bee608bd246c2a97214df6e0253869f87187cce9aaa92f647289a7a1068156c9a01b
+  metadata.gz: a78cf0336f37b5107f0991ca1f0e88a3cfeb911f1a998d1ffb5763e071d1ba9ffa88fde11d92fc2eaca9eeb0ffc948718e3bfa1f65ed0f87fa1adf3f1c36d40a
+  data.tar.gz: da3b0b85ec1518e1e07f4bd4199761128006fe57db205059b36f3145db7cd5ef8f51b9d95f24faa82a05756507244700d6fbe3655d3672d11b80e9b7eb4a697d

data/CHANGELOG.md

@@ -4,6 +4,226 @@ All notable changes to the `kairos-chain` gem will be documented in this file.
 
 This project follows [Semantic Versioning](https://semver.org/).
 
+## [3.74.0] - 2026-08-18
+
+### Fixed
+
+- **Every guard in `project_manager` sat on the reading side, and a value JSON
+  cannot represent walked past all of them and wedged the store.** Generation ran
+  before `File.write`, so the file survived and `@data` did not: the bad value
+  stayed in memory and every later save in the process failed identically. The
+  store went on silently accepting nothing while each caller saw only its own
+  error, and the digest counted items that were never written. Measured on a
+  probe: a title carrying a lone surrogate raised, and so did the next perfectly
+  ordinary write; 0 items on disk against 2 in memory. `Store#save` now treats
+  generation, `mkdir`, write and rename as one unit, and any failure restores
+  `@committed` — the last state that reached disk, held in memory and advanced
+  only after a write completes — before re-raising. Restoring from memory rather
+  than by re-reading the file matters because a `store.json` that had itself
+  become unreadable would otherwise leave the rollback with nothing to restore.
+  What rollback discards is stated rather than glossed: everything in memory since
+  the last successful save, including an edit written straight into a record
+  handed out by `items` or `fetch_*`. Records returned by the store are for
+  reading; go through a mutator to keep a change.
+- **`pm.yml` is the one file an operator is invited to edit and `skillset upgrade`
+  never repairs it, so a bad edit was permanent — and it returned an error from
+  every pm tool at once.** `YAML.safe_load_file` is strict: 5 of 5 ordinary edits
+  raise (tab indent, unclosed quote, bare date, `&anchor`/`*alias`, `:symbol`),
+  and the raise landed one level above every guard the tools carry. The read now
+  falls back to the defaults — but falling back is only half a fix, because
+  defaults wearing the operator's settings are worse than the outage they replace.
+  The reason is kept in `pm_config_error`, `pm_digest` and `pm_record` carry it as
+  `config_error`, and the secretary is told to say it **before** the buckets and
+  to state that the report was built on defaults and is not comparable to a
+  configured one. A document that parses but is not a mapping is reported the same
+  way, `false` included; only `nil` means "no settings", which an empty file, a
+  newline-only file and a comment-only file all produce (3 of 3 measured).
+  `ToolHelpers#pm_digest` carried the same hole and had no caller, so it is
+  deleted rather than guarded.
+- **Two rounds of review, and the second round's fixes came from findings the
+  first round's fixes created.** Round 1 returned 1 APPROVE of 3 seats with six
+  blocking findings; all six were checked against the code before acting and all
+  six were real. Round 2 returned 2 of 3. One correction runs the other way: a
+  finding claimed an operator's shortened record ttl would be silently replaced,
+  but the shipped value and the built-in default are the same 100 years, so only
+  an operator who changed it is affected — the gap was real, the stated magnitude
+  was not. Two residuals are shipped open, both unreachable from any of the five
+  tool entry points and both recorded at the call site as well as in the store:
+  rollback detaches previously returned records (0 of 3 holders are harmed today),
+  and `JSON.parse(@committed)` is assumed to succeed (tool arguments arrive parsed
+  from JSON, so no object with its own `to_json` can enter).
+- **The mutant set grew from 8 to 14 and one of its own results was thrown out.**
+  Mutant 18-d first read as a survivor; the mutation was malformed, splitting the
+  `begin` block while leaving the original `rescue` attached to the second half,
+  so the mutant still rolled back and was equivalent rather than surviving.
+  Rewritten as a whole-method replacement it is killed. 14 of 14 killed, including
+  the two a reviewer predicted would survive. Suite: 78 runs, 259 assertions.
+  Still uncovered, and recorded as such: `secretary.md` is prose, so deleting the
+  paragraph it gained passes all 14 mutants — as would deleting any other rule in
+  that file, since nothing in this SkillSet inspects what the secretary produces.
+
+## [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.74.0"
   CHANGELOG_URL = "https://github.com/masaomi/KairosChain_2026/blob/main/CHANGELOG.md"
 end

data/templates/skillsets/project_manager/lib/project_manager/store.rb

@@ -35,6 +35,12 @@ module ProjectManager
     def initialize(path: nil)
       @path = path || default_path
       @data = load_data
+      # The last state known to be writable, kept as generated JSON. A rollback
+      # restores from this rather than re-reading the file, so it cannot fail the
+      # way the write it undoes did — a store.json that has meanwhile become
+      # unreadable would otherwise leave the rollback with nothing to restore and
+      # the offending value still in place.
+      @committed = JSON.generate(@data)
     end
 
     def default_path
@@ -315,11 +321,50 @@ module ProjectManager
       { 'version' => 1, 'projects' => {}, 'items' => {}, 'attention_days' => {} }
     end
 
+    # The whole write is one unit — generation, mkdir, write, rename. Any failure
+    # restores the last state that reached disk and re-raises, so a caller reports
+    # a refused write instead of losing one. Before this, a value JSON cannot
+    # represent stayed in @data and every later save failed identically, so the
+    # store silently accepted nothing while each caller saw only its own error.
+    #
+    # Rollback discards everything in memory since the last successful save.
+    # Store's own mutators each end in save, so that is normally just the
+    # offending write — but `items`, `projects` and the fetch_* methods hand out
+    # the live hashes, and an edit written straight into one of those is discarded
+    # too. Records returned by this class are for reading; go through a mutator to
+    # keep a change.
+    #
+    # The guard belongs here rather than in apply_item_attrs: every writer passes
+    # through save, and an attribute-level check would leave project names,
+    # provenance entries and attention records unguarded.
+    #
+    # Two residuals, both raised in review and both left open because no current
+    # caller can reach them. Read these before adding a caller that does.
+    #
+    # 1. Rollback rebuilds @data, so a record handed out earlier by items,
+    #    projects or fetch_* is detached from the store afterwards: reads from it
+    #    go stale and writes into it reach nothing. Of the three tools that hold
+    #    a returned record, only pm_record holds one across a save, and it uses
+    #    the id string alone. A caller that keeps a record and edits it after a
+    #    refused write would need this to restore in place instead.
+    # 2. JSON.parse(@committed) is assumed to succeed. It does, because
+    #    @committed is only ever assigned the output of a generate that already
+    #    round-tripped, and tool arguments arrive parsed from JSON so no object
+    #    with its own to_json can enter. A value reaching @data from Ruby rather
+    #    than from a tool could break that.
     def save
-      FileUtils.mkdir_p(File.dirname(@path))
-      tmp = "#{@path}.tmp"
-      File.write(tmp, JSON.pretty_generate(@data))
-      File.rename(tmp, @path)
+      json = nil
+      begin
+        json = JSON.pretty_generate(@data)
+        FileUtils.mkdir_p(File.dirname(@path))
+        tmp = "#{@path}.tmp"
+        File.write(tmp, json)
+        File.rename(tmp, @path)
+      rescue StandardError
+        @data = JSON.parse(@committed)
+        raise
+      end
+      @committed = json
     end
   end
 end

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

@@ -8,15 +8,54 @@ module ProjectManager
       @_pm_store ||= Store.new
     end
 
+    # Named so a test can point the reader at a file it wrote, and still drive
+    # the real pm_config rather than a stand-in for it.
+    def pm_config_path
+      File.expand_path('../../config/pm.yml', __dir__)
+    end
+
+    # pm.yml is the one file an operator is invited to edit, and `skillset
+    # upgrade` deliberately never overwrites it, so a bad edit is permanent
+    # rather than transient. YAML.safe_load_file is strict — a tab indent, an
+    # unclosed quote, a bare date, an &anchor and a :symbol each raise, five of
+    # five measured — and the raise happened here, one level above every guard
+    # the tools carry. One stray character took every pm tool out at once.
+    #
+    # A document that parses but is not a mapping is the same failure in another
+    # shape: it breaks the first caller that subscripts it. It is coerced here
+    # rather than at each call site, because a call-site guard is re-acquired by
+    # the next caller and pm_record's was never written.
+    #
+    # Falling back is not the whole fix. Defaults wearing the operator's settings
+    # are worse than the outage they replace, so the reason is kept and
+    # pm_config_error hands it to any caller that reports to a human.
     def pm_config
-      @_pm_config ||= begin
-        path = File.expand_path('../../config/pm.yml', __dir__)
-        File.exist?(path) ? (YAML.safe_load_file(path) || {}) : {}
-      end
+      return @_pm_config if defined?(@_pm_config)
+
+      @_pm_config_error = nil
+      loaded = File.exist?(pm_config_path) ? YAML.safe_load_file(pm_config_path) : {}
+      @_pm_config =
+        if loaded.is_a?(Hash)
+          loaded
+        else
+          # An empty file — no bytes, blank lines, or comments only — parses to
+          # nil, and that is the operator saying "no settings". Every other
+          # non-mapping is a mistake and is named, `false` included: it is an
+          # affirmative value that happens not to be a Hash, so treating it as
+          # emptiness would hand back defaults with nothing said.
+          @_pm_config_error = "pm.yml is #{loaded.class}, expected a mapping" unless loaded.nil?
+          {}
+        end
+    rescue StandardError => e
+      @_pm_config_error = "#{e.class}: #{e.message.to_s.lines.first.to_s.strip}"
+      @_pm_config = {}
     end
 
-    def pm_digest
-      Digest.new(pm_store, pm_config['digest'])
+    # nil when pm.yml was usable, or absent — absence is the documented default,
+    # not a failure. Otherwise, why the file was ignored.
+    def pm_config_error
+      pm_config
+      @_pm_config_error
     end
   end
 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/agents/secretary.md

@@ -51,6 +51,13 @@ thresholds cannot be compared with yesterday's. If the operator asks for a diffe
 use it, and say in the report which value you used and that this report is not comparable to the
 default one.
 
+The digest reads those defaults from `pm.yml`, and that file can be unreadable — a stray tab, an
+unclosed quote, a bare date. When it is, the digest still answers, on built-in defaults rather than
+the operator's settings, and returns a `config_error` field saying why. **If that field is present,
+say so first, before the buckets**, and name the reason verbatim: this report was built on defaults,
+so it is not comparable to one built on the configured thresholds, and the settings file needs
+repair. Reporting the buckets without it presents defaults as though the operator had chosen them.
+
 The digest computes its buckets independently, so one item can appear in several of them. Report
 each item exactly once, in the first bucket that claims it, in this fixed order:
 

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
+          }
+        ]
+      }
+    ]
+  }
+}