@passioncode-ai/passioncode 0.2.14 → 0.2.16

package/payload/plugins/observatory-log/hooks/ask-why.py

@@ -1,5 +1,5 @@
 #!/usr/bin/env python3
-"""Turn a record_turn.py result into the Stop hook's structured output.
+"""Turn a record_turn.py result into the request for a `why`, delivered with the next prompt.
 
 Standard library only, and silent on anything unexpected: a hook that reports
 its own confusion as a failure teaches the operator to disable hooks.
@@ -9,43 +9,45 @@ cooperation, so the only thing left to ask for is the `why` — and asking is
 worth more than a veto that costs a turn. An absent `why` stays visible in the
 ledger as a proposed record with a null field, which is accountability without
 obstruction.
+
+**Once, where the model reads it.** This printed the ask as a Stop
+`systemMessage` after every changed turn: measured over fourteen days of one
+machine's transcripts, 3,593 asks for 34 answers. A Stop `systemMessage` is a
+notice for the person, never rendered into the model's input, and a session is
+ONE record revised per turn, so every ask after the first repeated the question.
+Now the recorder decides (`ask` is false once a record was asked about, and when
+the turn wrote its own rationale), and this hook leaves the ask in a private
+per-session file that `prompt-why.py` hands to the model as the next prompt's
+`additionalContext`, once. If that file cannot be written the ask falls back to
+the old Stop notice: an ask is never lost to a full disk.
 """
 from __future__ import annotations
 import json
+import os
+import re
 import sys
+import time
 
 OWNER = "agent:claude-code"
+#: A session id names a file, so it is held to a shape that cannot leave the directory.
+SESSION = re.compile(r"[A-Za-z0-9][A-Za-z0-9._-]{0,127}")
+#: An ask nobody collected — the session ended — is removed after this long.
+PRUNE_SECONDS = 7 * 86400
+#: A session's pending asks, newest kept: a record is asked about once, so more
+#: than a few undelivered ones means the session is gone, not busy.
+KEEP = 3
 
 
-def main() -> int:
-    try:
-        r = json.load(sys.stdin)
-    except Exception:
-        return 0
-    if not r.get("recorded"):
-        # A FAULT IS NOT A QUIET TURN. This returned 0 for every `recorded:
-        # false`, and the recorder's reasons are two different kinds: "nothing
-        # changed" is an answer about the work, while `IllegalTransition:
-        # observed -> proposed` is the recorder failing. Measured 2026-09-07:
-        # once `tools/corroborate.py` promoted a session's record, every later
-        # turn of that session raised that error and said nothing — roughly
-        # seventy-two turns in one session, and the only visible sign was a
-        # ledger row that had stopped moving.
-        #
-        # The recorder marks which kind it is; this only has to stop hiding it.
-        reason = r.get("reason") or ""
-        if not r.get("fault"):
-            return 0                   # nothing changed, not watched, or explained
-        print(json.dumps({"systemMessage":
-                          "Observatory could NOT record this turn: " + reason +
-                          "\n\nThe facts of this turn are not in the ledger. "
-                          "`store/raw/record-turn.json` holds the same reason, and "
-                          "`project-observatory full findings` raises it.",
-                          "suppressOutput": True}))
-        return 0
-    if r.get("hasWhy"):
-        return 0                                          # already explained
+def pending_dir() -> str:
+    """Where a session's undelivered ask waits; `prompt-why.py` computes the same."""
+    base = os.environ.get("XDG_STATE_HOME") or os.path.join(
+        os.path.expanduser("~"), ".local", "state")
+    return os.path.join(base, "project-observatory", "ask-why")
+
 
+def message(r: dict, at_stop: bool = False) -> str:
+    """The ask. `at_stop` words it for a Stop notice, which follows the turn it is
+    about, rather than for the next prompt, which comes after it."""
     mid = r.get("memoryId")
     rev = r.get("revision")
     project = r.get("project", "this project")
