workspace: version the root CLAUDE.md + InstructionsLoaded hook, and report which rules fire (R-229)
gates / gates (push) Successful in 8s
gates / gates (push) Successful in 8s
install_workspace.py lays down the two things that shaped every session while existing on one host only. Unlike install_skills.py the targets are LIVE CONFIG, so: timestamped backup before every write, settings.json MERGED (this script owns exactly one key), a diverged CLAUDE.md reported rather than silently resolved, and an unparseable settings.json refused outright. Proven: all 7 top-level settings keys survived byte-identically, and run 2 wrote nothing. rules_report.py surfaces the column that matters -- rules that have NEVER fired, which are mis-globbed or dead. 6 of 9 on first run. The hook now self-rotates at 5 MB. The memory store is BACKED UP, NOT COMMITTED (auto-written, may name hosts/paths): added to dooplex-backup.service's User Data component. /opt/backup/scripts/ is itself unversioned host state -- filed, not fixed here.
This commit is contained in:
@@ -1,3 +1,35 @@
|
||||
## install_workspace.py + rules_report.py — the workspace survives the machine (2026-08-06, R-229)
|
||||
|
||||
The workspace-root `CLAUDE.md` and the `InstructionsLoaded` hook shape every session and existed on
|
||||
**one host** — the one that cannot be rebuilt from anything else. `install_workspace.py` lays both
|
||||
down from versioned copies.
|
||||
|
||||
**Canonical-path decision:** `documentation/runbooks/workspace-CLAUDE.md` stays the source.
|
||||
`workspace/` carries only the hook fragment. A `workspace/CLAUDE.md` would be a *third* copy of a
|
||||
file whose entire problem is that copies drift, and check 5 already enforces byte-identity against
|
||||
the runbooks path.
|
||||
|
||||
**Where this deliberately differs from `install_skills.py`:** that script's targets are disposable —
|
||||
a skill dir can be deleted and re-linked losing nothing. These are **live configuration**.
|
||||
`~/.claude/settings.json` holds permissions, plugins and effort level this repo knows nothing about.
|
||||
So every write is preceded by a timestamped backup; `settings.json` is **merged**, this script owning
|
||||
exactly one key (`hooks.InstructionsLoaded`); a diverged `CLAUDE.md` is backed up and *reported*, not
|
||||
silently resolved; and an unparseable `settings.json` is **refused**, never overwritten — a malformed
|
||||
settings file disables every setting in it, and overwriting would destroy whatever was mid-fix.
|
||||
|
||||
Proven: merge preserved all 7 top-level keys byte-identically (`sha256` of the file minus `.hooks`
|
||||
unchanged across the write), and a second run wrote nothing — *idempotent* means "changed nothing the
|
||||
second time", not "ran twice without erroring".
|
||||
|
||||
**`rules_report.py`** answers what the hook log exists for: which rules fired, how often, and **which
|
||||
never have**. The empty column is the point — a never-fired rule is mis-globbed or dead, which is the
|
||||
built-but-never-wired class applied to instructions. It prints each silent rule's `paths:` beside it
|
||||
so "wrong glob" is distinguishable from "quiet month", and it judges neither. First run: 6 of 9 rule
|
||||
files had never fired. **Caveat: the log only covers since the hook was armed** — `gates.md` shows
|
||||
silent despite having fired earlier the same day, before installation.
|
||||
|
||||
The hook now **self-rotates at 5 MB**, one generation, since the log is otherwise unbounded.
|
||||
|
||||
## instructions_gate.py — check 6: the auto-memory index (2026-08-06, R-229)
|
||||
|
||||
**The bigger half of what loads was watched by nothing.** Measured at the workspace root, the
|
||||
|
||||
@@ -0,0 +1,193 @@
|
||||
# -*- coding: utf-8 -*-
|
||||
"""Lay down the workspace files that live outside every repo, from their versioned copies.
|
||||
|
||||
Usage: python3 scripts/install_workspace.py [--dry-run] [--workspace DIR] [--settings FILE]
|
||||
|
||||
WHAT THIS EXISTS FOR. Claude Code runs from /mnt/5_hdd/felhom.eu/git, which is not a git repository.
|
||||
The workspace-root CLAUDE.md and the InstructionsLoaded hook shape every session and existed on ONE
|
||||
machine — the one host that cannot be rebuilt from anything else. This restores them.
|
||||
|
||||
WHAT IT DOES NOT TOUCH. The auto-memory store. That is backed up, not versioned — see
|
||||
workspace/README.md for why, and /opt/backup/scripts/backup-config.sh for where.
|
||||
|
||||
THE ONE WAY THIS DIFFERS FROM install_skills.py, AND IT IS THE IMPORTANT ONE. That script's targets
|
||||
are disposable: a skill directory can be deleted and re-linked with nothing lost. These targets are
|
||||
LIVE CONFIGURATION. ~/.claude/settings.json holds permissions, plugins and effort level that this
|
||||
repo knows nothing about, and the workspace CLAUDE.md may have been edited on the machine since the
|
||||
last sync. So:
|
||||
|
||||
- every write is preceded by a TIMESTAMPED BACKUP of the file being replaced;
|
||||
- settings.json is MERGED, never rewritten from a template — this script owns exactly one key,
|
||||
hooks.InstructionsLoaded, and every other key is carried through untouched;
|
||||
- a diverging CLAUDE.md is reported, not silently resolved in either direction.
|
||||
|
||||
IDEMPOTENT. A second run writes nothing and says so. That is asserted by the caller in the session
|
||||
report, because "it ran twice without error" and "it changed nothing the second time" are different
|
||||
claims and only the second one means idempotent.
|
||||
"""
|
||||
import argparse
|
||||
import datetime
|
||||
import json
|
||||
import os
|
||||
import shutil
|
||||
import sys
|
||||
|
||||
REPO = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
|
||||
# Canonical source of the workspace instructions. Deliberately NOT workspace/ — see workspace/README.md.
|
||||
CLAUDE_SRC = os.path.join(REPO, "documentation", "runbooks", "workspace-CLAUDE.md")
|
||||
HOOK_SRC = os.path.join(REPO, "workspace", "hooks", "instructions-loaded.json")
|
||||
|
||||
changed = []
|
||||
unchanged = []
|
||||
problems = []
|
||||
|
||||
|
||||
def stamp():
|
||||
return datetime.datetime.now().strftime("%Y%m%d-%H%M%S")
|
||||
|
||||
|
||||
def backup(path):
|
||||
dst = "%s.bak-%s" % (path, stamp())
|
||||
shutil.copy2(path, dst)
|
||||
return dst
|
||||
|
||||
|
||||
def read(path):
|
||||
with open(path, "r", encoding="utf-8") as fh:
|
||||
return fh.read()
|
||||
|
||||
|
||||
def install_claude_md(workspace, dry_run):
|
||||
target = os.path.join(workspace, "CLAUDE.md")
|
||||
if not os.path.exists(CLAUDE_SRC):
|
||||
problems.append("versioned source missing: %s" % CLAUDE_SRC)
|
||||
return
|
||||
src_text = read(CLAUDE_SRC)
|
||||
|
||||
if os.path.exists(target):
|
||||
if read(target) == src_text:
|
||||
unchanged.append("CLAUDE.md (already byte-identical to the versioned copy)")
|
||||
return
|
||||
# Diverged. Back up FIRST, install, and report the direction so a human can judge which
|
||||
# side was right — this script must not silently pick one.
|
||||
if dry_run:
|
||||
changed.append("CLAUDE.md WOULD back up and overwrite (live file differs from source)")
|
||||
return
|
||||
b = backup(target)
|
||||
with open(target, "w", encoding="utf-8") as fh:
|
||||
fh.write(src_text)
|
||||
changed.append(
|
||||
"CLAUDE.md DIVERGED -> backed up to %s, installed from %s.\n"
|
||||
" If the LIVE file was the newer one, restore it and re-sync the versioned "
|
||||
"copy instead; instructions_gate check 5 enforces they match." % (os.path.basename(b), CLAUDE_SRC)
|
||||
)
|
||||
return
|
||||
|
||||
if dry_run:
|
||||
changed.append("CLAUDE.md WOULD create (absent)")
|
||||
return
|
||||
with open(target, "w", encoding="utf-8") as fh:
|
||||
fh.write(src_text)
|
||||
changed.append("CLAUDE.md created from %s" % CLAUDE_SRC)
|
||||
|
||||
|
||||
def install_hook(settings_path, dry_run):
|
||||
if not os.path.exists(HOOK_SRC):
|
||||
problems.append("versioned source missing: %s" % HOOK_SRC)
|
||||
return
|
||||
fragment = json.loads(read(HOOK_SRC))
|
||||
want = fragment.get("hooks", {}).get("InstructionsLoaded")
|
||||
if not want:
|
||||
problems.append("%s declares no hooks.InstructionsLoaded" % HOOK_SRC)
|
||||
return
|
||||
|
||||
if os.path.exists(settings_path):
|
||||
try:
|
||||
settings = json.loads(read(settings_path))
|
||||
except ValueError as e:
|
||||
# A broken settings.json silently disables EVERY setting in it. Never overwrite one we
|
||||
# could not parse — that would destroy whatever the user was mid-way through fixing.
|
||||
problems.append(
|
||||
"%s is not valid JSON (%s). Refusing to write: a malformed settings file disables "
|
||||
"every setting in it, and overwriting would destroy the original." % (settings_path, e)
|
||||
)
|
||||
return
|
||||
else:
|
||||
settings = {}
|
||||
|
||||
have = settings.get("hooks", {}).get("InstructionsLoaded")
|
||||
if have == want:
|
||||
unchanged.append("settings.json (hooks.InstructionsLoaded already current)")
|
||||
return
|
||||
|
||||
if dry_run:
|
||||
changed.append("settings.json WOULD merge hooks.InstructionsLoaded (%s)"
|
||||
% ("replacing an existing one" if have else "adding"))
|
||||
return
|
||||
|
||||
before_keys = sorted(settings.keys())
|
||||
if os.path.exists(settings_path):
|
||||
b = backup(settings_path)
|
||||
else:
|
||||
b = None
|
||||
os.makedirs(os.path.dirname(settings_path), exist_ok=True)
|
||||
|
||||
settings.setdefault("hooks", {})["InstructionsLoaded"] = want
|
||||
with open(settings_path, "w", encoding="utf-8") as fh:
|
||||
json.dump(settings, fh, indent=2, ensure_ascii=False)
|
||||
fh.write("\n")
|
||||
|
||||
after_keys = sorted(json.loads(read(settings_path)).keys())
|
||||
lost = set(before_keys) - set(after_keys)
|
||||
if lost:
|
||||
problems.append("MERGE LOST KEYS from settings.json: %s" % ", ".join(sorted(lost)))
|
||||
changed.append(
|
||||
"settings.json %s hooks.InstructionsLoaded%s; %d top-level key(s) carried through unchanged"
|
||||
% ("replaced" if have else "added",
|
||||
(" (backup %s)" % os.path.basename(b)) if b else "",
|
||||
len(before_keys))
|
||||
)
|
||||
|
||||
|
||||
def main(argv):
|
||||
ap = argparse.ArgumentParser()
|
||||
ap.add_argument("--dry-run", action="store_true",
|
||||
help="report what would change; write nothing")
|
||||
ap.add_argument("--workspace", default=os.path.dirname(REPO),
|
||||
help="workspace root (default: the parent of this repo)")
|
||||
ap.add_argument("--settings",
|
||||
default=os.path.join(os.path.expanduser("~"), ".claude", "settings.json"))
|
||||
args = ap.parse_args(argv[1:])
|
||||
|
||||
print("install_workspace%s" % (" [--dry-run]" if args.dry_run else ""))
|
||||
print(" workspace : %s" % args.workspace)
|
||||
print(" settings : %s" % args.settings)
|
||||
print("")
|
||||
|
||||
if not os.path.isdir(args.workspace):
|
||||
print("FAIL: workspace root does not exist: %s" % args.workspace)
|
||||
return 2
|
||||
|
||||
install_claude_md(args.workspace, args.dry_run)
|
||||
install_hook(args.settings, args.dry_run)
|
||||
|
||||
for c in changed:
|
||||
print("CHANGED %s" % c)
|
||||
for u in unchanged:
|
||||
print("unchanged %s" % u)
|
||||
for p in problems:
|
||||
print("PROBLEM %s" % p)
|
||||
|
||||
print("")
|
||||
if problems:
|
||||
print("install_workspace: %d PROBLEM(S)" % len(problems))
|
||||
return 1
|
||||
if not changed:
|
||||
print("install_workspace: nothing to do — already installed (idempotent)")
|
||||
else:
|
||||
print("install_workspace: %d change(s)" % len(changed))
|
||||
return 0
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
sys.exit(main(sys.argv))
|
||||
@@ -0,0 +1,134 @@
|
||||
# -*- coding: utf-8 -*-
|
||||
"""Which instruction files actually load, how often — and which NEVER have.
|
||||
|
||||
Usage: python3 scripts/rules_report.py [--log FILE] [--workspace DIR] [--days N]
|
||||
|
||||
READS the InstructionsLoaded hook log (~/.claude/instructions-loaded.jsonl, plus its rotated .1) and
|
||||
CROSS-REFERENCES it against every .claude/rules/*.md across the workspace.
|
||||
|
||||
THE COLUMN THAT MATTERS IS THE EMPTY ONE. A rule that has never fired is not a rule — it is either
|
||||
mis-globbed (its `paths:` never match the files people actually edit) or dead (the surface it guards
|
||||
is gone). That is the built-but-never-wired failure class, which this project has shipped four times,
|
||||
applied to instructions: the rule file exists, reads correctly, passes the gate that checks it
|
||||
declares `paths:` — and reaches the model never.
|
||||
|
||||
A never-fired rule is NOT automatically a defect. A rule scoped to a surface nobody has touched since
|
||||
it was written is simply untested. The report says which, it does not judge: `paths:` globs are
|
||||
printed beside each silent rule so the reader can tell "wrong glob" from "quiet month".
|
||||
|
||||
Exit code is always 0 — this is a report, not a gate.
|
||||
"""
|
||||
import argparse
|
||||
import collections
|
||||
import json
|
||||
import os
|
||||
import re
|
||||
import sys
|
||||
|
||||
|
||||
def load_events(paths, days):
|
||||
import datetime
|
||||
cutoff = None
|
||||
if days:
|
||||
cutoff = (datetime.datetime.utcnow() - datetime.timedelta(days=days)).strftime("%Y-%m-%dT%H:%M:%SZ")
|
||||
events, bad = [], 0
|
||||
for p in paths:
|
||||
if not os.path.exists(p):
|
||||
continue
|
||||
with open(p, "r", encoding="utf-8", errors="replace") as fh:
|
||||
for line in fh:
|
||||
line = line.strip()
|
||||
if not line:
|
||||
continue
|
||||
try:
|
||||
e = json.loads(line)
|
||||
except ValueError:
|
||||
bad += 1
|
||||
continue
|
||||
if cutoff and (e.get("ts") or "") < cutoff:
|
||||
continue
|
||||
events.append(e)
|
||||
return events, bad
|
||||
|
||||
|
||||
def find_rule_files(workspace):
|
||||
"""Every .claude/rules/*.md in the workspace, with its declared paths: globs."""
|
||||
out = {}
|
||||
for repo in sorted(os.listdir(workspace)):
|
||||
rd = os.path.join(workspace, repo, ".claude", "rules")
|
||||
if not os.path.isdir(rd):
|
||||
continue
|
||||
for name in sorted(os.listdir(rd)):
|
||||
if not name.endswith(".md"):
|
||||
continue
|
||||
full = os.path.join(rd, name)
|
||||
try:
|
||||
with open(full, "r", encoding="utf-8") as fh:
|
||||
head = fh.read(2048)
|
||||
except OSError:
|
||||
head = ""
|
||||
m = re.search(r"^paths:\s*(.+)$", head, re.M)
|
||||
globs = m.group(1).strip() if m else ("(unconditional)" if re.search(
|
||||
r"^unconditional:\s*true", head, re.M) else "(NO paths: — loads every session)")
|
||||
out[full] = (repo, name, globs)
|
||||
return out
|
||||
|
||||
|
||||
def main(argv):
|
||||
home = os.path.expanduser("~")
|
||||
ap = argparse.ArgumentParser()
|
||||
ap.add_argument("--log", default=os.path.join(home, ".claude", "instructions-loaded.jsonl"))
|
||||
ap.add_argument("--workspace",
|
||||
default=os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__)))))
|
||||
ap.add_argument("--days", type=int, default=0, help="only count events newer than N days")
|
||||
args = ap.parse_args(argv[1:])
|
||||
|
||||
logs = [args.log, args.log + ".1"]
|
||||
events, bad = load_events(logs, args.days)
|
||||
|
||||
print("rules_report")
|
||||
print(" log : %s%s" % (args.log, " (+ rotated .1)" if os.path.exists(args.log + ".1") else ""))
|
||||
print(" workspace : %s" % args.workspace)
|
||||
print(" events : %d%s%s" % (len(events),
|
||||
(" (last %d days)" % args.days) if args.days else "",
|
||||
(" [%d unparseable lines skipped]" % bad) if bad else ""))
|
||||
if not events:
|
||||
print("\n No events. The hook may not be installed — see scripts/install_workspace.py.")
|
||||
|
||||
by_reason = collections.Counter(e.get("load_reason") or "?" for e in events)
|
||||
print("\n== why instructions loaded ==")
|
||||
for reason, n in by_reason.most_common():
|
||||
print(" %-18s %d" % (reason, n))
|
||||
|
||||
fired = collections.Counter()
|
||||
triggers = collections.defaultdict(collections.Counter)
|
||||
for e in events:
|
||||
fp = e.get("file_path") or "?"
|
||||
fired[fp] += 1
|
||||
t = e.get("trigger_file_path")
|
||||
if t:
|
||||
triggers[fp][os.path.basename(t)] += 1
|
||||
|
||||
print("\n== instruction files that LOADED ==")
|
||||
if not fired:
|
||||
print(" (none)")
|
||||
for fp, n in fired.most_common():
|
||||
short = fp.replace(args.workspace + os.sep, "")
|
||||
ex = triggers[fp].most_common(1)
|
||||
print(" %5d %-58s %s" % (n, short, ("e.g. via %s" % ex[0][0]) if ex else ""))
|
||||
|
||||
rules = find_rule_files(args.workspace)
|
||||
silent = [(p, v) for p, v in sorted(rules.items()) if p not in fired]
|
||||
print("\n== rule files that have NEVER fired (%d of %d) ==" % (len(silent), len(rules)))
|
||||
if not silent:
|
||||
print(" none — every rule file in the workspace has loaded at least once")
|
||||
for p, (repo, name, globs) in silent:
|
||||
print(" %-24s %-18s paths: %s" % (repo, name, globs))
|
||||
if silent:
|
||||
print("\n A never-fired rule is mis-globbed, dead, or simply guarding a surface nobody has")
|
||||
print(" edited since it was written. The globs above are printed so you can tell which.")
|
||||
return 0
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
sys.exit(main(sys.argv))
|
||||
Reference in New Issue
Block a user