@@ -53,11 +55,11 @@ def main() -> int:
     plural = "" if files == 1 else "s"
     unpushed = r.get("unpushed") or 0
     extra = f", {unpushed} unpushed commit(s)" if unpushed else ""
-
-    message = (
-        f"Observatory recorded the facts of this turn in {project}: "
+    text = (
+        f"Observatory recorded the facts of {'this' if at_stop else 'your previous'} turn in {project}: "
         f"{files} file{plural} changed, +{r.get('insertions', 0)}/-{r.get('deletions', 0)}"
-        f"{extra}. Stored as {mid}@{rev}, state proposed, with no `why`.\n\n"
+        f"{extra}. Stored as {mid}@{rev}, state proposed, with no `why`."
+        + (" This record is asked about once." if r.get("ask") is True else "") + "\n\n"
         "The diff already says WHAT changed. Add WHY — one or two sentences a "
         "reader in six months could not reconstruct from the diff: the constraint "
         "that forced the shape, the alternative rejected, the trap avoided.\n\n"
@@ -66,6 +68,7 @@ def main() -> int:
         "If the change genuinely needs no explanation — a typo, a rename — say so "
         "and skip it. An empty `why` on a trivial edit is honest; an invented one "
         "is worse than nothing, because it will be read as true."
+        + ("" if at_stop else " Then answer the user's new message.")
     )
     # THE NUDGE AT THE MOMENT OF WORK. The agent is already inside this project;
     # rebuilding its graph or touching its note costs least right now. Thresholds
@@ -82,9 +85,111 @@ def main() -> int:
                           f"work changed what the project IS (modules, scope, "
                           f"stack), update the overview note too")
     if stale_bits:
-        message += ("\n\nWhile you are here — this project's recorded knowledge "
-                    "is behind its code:\n  - " + "\n  - ".join(stale_bits))
-    print(json.dumps({"systemMessage": message, "suppressOutput": True},
+        text += ("\n\nWhile you are here — this project's recorded knowledge "
+                 "is behind its code:\n  - " + "\n  - ".join(stale_bits))
+    return text
+
+
+def leave_for_next_prompt(session: str, r: dict, text: str) -> bool:
+    """Write the ask where `prompt-why.py` finds it. False when it could not be kept."""
+    if not isinstance(session, str) or not SESSION.fullmatch(session):
+        return False
+    try:
+        d = pending_dir()
+        os.makedirs(d, mode=0o700, exist_ok=True)
+        os.chmod(d, 0o700)
+        now = time.time()
+        for name in os.listdir(d):                  # sessions that never prompted again
+            p = os.path.join(d, name)
+            try:
+                if now - os.stat(p).st_mtime > PRUNE_SECONDS:
+                    os.unlink(p)
+            except OSError:
+                pass
+        path = os.path.join(d, session + ".json")
+        asks = []
+        try:
+            with open(path, encoding="utf-8") as fh:
+                asks = [a for a in (json.load(fh).get("asks") or []) if isinstance(a, dict)]
+        except (OSError, ValueError, AttributeError):
+            asks = []
+        asks = [a for a in asks if a.get("memoryId") != r.get("memoryId")]
+        entry = {"at": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime(now)),
+                 "memoryId": r.get("memoryId"), "revision": r.get("revision"),
+                 "context": text}
+        # Where `prompt-why.py` records the delivery: the engine's journal, named by
+        # the recorder. Only a file of that exact name is ever written there.
+        journal = r.get("journal")
+        if isinstance(journal, str) and os.path.basename(journal) == "why-asks.jsonl":
+            entry["journal"] = journal
+        asks.append(entry)
+        tmp = f"{path}.{os.getpid()}.tmp"
+        # Created owner-only by the umask, not by a raw `os.open`: this script runs
+        # from the plugin's own copy without the engine, so `osprivacy` (the one
+        # module allowed to pass open flags) is out of reach, and the hook is one
+        # single-threaded process, so the umask is its own.
+        mask = os.umask(0o077)
+        try:
+            with open(tmp, "w", encoding="utf-8") as fh:
+                json.dump({"asks": asks[-KEEP:]}, fh, ensure_ascii=False)
+        finally:
+            os.umask(mask)
+        os.chmod(tmp, 0o600)
+        os.replace(tmp, path)
+        return True
+    except Exception:                                                  # noqa: BLE001
+        return False
+
+
+def main() -> int:
+    try:
+        r = json.load(sys.stdin)
+    except Exception:
+        return 0
+    if not isinstance(r, dict):
+        return 0
+    if not r.get("recorded"):
+        # A FAULT IS NOT A QUIET TURN. This returned 0 for every `recorded:
+        # false`, and the recorder's reasons are two different kinds: "nothing
+        # changed" is an answer about the work, while `IllegalTransition:
+        # observed -> proposed` is the recorder failing. Measured 2026-09-07:
+        # once `tools/corroborate.py` promoted a session's record, every later
+        # turn of that session raised that error and said nothing — roughly
+        # seventy-two turns in one session, and the only visible sign was a
+        # ledger row that had stopped moving.
+        #
+        # The recorder marks which kind it is; this only has to stop hiding it.
+        # A fault stays a Stop notice: it is for the person, and it is urgent.
+        reason = r.get("reason") or ""
+        if not r.get("fault"):
+            return 0                   # nothing changed, not watched, or explained
+        print(json.dumps({"systemMessage":
+                          "Observatory could NOT record this turn: " + reason +
+                          "\n\nThe facts of this turn are not in the ledger. "
+                          "`store/raw/record-turn.json` holds the same reason, and "
+                          "`project-observatory full findings` raises it.",
+                          "suppressOutput": True}))
+        return 0
+    if r.get("hasWhy"):
+        return 0                                          # already explained
+    if r.get("rationale"):
+        return 0          # the turn wrote its rationale; the record links that file
+    if "ask" not in r:
+        # AN OLDER ENGINE, which decides nothing about asking: it would send this
+        # every changed turn, and an every-turn ask injected into the model's context
+        # is worse than the notice it replaces. So it gets the old Stop notice.
+        print(json.dumps({"systemMessage": message(r, at_stop=True), "suppressOutput": True},
+                         ensure_ascii=False))
+        return 0
+    if r.get("ask") is not True:
+        return 0          # this record was asked about already
+
+    text = message(r)
+    if leave_for_next_prompt(r.get("session"), r, text):
+        return 0
+    # THE OLD CHANNEL, as the fallback. A notice the model may not read is better
+    # than an ask that silently never happens.
+    print(json.dumps({"systemMessage": message(r, at_stop=True), "suppressOutput": True},
                      ensure_ascii=False))
     return 0
 

package/payload/plugins/observatory-log/hooks/hooks.json

@@ -1,5 +1,5 @@
 {
-  "description": "Optional Claude Code hooks: record changes in watched Git projects and request missing reasoning. SessionStart reports brief actionable context. Missing workspace, interpreter or watched project degrades quietly; hooks do not block a turn. Project names and paths stay in the private workspace.",
+  "description": "Optional Claude Code hooks: record changes in watched Git projects and request missing reasoning. SessionStart reports brief actionable context. Stop records the facts of a turn that changed something since the previous turn first, counting only what differs from the session's baseline (taken at SessionStart; files untracked before the session never count); then, within 2 seconds, it reads the last 4 MB of the session transcript once for this session's writing calls (Edit, Write, MultiEdit, NotebookEdit, and Bash writes through >, >>, tee or sed -i; failed calls, subagent calls and commands over 65,536 characters are skipped). It leaves a request for the why at most once per record, only when the turn changed tracked content, none while a revision's rationale link is still true (same repository, a regular file in the checkout with one hard link and no symbolic link, the exact heading line present once and the file unchanged or with only a new entry appended after it; any other edit asks again), and none when such a call targeted a decisions.md or an adr/ .md, .markdown or .txt file (outside vendored trees) with text carrying the entry's own heading (unique in the register) or, with no heading, most of its added lines, or wrote a decision: or stage: line into .task-pipeline/run.md. UserPromptSubmit hands that pending request to the model with the next prompt, once, within 4,000 characters, records the delivery, and prints nothing when none is pending. Missing workspace, interpreter or watched project degrades quietly; hooks do not block a turn or a prompt. Project names and paths stay in the private workspace.",
   "hooks": {
     "SessionStart": [
       {
@@ -26,6 +26,18 @@
           }
         ]
       }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "shell": "bash",
+            "command": "py=\"${OBSERVATORY_PYTHON:-}\"; [ -x \"$py\" ] || py=python3; \"$py\" \"${CLAUDE_PLUGIN_ROOT}/hooks/prompt-why.py\" 2>/dev/null; exit 0",
+            "timeout": 5
+          }
+        ]
+      }
     ]
   }
 }

package/payload/plugins/observatory-log/hooks/prompt-why.py

@@ -0,0 +1,180 @@
+#!/usr/bin/env python3
+"""Hand the model the request for a `why` that the Stop hook left for this session.
+
+A UserPromptSubmit hook, so it runs before EVERY prompt of every session, and the
+whole design is about that cost:
+
+- **Silent unless an ask is pending.** One `stat` of a per-session file and exit 0;
+  the file exists only after `ask-why.py` asked about a record, at most once per
+  record (`why_asks.py` in the engine).
+- **Once.** The file is taken by an atomic rename before it is read, so two prompts
+  cannot both deliver it, and it is deleted after.
+- **Never in the way of the prompt.** Every error — a payload that is not JSON, a
+  session id that is not a plain name, a torn file — is exit 0 with nothing on
+  stdout. It cannot block: it prints no `decision`, and it exits 0 on every path.
+- **Delivery is recorded.** For each ask handed over it appends
+  `{"event": "delivered"}` to the engine's journal (`store/raw/why-asks.jsonl`, the
+  path the recorder named), because the answer rate is measured on delivered asks: a
+  headless session that never sends a second prompt never receives its ask, and must
+  not count as having ignored it.
+- **Where the model reads it.** The ask goes out as
+  `hookSpecificOutput.additionalContext`, which Claude Code renders into the
+  model's input; the Stop `systemMessage` it replaces is a notice for the person
+  (`tests/test_ask_why_reach.py`).
+
+It holds no secret: the pending file carries the ask's text — a project id, a
+record id and a diff's size — and is written 0600 in a 0700 directory.
+Standard library only; it does not need the engine.
+"""
+from __future__ import annotations
+import calendar
+import json
+import os
+import re
+import sys
+import time
+
+SESSION = re.compile(r"[A-Za-z0-9][A-Za-z0-9._-]{0,127}")
+#: An ask older than this is about a turn too far back to explain well; it is dropped.
+STALE_SECONDS = 7 * 86400
+#: The context a prompt can be handed, at most. One ask is about a thousand characters.
+MAX_CHARS = 4000
+
+
+def pending_dir() -> str:
+    """The directory `ask-why.py` writes; the two must agree."""
+    base = os.environ.get("XDG_STATE_HOME") or os.path.join(
+        os.path.expanduser("~"), ".local", "state")
+    return os.path.join(base, "project-observatory", "ask-why")
+
+
+SEPARATOR = "\n\n---\n\n"
+
+
+def _put_back(path: str, asks: list) -> None:
+    """Return undelivered asks to the session's pending file, beside any the Stop hook
+    wrote meanwhile. Owner-only, like the file `ask-why.py` writes."""
+    try:
+        try:
+            with open(path, encoding="utf-8") as fh:
+                current = [a for a in (json.load(fh).get("asks") or []) if isinstance(a, dict)]
+        except (OSError, ValueError, AttributeError):
+            current = []
+        ids = {a.get("memoryId") for a in current}
+        merged = [a for a in asks if a.get("memoryId") not in ids] + current
+        tmp = f"{path}.{os.getpid()}.back"
+        mask = os.umask(0o077)
+        try:
+            with open(tmp, "w", encoding="utf-8") as fh:
+                json.dump({"asks": merged}, fh, ensure_ascii=False)
+        finally:
+            os.umask(mask)
+        os.replace(tmp, path)
+    except Exception:                                                  # noqa: BLE001
+        pass                          # an ask that is not put back stays pending, unasked
+
+
+def _record_delivery(ask: dict, session: str) -> None:
+    """Append a `delivered` row to the journal the recorder named. Never raises."""
+    journal = ask.get("journal")
+    if not isinstance(journal, str) or os.path.basename(journal) != "why-asks.jsonl" \
+            or os.path.islink(journal) or not os.path.isdir(os.path.dirname(journal) or "/nonexistent"):
+        return
+    row = {"at": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+           "memoryId": ask.get("memoryId"), "event": "delivered", "session": session}
+    if not isinstance(row["memoryId"], str):
+        return
+    try:
+        with open(journal, "a", encoding="utf-8") as fh:
+            fh.write(json.dumps(row, ensure_ascii=False) + "\n")
+    except OSError:
+        pass                    # an undelivered count is a floor, not a failed prompt
+
+
+def _prune(directory: str) -> None:
+    """Remove pending asks older than STALE_SECONDS: sessions that ended without a
+    further prompt. Run only after a delivery, so a quiet prompt stays one `stat`."""
+    try:
+        now = time.time()
+        for name in os.listdir(directory):
+            path = os.path.join(directory, name)
+            try:
+                if now - os.stat(path).st_mtime > STALE_SECONDS:
+                    os.unlink(path)
+            except OSError:
+                pass
+    except OSError:
+        pass
+
+
+def _fresh(stamp) -> bool:
+    try:
+        when = calendar.timegm(time.strptime(str(stamp), "%Y-%m-%dT%H:%M:%SZ"))
+    except (ValueError, OverflowError):
+        return True                                  # an odd stamp still delivers
+    return time.time() - when <= STALE_SECONDS
+
+
+def main() -> int:
+    try:
+        payload = json.load(sys.stdin)
+    except Exception:
+        return 0
+    session = payload.get("session_id") if isinstance(payload, dict) else None
+    if not isinstance(session, str) or not SESSION.fullmatch(session):
+        return 0
+    path = os.path.join(pending_dir(), session + ".json")
+    if not os.path.isfile(path):
+        return 0                                     # the common case: nothing pending
+    taking = f"{path}.taking-{os.getpid()}"
+    try:
+        os.replace(path, taking)                     # one prompt takes it, not two
+    except OSError:
+        return 0
+    try:
+        with open(taking, encoding="utf-8") as fh:
+            doc = json.load(fh)
+    except Exception:
+        doc = {}
+    finally:
+        try:
+            os.unlink(taking)
+        except OSError:
+            pass
+    _prune(os.path.dirname(path))
+    asks = doc.get("asks") if isinstance(doc, dict) else None
+    chosen = [a for a in (asks or [])
+              if isinstance(a, dict) and isinstance(a.get("context"), str)
+              and a["context"].strip() and _fresh(a.get("at"))]
+    if not chosen:
+        return 0
+    # THE CAP, honestly counted. Only asks that fit inside MAX_CHARS whole are handed
+    # over and marked delivered; the rest go back for the next prompt. The first ask
+    # always goes (cut at the cap if it alone is longer: its record id and the call
+    # to make come first).
+    sent, rest, used = [], [], 0
+    for a in chosen:
+        cost = len(a["context"]) + (len(SEPARATOR) if sent else 0)
+        if sent and used + cost > MAX_CHARS:
+            rest.append(a)
+            continue
+        sent.append(a)
+        used += cost
+    if rest:
+        _put_back(path, rest)
+    context = SEPARATOR.join(a["context"] for a in sent)[:MAX_CHARS]
+    for a in sent:
+        _record_delivery(a, session)
+    print(json.dumps({"hookSpecificOutput": {"hookEventName": "UserPromptSubmit",
+                                             "additionalContext": context}},
+                     ensure_ascii=False))
+    return 0
+
+
+if __name__ == "__main__":
+    try:
+        raise SystemExit(main())
+    except SystemExit:
+        raise
+    except Exception:
+        raise SystemExit(0)

package/payload/plugins/observatory-log/hooks/record-turn.sh

@@ -52,29 +52,45 @@ py="${OBSERVATORY_PYTHON:-$root/.venv/bin/python}"   # set by `full agent instal
 [ -x "$py" ] || py="$(command -v python3 2>/dev/null)"
 [ -n "$py" ] || exit 0                         # no interpreter: silent
 
-read_field() {                     # read_field <key>
+# ONE PARSE of the payload, not one interpreter start per field: four starts cost
+# 0.1-0.4 s of every turn's Stop before the recorder ran. A value holding a line
+# break is dropped rather than split across the fields that follow it.
+read_fields() {                    # stop_hook_active, cwd, session_id, transcript_path
   [ -n "$payload" ] || return 0
   printf '%s' "$payload" | "$py" -c '
 import json, sys
 try:
     d = json.load(sys.stdin)
 except Exception:
-    sys.exit(0)
-print(d.get(sys.argv[1]) or "")
-' "$1" 2>/dev/null
+    d = {}
+if not isinstance(d, dict):
+    d = {}
+for k in ("stop_hook_active", "cwd", "session_id", "transcript_path"):
+    v = d.get(k)
+    v = "" if v is None or v is False else str(v)
+    print("" if ("\n" in v or "\r" in v) else v)
+' 2>/dev/null
 }
+fields="$(read_fields)"
+active=""; cwd=""; session=""; transcript=""
+{ IFS= read -r active; IFS= read -r cwd; IFS= read -r session; IFS= read -r transcript; } <<EOF_FIELDS || true
+$fields
+EOF_FIELDS
+
+[ "$active" = "True" ] && exit 0
+[ "$active" = "true" ] && exit 0
+
+[ -n "$cwd" ] || cwd="${CLAUDE_PROJECT_DIR:-$PWD}"
+# `transcript` is the session's own transcript, so a register another session is
+# editing in the same checkout does not silence this session's ask. Passed only to a
+# recorder that reads it: an older engine's argument parser would refuse the flag
+# and record nothing.
+extra=()
+if [ -n "$transcript" ] && [ -f "$transcript" ] && grep -q -- '--transcript' "$root/tools/record_turn.py" 2>/dev/null; then
+  extra=(--transcript "$transcript")
+fi
 
-
-
-
-[ "$(read_field stop_hook_active)" = "True" ] && exit 0
-[ "$(read_field stop_hook_active)" = "true" ] && exit 0
-
-cwd="$(read_field cwd)"; [ -n "$cwd" ] || cwd="${CLAUDE_PROJECT_DIR:-$PWD}"
-session="$(read_field session_id)"
-
-
-result="$("$py" "$root/tools/record_turn.py" --cwd "$cwd" --session-id "$session" 2>/dev/null)"
+result="$("$py" "$root/tools/record_turn.py" --cwd "$cwd" --session-id "$session" ${extra[@]+"${extra[@]}"} 2>/dev/null)"
 [ -n "$result" ] || exit 0
 
 printf '%s' "$result" | "$py" "${CLAUDE_PLUGIN_ROOT:-$(dirname "$0")/..}/hooks/ask-why.py" 2>/dev/null

package/payload/plugins/observatory-log/hooks/session-start.sh

@@ -88,7 +88,8 @@ if [ -f "$root/tools/maintain.py" ]; then
 else
   # The bridge for engines from before 0.17.0, which carry no updater of their own:
   # once a day, check; when a newer stable release exists and the person has not turned
-  # automatic updates off (`updates.auto` false), install it with `full update --apply`.
+  # automatic updates off (the `auto-update` file says `off`, or `updates.auto` is false),
+  # install it with `full update --apply`.
   po=""
   [ -n "$venv" ] && [ -x "$venv/bin/project-observatory" ] && po="$venv/bin/project-observatory"
   [ -n "$po" ] || po="$(command -v project-observatory 2>/dev/null)"
@@ -96,10 +97,15 @@ else
     detach "$stamps/update-bridge.log" /bin/bash -c '
       po="$1"; py="$2"
       home="${OBSERVATORY_FULL_HOME:-${OBSERVATORY_HOME:-$HOME/.local/share/project-observatory-full}}"
-      off="$("$py" -c "import json,sys
-try: d=json.load(open(sys.argv[1]))
+      # The switch (LC-16): the file `auto-update` in the home, where only `off` is off;
+      # without one, `updates.auto: false` in settings.json, as those releases wrote it.
+      off="$("$py" -c "import json,os,sys
+f=os.path.join(sys.argv[1], \"auto-update\")
+if os.path.isfile(f) and not os.path.islink(f):
+    print(1 if open(f, errors=\"replace\").read(64).strip().lower() == \"off\" else 0); sys.exit()
+try: d=json.load(open(os.path.join(sys.argv[1], \"config\", \"settings.json\")))
 except Exception: d={}
-print(1 if (d.get(\"updates\") or {}).get(\"auto\") is False else 0)" "$home/config/settings.json" 2>/dev/null)"
+print(1 if (d.get(\"updates\") or {}).get(\"auto\") is False else 0)" "$home" 2>/dev/null)"
       [ "$off" = "1" ] && { echo "$(date -u +%FT%TZ) automatic updates are off"; exit 0; }
       "$po" full update --check >/dev/null 2>&1; rc=$?
       echo "$(date -u +%FT%TZ) check exit $rc"

package/payload/plugins/observatory-log/skills/explaining-changes/SKILL.md

@@ -15,7 +15,7 @@ description: >-
   decision with different evidence.
 license: AGPL-3.0-only OR LicenseRef-PassionCode-Commercial
 metadata:
-  version: "0.18.0"
+  version: "0.26.0"
 compatibility: >-
   Requires an initialized full Project Observatory installation to persist
   records. Uses its MCP server when available in the current host; the bundled
@@ -48,14 +48,25 @@ and nothing in the ledger can tell it from a measured one.
 
 ## Recording it
 
-The Observatory's Stop hook has already stored the facts as a `proposed` record
-and printed its id. Correct that record rather than creating a second one:
+The Observatory's Stop hook has already stored the facts as a `proposed` record.
+Its id arrives once, as context with the next prompt. There is no ask when, within
+2 seconds of the record being written, the hook finds in the last 4 MB of this
+session's transcript an Edit, Write, MultiEdit, NotebookEdit or Bash write (`>`,
+`>>`, `tee`, `sed -i`) that targeted a `decisions.md` or an `adr/` `.md`,
+`.markdown` or `.txt` file (outside vendored trees) with the entry's own
+heading (unique in the register) or, with no heading, most of its added lines, or that wrote a `decision:` /
+`stage:` line into `.task-pipeline/run.md`. Failed calls, subagent calls and
+Bash commands over 65,536 characters are not counted. The record then links
+that file, and keeps the link while the entry's exact heading line occurs once
+and the file is unchanged, or has only a new entry appended after it; any other
+edit to the file asks again.
+Correct that record rather than creating a second one:
 
 ```
 observatory_record(
   owner="agent:claude-code",
-  memory_id="<the id the hook printed>",
-  expected_revision=<the revision it printed>,
+  memory_id="<the id the hook gave>",
+  expected_revision=<the revision it gave>,
   statement="<the same claim, unchanged>",
   why="<one or two sentences>"
 )