rebelytics/one-skill-to-rule-them-all / skills/task-observer
task-observer
VerifiedTurns corrections, repeated workflows and judgement calls from work sessions into small, evidenced skill updates: logs each observation with its source, stages every change for your approval, and flags repeating work as new skills. Use during ANY multi-step task, agentic workflow, or work session. Also triggers in post-task feedback discussions and when the user mentions skill observations, the observation log, or skill taxonomy. Also known as "One Skill to Rule Them All" — trigger on this phrase too. IMPORTANT: invoke this skill before the FIRST tool call of any session and before writing or proposing a plan — any turn that will involve a tool call counts. This sentence is the session-start trigger and the only activation layer that survives an unreachable config file; pair it with a CLAUDE.md instruction or a session-start hook (references/environments.md). A subagent dispatched by a session already running it does not run it: it writes nothing and puts its findings in its report.
scripts/session-start-scan.sh
View on GitHub#!/usr/bin/env bash
# session-start-scan.sh — the Session Start step 2 scan of the observation
# log, as one command.
#
# Usage:
# bash scripts/session-start-scan.sh [--entries-to <file>] [workspace-root]
# (options first: an argument after the root is refused, exit 2)
#
# [workspace-root] the pinned absolute workspace path — the directory that
# holds skill-observations/. Defaults to the environment
# variable TASK_OBSERVER_WORKSPACE. One of the two is
# required; the log is never resolved from the cwd. The
# path may contain spaces.
# --skill-dir <dir>
# the installed skill directory, read for the shipped
# starter set; default: the directory above this script.
# A copy run from skill-observations/.bin/ passes it.
# --entries-to <file>
# write the per-entry listing to <file>
# instead of stdout, for a channel that caps the output
# (a bridged device shell): stdout then carries only the
# finding lines, the counts, the principles' headings and
# the summary block, and the entries are read from the
# file on demand. <file> is a path THIS run created
# (`mktemp`), never a fixed name in a shared scratch
# directory: an existing non-empty file is refused (exit
# 2), because a redirect onto another session's file
# followed by a read returns that session's scan.
# TASK_OBSERVER_SEARCH_SECONDS
# environment: the time limit, in whole seconds, of the
# sibling-log search (default 10); a search cut there
# is a NOTE line, never a stall.
#
# Prints, on stdout, in this order: any DUE / NOTE / LOST ENTRIES / UNFILLED /
# DUPLICATE ID / RESURRECTED lines
# (DUE: a session-start duty still owed — `DUE: workspace creation` when one
# of the four artefacts the Workspace creation command makes is missing,
# `DUE: starter-set reconciliation` when skill-observations/
# starter-principles-reviewed.txt is absent or names an older set than
# references/starter-principles.md beside this script; where that file is
# unreadable — a .bin/ copy in a bridged session — an absent marker is still
# DUE and an older one is not compared, so no line prints for it; the line
# names where the offer may be made, since it is read mid-task; a marker
# that is not one line holding only the version is a NOTE quoting line 1;
# `DUE: starter-set import lost` when checkpoints.log records a
# reconciliation that imported entries and the principles file's Active
# Principles hold none marked as imported;
# UNFILLED: a header whose title: is empty — the skeleton new-observation.sh
# writes at create time, a write in progress or abandoned; NOTE: id: … when
# a header's id does not read as its filename prefix; DUPLICATE ID — NNNN:
# <file1>, <file2> when two files across observation-log/ and archive/ share
# a numeric prefix — a write that went around the id snippet's prefix
# guard; RESURRECTED — when an active file is byte-identical to its
# same-named archive/ copy, a restored archive entry, never renumbered); the
# NOTE lines for a header key written twice, for an actioned entry whose
# resolution: gives a skill: member no disposition, and for a file holding a
# key-shaped run beside key / token / secret / password (names only); the
# counts line (files, parsed, suspect, archive-suspect, resurrected); a SPLIT STORE line when a
# pre-3.0 log.md sits beside the directory, and one for an observation log
# at the working directory or beside the skill's install that is not the
# pinned root; a `staged:` line naming
# [root]/skill-updates/ and its manifest, and a NOTE: SPLIT STAGING (both
# roots) or NOTE: legacy staging root line when
# skill-observations/skill-updates/ (the pre-3.0 staging root) exists; a NOTE: pointer line when
# skill-observations/MOVED.md exists; a GAP
# line when the previous scan in checkpoints.log is 7 or more days old; a
# `review:` line on every run (the last review's date and age in days, and
# the open entries dated after it or undated — never a finding); the
# session-start record; the active principles' headings; then one line per numbered entry,
# `id | status | skill | proposes_skill | title` (`-` for a field the header
# lacks), parked entries after the others, an actioned, declined or
# superseded entry as `id | status | skill | proposes_skill | resolved <date>
# — title withheld` (its title names a defect that is probably fixed), and
# `--- <file> (no header)` or
# `--- <file> (header not closed)` for a file whose header did not parse (or,
# with --entries-to, that listing goes to the file); the full headers go to
# skill-observations/last-scan-headers.txt, overwritten each run, for a step
# that needs another field; then, flushed out first and bounded by a time
# limit, the logs found at the plausible anchors, each with its entry count,
# its checkpoints.log's last date and any log.md beside it, with any finding
# that search makes (another root's SPLIT STORE, a NOTE when the search hit
# its limit); then the summary
# block: every finding line (DUE / NOTE / LOST ENTRIES / UNFILLED / DUPLICATE
# ID / RESURRECTED / SPLIT STORE / GAP) repeated VERBATIM, and LAST one `end of scan` line
# repeating the counts, how many finding lines stand above the entries, how
# many bytes stdout carried above it, and this script's version (VERSION below, equal to the skill's `metadata.version`), so
# a run can tell a script that lacks a feature from one that is broken. The findings
# open the output and close it, so a view cut by `head` keeps them and one
# cut by `tail` keeps them with the summary; the same lines are written to
# skill-observations/last-scan-findings.txt (overwritten each run, empty
# when there are none), which the end line names, so a run whose output was
# cut anyway still has them on disk. Three places, because an instruction
# not to cut the output was broken while it was in context: the barrier is
# the output's shape, not the reader. None of it replaces reading the output
# whole, which the end line says.
# Appends one line to skill-observations/checkpoints.log:
# YYYY-MM-DD HH:MM [<cwd's last segment>] session-start scan: files=N parsed=N principles=N
# and one to skill-observations/session-starts.log (also printed), the
# checklist items it can measure:
# YYYY-MM-DD HH:MM [<label>] session start: 1 storage=… 2 scan=… 3 review=… 6 staged=… 7 log=…
#
# Exit status:
# 0 the scan ran (NOTE lines are findings, not failures)
# 1 SCAN COMMAND BROKEN — numbered files exist but no header parsed, or
# a count did not read as a number; or SCAN TOOLS MISSING — a command
# the scan runs is not on PATH. The scan halts there, before the
# checkpoint line and the content print (the sidecar file holds that
# one line, so no earlier run's findings survive the halt)
# 2 refused: no workspace root, a root that is not an absolute path, a
# root with no skill-observations/observation-log/ under it (the line
# says which: a path inside the workspace, a first run, a pre-3.0
# log.md, a root that does not exist; a root named skill-observations/
# that holds the log is resolved to its parent instead, with a NOTE), an
# --entries-to path that exists and is not empty, an unknown option, or
# any argument after the root (an option there is a usage error)
# 3 --entries-to left its file empty while numbered files exist: a broken
# run, named by a NOTE line in the summary block and the sidecar
# any other non-zero status is the content print's own (the counts and the
# checkpoint line above it already ran, and the end-of-scan line names the
# status) — a refused or failed print is never an empty log
#
# This is the inline scan SKILL.md carried in step 2, unchanged in what it
# runs and prints, moved into a file for two reasons. A reader can review it
# here, line by line, instead of as one block of awk regexes inside a numbered
# step. And it no longer travels through the agent's Bash tool as text: on a
# host whose tool halves runs of backslashes (Git for Windows' bash fed one
# `-c` argument), the suspect program's `\\` runs arrived altered, the program
# stopped compiling, and `suspect` read 0 with an error on stderr. A file
# read by bash arrives exact; the one-line invocation carries no backslash.
#
# bash, not sh: the invocation names bash, and every snippet in this skill is
# bash. Runs on bash 3.2 (stock macOS): case patterns are parenthesised.
set -u
VERSION="3.12.0" # equal to the skill's frontmatter metadata.version; the end line names it
entries= # --entries-to target; empty = the entries print to stdout
skill_dir= # --skill-dir: the installed skill directory; empty = the one this script sits in
while [ $# -gt 0 ]; do
case $1 in
(--entries-to) [ $# -ge 2 ] || { echo "--entries-to needs a file path" >&2; exit 2; }; entries="$2"; shift 2 ;;
(--entries-to=*) entries="${1#--entries-to=}"; shift ;;
(--skill-dir) [ $# -ge 2 ] || { echo "--skill-dir needs a directory" >&2; exit 2; }; skill_dir="$2"; shift 2 ;;
(--skill-dir=*) skill_dir="${1#--skill-dir=}"; shift ;;
(--) shift; break ;;
(-*) echo "unknown option '$1' (the options are --entries-to <file> and --skill-dir <dir>)" >&2; exit 2 ;;
(*) break ;;
esac
done
root="${1:-${TASK_OBSERVER_WORKSPACE:-}}"
# Nothing may follow the root: the loop above stops at it, so an option
# written after it was never parsed — a trailing --entries-to silently fell
# back to printing the entries on stdout and left its file empty. Refused
# by name instead, before anything is written.
[ $# -gt 0 ] && shift
if [ $# -gt 0 ]; then
echo "argument after the workspace root: '$1' — options go BEFORE the root (bash session-start-scan.sh --entries-to <file> <root>); nothing was scanned" >&2; exit 2
fi
if [ -n "$entries" ] && [ -s "$entries" ]; then
echo "--entries-to '$entries' exists and is not empty: pass a path this run created (mktemp), never a fixed name another session may hold" >&2; exit 2
fi
if [ -z "$root" ]; then
echo "no workspace root: pass it as the first argument or set TASK_OBSERVER_WORKSPACE" >&2; exit 2
fi
# A Windows drive path (C:/... or C:\...) is absolute there and is used as
# given: Git Bash's find, awk and dirname accept it, and the paths the scan
# prints keep the form the pin used.
case $root in
(/*|[A-Za-z]:[/\\]*) ;;
(*) echo "workspace root must be an ABSOLUTE path, never relative to the cwd: got '$root'" >&2; exit 2 ;;
esac
# Every expansion of $root, $d and $p stays double-quoted: the pinned path
# routinely contains a space.
d="$root/skill-observations/observation-log"
# --- the root holds a log: refused by name, before any command runs ----------
# A wrong root used to print six find errors, `files: 0`, exit 0 and a
# checkpoint line: a clean empty backlog. Only builtins run here. One
# near-miss is resolved instead: a root named skill-observations/ that holds
# observation-log/ (a pin one level too deep) scans its parent, and a NOTE
# names the resolution so the pin gets fixed.
resolved=
case ${root%/} in
(*/skill-observations)
if [ ! -d "$d" ] && [ -d "${root%/}/observation-log" ]; then
root="${root%/}"; root="${root%/skill-observations}"; d="$root/skill-observations/observation-log"
resolved="NOTE: root resolved: $root (argument named skill-observations/) — the workspace root is the directory that contains skill-observations/; fix the pin"
fi ;;
esac
if [ ! -d "$d" ]; then
r="${root%/}"
case $r in
(*/skill-observations/observation-log) why="that is the log itself — pass '${r%/skill-observations/observation-log}', the directory that contains skill-observations/" ;;
(*/skill-observations) why="that is skill-observations/ itself — pass '${r%/skill-observations}', the directory that contains it" ;;
(*) if [ ! -d "$root" ]; then why="the root does not exist — check the pinned path"
elif [ -e "$root/skill-observations/log.md" ]; then why="a pre-3.0 log.md and no directory — run the migration (references/migration.md) first"
elif [ ! -d "$root/skill-observations" ]; then why="no skill-observations/ — a first run: run the Workspace creation command (references/observation-log.md) first, or pass the workspace root"
else why="skill-observations/ holds no observation-log/ — run the Workspace creation command (references/observation-log.md)"; fi ;;
esac
echo "no observation log under '$root': $why; nothing was scanned or written" >&2; exit 2
fi
# --- the tools: a missing command is a broken scan, never an empty log -------
# On a runner without the usual commands every count came back empty and the
# trace line was appended anyway. The halt line goes to the sidecar too.
miss=
for t in find awk sed wc tr date sort grep head tail cut dirname tee; do
command -v "$t" >/dev/null 2>&1 || miss="$miss $t"
done
if [ -n "$miss" ]; then
printf 'SCAN TOOLS MISSING —%s not on PATH; nothing scanned, no checkpoint line written\n' "$miss"
printf 'SCAN TOOLS MISSING —%s not on PATH\n' "$miss" > "$root/skill-observations/last-scan-findings.txt" 2>/dev/null
exit 1
fi
# --- the output is counted: stdout goes through a buffer up to the end line ---
# The end line names how many bytes stand above it, so a copy that a harness
# saved to a file or cut to a preview is told from the whole output by its
# size, not by whether the end line happens to be in view. The buffer is
# written out on every exit, a halt included; without mktemp the output runs
# unbuffered and the end line says the bytes were not counted. The buffer is
# opened for APPEND: the entries are flushed out of it before the sibling-log
# search (below), and an emptied append-mode file takes the next write at its
# start, where a plain `>` would leave a run of NUL bytes.
buf=$(mktemp 2>/dev/null) || buf=
by0=0 # bytes already flushed to stdout ahead of the end line
if [ -n "$buf" ]; then
exec 5>&1 >>"$buf"
trap 'exec >&5; cat "$buf"; rm -f "$buf"' EXIT
fi
# --- counts -------------------------------------------------------------------
# n: numbered, non-empty files — what the parse can read. Counted from the
# literal path, independent of $d, so the guard below compares two numbers
# derived by different means.
n=$(find "$root/skill-observations/observation-log" -maxdepth 1 -name '[0-9]*.md' ! -empty | wc -l | tr -d ' ')
# parsed: files whose header opens on line 1 (after a UTF-8 BOM, if any) and
# closes with a second `---`. Counted by its own command, never inside the
# printing loop.
parsed=$(LC_ALL=C find "$d" -maxdepth 1 -name '[0-9]*.md' -exec awk 'FNR==1 {sub(/^\357\273\277/, ""); fm=/^---[[:space:]]*$/; if (!fm) nextfile; next} fm && /^---[[:space:]]*$/ {print FILENAME; nextfile}' {} + | wc -l | tr -d ' ')
bad=; case $n in (""|*[!0-9]*) bad=1 ;; esac; case $parsed in (""|*[!0-9]*) bad=1 ;; esac
if [ -n "$bad" ]; then echo "SCAN COMMAND BROKEN — the counts did not read as numbers (files='$n' parsed='$parsed')" | tee "$root/skill-observations/last-scan-findings.txt"; exit 1; fi
# --- suspect: headers that look like invalid YAML by shape (a floor) ----------
# The awk program `sus` is assembled from the named parts below, then run
# once over the active directory and once over archive/. One rule per line
# of the program, each printing the file name at its first hit:
# 1. line 1 opens the header (state resets per file, so an unclosed header
# cannot leak into the next file under find -exec … +)
# 2. the closing `---` ends the header
# 3. a plain (unquoted) value holding `: `
# 4. text after a closing quote, double- or single-quoted
# 5. a value opening with a backtick, @ or %
# 6. a double-quoted value holding an escape YAML does not define
# 7. a [ … ] list whose unquoted part holds a colon
# A hit prints `<file> TAB <rule> TAB <line>`; the scan names each file with
# its rule and key in the NOTE, the creation helper names the rule and the
# line in its refusal.
# Every rule allows any number of spaces after the key's colon and any
# &anchor / !tag before the value. The program holds no literal brace pair:
# find -exec … {} + would replace it.
# >>> sus: shared with new-observation.sh, byte for byte (the selftest compares them)
key='^[a-z_]+:[ ]+([&!][^[:space:]]*[[:space:]]+)*' # a key, its spaces, any &anchor or !tag
hx='[[:xdigit:]]' # one hex digit
# cut_short N: N hex digits cut short — k hex digits (k < N), then a non-hex
# character, as one alternation: cut_short 2 is `[^h]|h[^h]`, h being $hx.
cut_short() {
local k i pre alt=
for ((k = 0; k < $1; k++)); do
pre=
for ((i = 0; i < k; i++)); do pre="$pre$hx"; done
alt="$alt${alt:+|}$pre[^[:xdigit:]]"
done
printf '%s' "$alt"
}
# The escapes a double-quoted YAML scalar defines: one character from the set,
# or \x, \u, \U followed by exactly 2, 4 and 8 hex digits.
esc_ok='\\[0abtnvfre \t\r"\/\\N_LP]|\\x'"$hx$hx"'|\\u'"$hx$hx$hx$hx"'|\\U'"$hx$hx$hx$hx$hx$hx$hx$hx"
# What follows a backslash in an undefined escape: a character outside the
# set, or \x, \u, \U with too few hex digits.
esc_bad='[^0abtnvfre \t\r"\/\\N_LPxuU]|x('"$(cut_short 2)"')|u('"$(cut_short 4)"')|U('"$(cut_short 8)"')'
sus='FNR==1 {sub(/^\357\273\277/, ""); fm = (/^---[[:space:]]*$/ ? 1 : 0); if (!fm) nextfile; next}
fm && /^---[[:space:]]*$/ {fm=0; nextfile}
fm && /'"$key"'[^"\047[{|>#&![:space:]].*: / {print FILENAME "\t3\t" $0; nextfile}
fm && /'"$key"'("([^"\\]|\\.)*"[[:space:]]*[^[:space:]#]|\047([^\047]|\047\047)*\047([[:space:]]+[^[:space:]#]|[^[:space:]#\047]))/ {print FILENAME "\t4\t" $0; nextfile}
fm && /'"$key"'[`@%]/ {print FILENAME "\t5\t" $0; nextfile}
fm && /'"$key"'"([^"\\]|('"$esc_ok"'))*\\('"$esc_bad"')/ {print FILENAME "\t6\t" $0; nextfile}
fm && /^[a-z_]+:[ ]+\[/ {v=$0; sub(/^[a-z_]+:[ ]+/,"",v); gsub(/"([^"\\]|\\.)*"/,"",v); gsub(/\047[^\047]*\047/,"",v); sub(/[[:space:]]#.*/,"",v); if (v ~ /:/) {print FILENAME "\t7\t" $0; nextfile}}'
# <<< sus
# The dispositions program, shared with set-fields.sh (which refuses the
# change it reports): an actioned entry whose resolution: gives a listed
# skill: member no disposition prints `<file> TAB <members>`.
# >>> disp: shared with session-start-scan.sh, byte for byte (the selftest compares them)
disp='function has(r, m, s, i, c, rest) {s = r
while ((i = index(s, m ":")) > 0) {c = (i > 1) ? substr(s, i - 1, 1) : ""
rest = substr(s, i + length(m) + 1); sub(/^[[:space:]]+/, "", rest)
if (c !~ /[A-Za-z0-9_.-]/ && rest ~ /^(applied|added|excluded|carried)/) return 1
s = substr(s, i + length(m) + 1)}
return 0}
function add(x) {sub(/[[:space:]]+#.*$/, "", x); gsub(/["\047\r]/, "", x); gsub(/^[[:space:]]+|[[:space:]]+$/, "", x); sub(/.*:/, "", x); if (x != "") sk[++ns] = x}
FNR==1 {split("", sk); ns = 0; res = ""; st = ""; key = ""; sub(/^\357\273\277/, ""); fm = /^---[[:space:]]*$/; if (!fm) nextfile; next}
fm && /^---[[:space:]]*$/ {fm = 0; miss = ""
if (st == "actioned") for (j = 1; j <= ns; j++) if (!has(res, sk[j])) miss = miss (miss == "" ? "" : " ") sk[j]
if (miss != "") print FILENAME "\t" miss
nextfile}
fm && /^[A-Za-z_][A-Za-z0-9_]*:/ {key = $0; sub(/:.*/, "", key); v = $0; sub(/^[A-Za-z_][A-Za-z0-9_]*:[[:space:]]*/, "", v); sub(/\r$/, "", v)
if (key == "status") {st = v; sub(/[[:space:]]+#.*$/, "", st); gsub(/["\047[:space:]]/, "", st)}
if (key == "resolution") res = v
if (key == "skill") {sub(/[[:space:]]+#.*$/, "", v); gsub(/\[|\]/, "", v); nn = split(v, a, ","); for (j = 1; j <= nn; j++) add(a[j])}
next}
fm && key == "skill" && /^[[:space:]]+-[[:space:]]/ {v = $0; sub(/^[[:space:]]+-[[:space:]]*/, "", v); add(v); next}
fm && key == "resolution" && /^[[:space:]]+[^[:space:]#]/ {res = res " " $0}'
# <<< disp
# The hits are kept, not only counted: the NOTE names each file with its rule
# and key (`0042-x.md rule 4 commands_verified`), never the value.
s_hits=$(LC_ALL=C find "$d" -maxdepth 1 -name '[0-9]*.md' -exec awk "$sus" {} +)
a_hits=; [ -d "$d/archive" ] && a_hits=$(LC_ALL=C find "$d/archive" -maxdepth 1 -name '*.md' -exec awk "$sus" {} +) # archive/ may not exist yet
suspect=$(printf '%s\n' "$s_hits" | grep -c .)
a_sus=$(printf '%s\n' "$a_hits" | grep -c .)
sus_names=$( { printf '%s\n' "$s_hits" | awk -F '\t' 'NF >= 3 {f = $1; sub(/.*\//, "", f); k = $3; sub(/:.*/, "", k); print f " rule " $2 " " k}'
printf '%s\n' "$a_hits" | awk -F '\t' 'NF >= 3 {f = $1; sub(/.*\//, "", f); k = $3; sub(/:.*/, "", k); print "archive/" f " rule " $2 " " k}'; } | LC_ALL=C sort | awk '{printf "%s%s", (NR > 1 ? ", " : ""), $0}')
# --- principles: count the headings under `## Active Principles` --------------
# A fenced block is skipped, so a template inside the file is not a principle.
p="$root/skill-observations/cross-cutting-principles.md"
pa='/^(\140\140\140|~~~)/ {f=!f} f {next} /^## Active Principles/ {a=1; h=1; next} a && /^## / {a=0}'
pr=absent; [ -f "$p" ] && pr=$(awk "$pa"' a && /^### / {n++} END {print (h ? n+0 : "unparsed")}' "$p")
# finding prints one finding line (DUE / NOTE / LOST ENTRIES / UNFILLED /
# SPLIT STORE / GAP) above the entries, keeps it for the summary block and the
# sidecar file, and counts it (fx) for the end-of-scan line. Every finding
# goes through it, so the three copies cannot differ.
fx=0; findings=
sidecar="$root/skill-observations/last-scan-findings.txt"
finding() { printf '%s\n' "$1"; findings="$findings$1"$'\n'; fx=$((fx + 1)); }
[ -n "$resolved" ] && finding "$resolved"
[ "$pr" = unparsed ] && finding "NOTE: the principles file has no '## Active Principles' heading — 'could not parse', not 'no principles'; read it directly"
# --- due: the step 1 duties the prose names, printed when still owed ----------
# Workspace creation: the four artefacts its command makes and asserts.
miss=
for x in observation-log/archive last-review-date.txt cross-cutting-principles.md; do
[ -e "$root/skill-observations/$x" ] || miss="$miss${miss:+, }$x"
done
[ -n "$miss" ] && finding "DUE: workspace creation — missing: $miss; run the Workspace creation command (references/observation-log.md) before anything else this session"
# Starter-set reconciliation: the marker against the shipped set, read from
# the installed skill (--skill-dir, else the directory this script sits in).
# A copy run away from its install (.bin/) finds no set there: an absent
# marker is still due, and an existing one cannot be compared — said in a
# NOTE, never skipped silently.
mk="$root/skill-observations/starter-principles-reviewed.txt"
sp="${skill_dir:-$(dirname "$0")/..}/references/starter-principles.md"
ship=; [ -r "$sp" ] && ship=$(sed -n 's/^Starter set version:[[:space:]]*\([0-9][0-9]*\).*/\1/p' "$sp" | head -n 1)
if [ ! -e "$mk" ]; then
finding "DUE: starter-set reconciliation — skill-observations/starter-principles-reviewed.txt is absent; offer once, in a review or a session opened for skill work, never in another task's reply (references/starter-principles.md, Reconciliation)"
elif [ -z "$ship" ]; then
finding "NOTE: shipped starter set not found at $sp — the marker cannot be compared with it; pass --skill-dir <installed skill directory> (a copy run from skill-observations/.bin/ has no references/ beside it)"
else
# The marker's format: one line holding only the starter-set version, a
# bare integer. A BOM, a CR and surrounding blanks are tolerated; any
# other text is reported, never mined for digits (`v2 (13 imported)` is
# not 213). An empty marker is still due.
mv_v=$(awk 'NR == 1 { sub(/^\357\273\277/, "") } { sub(/\r$/, ""); gsub(/^[[:space:]]+|[[:space:]]+$/, "") } NF { n++; v = $0 }
END { if (n == 1 && v ~ /^[0-9]+$/) print v; else if (n) print "malformed" }' "$mk")
if [ "$mv_v" = malformed ]; then
finding "NOTE: starter-set marker skill-observations/starter-principles-reviewed.txt is not one line holding only a version number (line 1: '$(head -n 1 "$mk" | tr -d '\r' | cut -c1-60)') — not compared with shipped set v$ship; if the adopter answered for a set, rewrite it as that version alone, else remove it so the offer returns (references/starter-principles.md, Reconciliation)"
elif [ -z "$mv_v" ] || [ "$((10#$mv_v))" -lt "$ship" ]; then
finding "DUE: starter-set reconciliation — marker v${mv_v:-?} < shipped set v$ship; offer once, in a review or a session opened for skill work, never in another task's reply (references/starter-principles.md, Reconciliation)"
fi
fi
# The marker certifies the answer, not the import: when checkpoints.log's
# last reconciliation line records K > 0 imported and the principles file's
# Active Principles hold no entry marked as imported from the starter set,
# the import was lost and the offer is due again. Zero, not fewer than K:
# the pruning pass removes imported entries on purpose.
ck_si=$(grep -E 'starter set v[0-9]+ reconciled: [0-9]+ imported' "$root/skill-observations/checkpoints.log" 2>/dev/null | tail -n 1 | tr -d '\r')
ck_k=$(printf '%s' "$ck_si" | sed -n 's/.*reconciled: \([0-9][0-9]*\) imported.*/\1/p')
if [ -e "$mk" ] && [ -n "$ck_k" ] && [ "$((10#$ck_k))" -gt 0 ] && [ -f "$p" ] && [ "$pr" != unparsed ]; then
p_imp=$(awk "$pa"' a && /imported from starter set/ {n++} END {print n+0}' "$p")
[ "$p_imp" -eq 0 ] && finding "DUE: starter-set import lost — checkpoints.log records 'starter set ${ck_si#* starter set }' but the Active Principles in cross-cutting-principles.md hold no entry imported from the starter set; redo the import from the entry numbers on that line, or re-offer the reconciliation (references/starter-principles.md, How to import)"
fi
# --- the guard: files present and nothing parsed is a broken command ----------
# The sidecar takes the guard line too: a stale finding file from the previous
# run must not survive a run that halted.
if [ "$n" -gt 0 ] && [ "$parsed" -eq 0 ]; then echo "SCAN COMMAND BROKEN — $n files present, 0 headers parsed" | tee "$sidecar"; exit 1; fi
# --- findings ----------------------------------------------------------------
# Lost entries: a zero-byte numbered file, or one with no opening `---`.
lost=$( { find "$d" -maxdepth 1 -name '[0-9]*.md' -empty; LC_ALL=C find "$d" -maxdepth 1 -name '[0-9]*.md' ! -empty -exec awk 'FNR==1 {sub(/^\357\273\277/, ""); if (!/^---[[:space:]]*$/) print FILENAME; nextfile}' {} +; } | sed 's|.*/||' | LC_ALL=C sort | tr '\n' ' ')
[ -n "$lost" ] && finding "LOST ENTRIES — no header, an interrupted write; report each, never reuse or delete: $lost"
# Unfilled and mismatched headers, from one awk over the parsed headers:
# U <file> for a header whose title: is empty — the skeleton the helper
# writes at create time, so a write in progress or abandoned, distinct from
# LOST (it holds its id); I <file> <id> for a header whose id: does not
# read as the filename prefix (a retyped id, or a body written into another
# entry's file). The id may be padded or not — both forms exist in live
# logs — so the comparison is numeric.
hd=$(LC_ALL=C find "$d" -maxdepth 1 -name '[0-9]*.md' -exec awk 'FNR==1 {sub(/^\357\273\277/, ""); fm=/^---[[:space:]]*$/; ti=0; idv="none"; f=FILENAME; sub(/.*\//, "", f); pre=substr(f, 1, match(f, /[^0-9]/) - 1); if (!fm) nextfile; next}
fm && /^---[[:space:]]*$/ {if (ti) print "U " f; if (idv !~ /^0*[1-9][0-9]*$/ || idv + 0 != pre + 0) print "I " f " " idv; nextfile}
fm && /^title:/ {v=$0; sub(/^title:[[:space:]]*/, "", v); sub(/[[:space:]]+$/, "", v); ti=(v == "" || v == "\"\"" || v == "\047\047")}
fm && /^id:/ {idv=$2; gsub(/["\047\r]/, "", idv)}' {} +)
unfilled=$(printf '%s\n' "$hd" | sed -n 's/^U //p' | LC_ALL=C sort | tr '\n' ' ')
[ -n "$unfilled" ] && finding "UNFILLED — a header with an empty title: the helper's skeleton, a write in progress or abandoned; it holds its id, so fill it or decline it, never reuse or delete: $unfilled"
idmis=$(printf '%s\n' "$hd" | sed -n 's/^I \(.*\) \(.*\)$/\1 (id: \2)/p' | LC_ALL=C sort | tr '\n' ' ')
[ -n "$idmis" ] && finding "NOTE: id: does not read as the filename prefix — another entry's id retyped, or a body written into the wrong file; fix the field, never the filename, after reading the body: $idmis"
# Duplicate numeric prefixes across observation-log/ and archive/: two files
# sharing one id are a write that went around the snippet's prefix guard
# (the guard lives on one write path; this check reads them all). The
# prefix is compared as a number, so 0063- and 63- are one id; archived
# files are named with their archive/ prefix. One finding line per id,
# counted and written to the sidecar like every other.
# An active file byte-identical to its same-named archive/ copy is not a
# collision: a sync or mirror restored an archived entry (an `mv` the mirror
# turned into a copy). It is reported as RESURRECTED, left out of the
# DUPLICATE ID check and of the entries print, and counted on its own; the
# fix removes the active copy and never renumbers. Without cmp on PATH the
# pair falls through to DUPLICATE ID.
res=; nres=0
if [ -d "$d/archive" ] && command -v cmp >/dev/null 2>&1; then
for p_a in "$d"/[0-9]*.md; do
[ -f "$p_a" ] || continue
b_a=${p_a##*/}
if [ -f "$d/archive/$b_a" ] && cmp -s "$p_a" "$d/archive/$b_a"; then res="$res/$b_a"; nres=$((nres + 1)); fi
done
[ -n "$res" ] && res="$res/"
fi
[ "$nres" -gt 0 ] && finding "RESURRECTED — $nres active file(s) byte-identical to their archive/ copy, a sync or mirror restoring archived entries: $(printf '%s' "$res" | sed 's|^/||; s|/$||; s|/|, |g'); remove the active copy, never renumber, and record the sync client (references/environments.md, \"Stable is not the same as always available\")"
dups=$( { find "$d" -maxdepth 1 -name '[0-9]*.md' | sed 's|.*/||' | LC_ALL=C awk -v skip="$res" 'index(skip, "/" $0 "/") == 0'; [ -d "$d/archive" ] && find "$d/archive" -maxdepth 1 -name '[0-9]*.md' | sed 's|.*/\([^/]*\)$|archive/\1|'; } \
| LC_ALL=C sort | LC_ALL=C awk '{f=$0; sub(/^archive\//, "", f); n=substr(f, 1, match(f, /[^0-9]/) - 1) + 0; c[n]++; if (n in l) l[n]=l[n] ", " $0; else l[n]=$0} END {for (n in c) if (c[n] > 1) printf "%04d: %s\n", n, l[n]}' | LC_ALL=C sort)
if [ -n "$dups" ]; then
# a here-string, not a pipe: `finding` must update fx and findings in THIS shell
while IFS= read -r line; do [ -n "$line" ] && finding "DUPLICATE ID — $line — two writes share one id; re-id the uncited file (else the later one) in the next review and never cite the number bare"; done <<< "$dups"
fi
# Duplicate header keys, active and archive/: a top-level key written twice
# passes every count here, and parsers disagree on which copy they keep (a
# batch edit once wrote one entry's lines over another's this way).
# scripts/set-fields.sh refuses such a file; this names it at read time.
dk=$( { LC_ALL=C find "$d" -maxdepth 1 -name '[0-9]*.md' -exec awk 'FNR==1 {split("", k); f=FILENAME; sub(/.*\//, "", f); sub(/^\357\273\277/, ""); fm=/^---[[:space:]]*$/; if (!fm) nextfile; next}
fm && /^---[[:space:]]*$/ {nextfile}
fm && /^[A-Za-z_][A-Za-z0-9_]*:/ {x=$0; sub(/:.*/, "", x); if (k[x]++ == 1) print f " (" x ")"}' {} +
[ -d "$d/archive" ] && LC_ALL=C find "$d/archive" -maxdepth 1 -name '[0-9]*.md' -exec awk 'FNR==1 {split("", k); f=FILENAME; sub(/.*\//, "archive/", f); sub(/^\357\273\277/, ""); fm=/^---[[:space:]]*$/; if (!fm) nextfile; next}
fm && /^---[[:space:]]*$/ {nextfile}
fm && /^[A-Za-z_][A-Za-z0-9_]*:/ {x=$0; sub(/:.*/, "", x); if (k[x]++ == 1) print f " (" x ")"}' {} +; } | LC_ALL=C sort | awk '{s = s (NR > 1 ? ", " : "") $0} END {print s}')
[ -n "$dk" ] && finding "NOTE: a header key occurs twice — parsers disagree on which copy they keep; read the body, keep one line, never batch-rewrite: $dk"
# Actioned entries, active only, whose resolution: gives a listed skill:
# member no disposition: a family fix marked done while a member was never
# edited for it reads as complete everywhere else.
nd=$(LC_ALL=C find "$d" -maxdepth 1 -name '[0-9]*.md' -exec awk "$disp" {} + | sed 's|^.*/||' | LC_ALL=C sort | awk -F '\t' '{s = s (NR > 1 ? ", " : "") $1 " (" $2 ")"} END {print s}')
[ -n "$nd" ] && finding "NOTE: actioned without a disposition for every skill: member — resolution: names each as '<member>: applied|excluded|carried'; complete it, or re-open the entry, through scripts/set-fields.sh: $nd"
# Secret-shaped values, active and archive/, header and body: a line naming
# key / token / secret / password that also holds a run of 24 or more letters
# and digits, both present (a 40- or 64-hex digest is skipped). File names
# only, never the match: printing it would copy the secret again. A floor.
run=; for ((i = 0; i < 24; i++)); do run="$run[A-Za-z0-9]"; done
sec='{l = tolower($0); if (l !~ /key|token|secret|password/) next; s = $0
while (match(s, /'"$run"'[A-Za-z0-9]*/)) {t = substr(s, RSTART, RLENGTH); s = substr(s, RSTART + RLENGTH)
if (t ~ /^[0-9a-fA-F]+$/ && (length(t) == 40 || length(t) == 64)) continue
if (t ~ /[0-9]/ && t ~ /[A-Za-z]/) {print FILENAME; nextfile}}}'
sk=$( { LC_ALL=C find "$d" -maxdepth 1 -name '[0-9]*.md' -exec awk "$sec" {} + | sed 's|.*/||'
[ -d "$d/archive" ] && LC_ALL=C find "$d/archive" -maxdepth 1 -name '[0-9]*.md' -exec awk "$sec" {} + | sed 's|.*/|archive/|'; } | LC_ALL=C sort -u)
if [ -n "$sk" ]; then
finding "NOTE: $(printf '%s\n' "$sk" | grep -c .) file(s) hold a key-shaped run beside key / token / secret / password (names only, never the match): $(printf '%s\n' "$sk" | tr '\n' ' ')— read each and rewrite the value to its shape (SKILL.md, How to Log, confidentiality)"
fi
# Headers that did not parse, by name: no opening, or no closing `---`. The
# names ride on the finding line itself, so the repeat and the sidecar carry them.
if [ "$parsed" -lt "$n" ]; then
unparsed=$(LC_ALL=C find "$d" -maxdepth 1 -name '[0-9]*.md' -exec awk 'FNR==1 {if (NR>1 && fm) print f; f=FILENAME; sub(/^\357\273\277/, ""); fm=/^---[[:space:]]*$/; if (!fm) {print f; nextfile}; next} fm && /^---[[:space:]]*$/ {fm=0; nextfile} END {if (fm) print f}' {} + | sed 's|.*/||' | LC_ALL=C sort | tr '\n' ' ')
finding "NOTE: $((n - parsed)) of $n headers did not parse (no opening or no closing ---): $unparsed"
fi
[ "$suspect" -gt 0 ] || [ "$a_sus" -gt 0 ] && finding "NOTE: $suspect of $n headers (and $a_sus in archive/) look like invalid YAML (rule 3 an unquoted ': ', 4 text after a closing quote, 5 a value opening with a backtick, @ or %, 6 an undefined escape, 7 a colon in an unquoted list entry): $sus_names — quote or fix them (File format)"
printf 'files: %s parsed: %s suspect (awk, a floor): %s archive-suspect: %s resurrected: %s\n' "$n" "$parsed" "$suspect" "$a_sus" "$nres"
# --- split store: a pre-3.0 log.md beside the directory -----------------------
# The creation command's LEGACY guard fires only when the directory is
# absent, so a legacy file written AFTER the migration — by an older
# installed copy the host still loads — sits beside the directory unseen.
# Report it with its entry count; the creation command refuses on it too.
lg="$root/skill-observations/log.md"
if [ -e "$lg" ]; then
finding "SPLIT STORE — log.md holds $(grep -c '^### Observation ' "$lg" | tr -d ' ') observations not in observation-log/: an older installed copy of the skill still writes the legacy file; name each copy's version, then migrate the remainder (references/migration.md) with ids re-issued from this directory's counter"
fi
# --- the anchors a session lands on: the working directory, the skill install --
# A session that took its root from the working directory (a repository
# root's skill-observations/) or from the skill's own install path
# (~/.agents/skills/<skill> beside ~/.agents/skill-observations/) keeps a
# stable log the pinned root never sees: every scan there is clean, and no
# search of this root's ancestry reaches it. Both places are tested here,
# above the entries, with directory tests only (no search, nothing to
# stall): the working directory, and the resolved skill directory's parent
# and that parent's parent (a skill directory is used only where it holds a
# SKILL.md, so a .bin/ copy's default names no install). One that holds an
# observation-log/ and is not the pinned root is a SPLIT STORE line; paths
# are compared resolved (cd -P), so a symlinked pin is not a second store.
rp() { (cd -P "$1" 2>/dev/null && pwd -P); }
root_r=$(rp "$root"); [ -n "$root_r" ] || root_r=${root%/}
cands="at the working directory|$PWD"
sk_r=$(rp "${skill_dir:-$(dirname "$0")/..}")
if [ -n "$sk_r" ] && [ -f "$sk_r/SKILL.md" ]; then
sk_p=$(dirname "$sk_r")
cands="$cands"$'\n'"beside the skill's install ($sk_r)|$sk_p"$'\n'"beside the skill's install ($sk_r)|$(dirname "$sk_p")"
fi
wa_seen=
while IFS= read -r cand; do
[ -n "$cand" ] || continue
w_r=$(rp "${cand#*|}"); [ -n "$w_r" ] || continue
[ -d "$w_r/skill-observations/observation-log" ] || continue
[ "$w_r" = "$root_r" ] && continue
case $wa_seen in (*"|$w_r|"*) continue ;; esac
wa_seen="$wa_seen|$w_r|"
w_n=$(find "$w_r/skill-observations/observation-log" -maxdepth 1 -name '[0-9]*.md' | wc -l | tr -d ' ')
w_lc=none; [ -f "$w_r/skill-observations/checkpoints.log" ] && w_lc=$(tail -n 1 "$w_r/skill-observations/checkpoints.log" | cut -c 1-10)
case $w_lc in ([0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9]) ;; (*) w_lc=none ;; esac
finding "SPLIT STORE — a second observation log at $w_r ($w_n entries, last scan $w_lc), ${cand%%|*}, not the pinned root $root: a session that took its root from there writes entries this root never sees; report both roots and ask, never consolidate or re-anchor from this scan (references/environments.md, \"Before creating a log, search for one\")"
done <<< "$cands"
# The pre-3.0 staging root: an upgrade never moves it, and rounds staged
# there are invisible to a review that reads [workspace]/skill-updates/.
# The staging root step 6 reads sits BESIDE skill-observations/, never inside
# it: one line says what is there, read from the root once, so a session
# never resolves it one level off.
ls_old="$root/skill-observations/skill-updates"
su="$root/skill-updates"
su_n=0; [ -d "$su" ] && su_n=$(find "$su" -mindepth 1 -maxdepth 1 -type d | wc -l | tr -d ' ')
if [ -f "$su/PENDING.md" ]; then printf 'staged: manifest at %s/PENDING.md (%s non-blank lines), %s directories under it\n' "$su" "$(grep -c . "$su/PENDING.md" | tr -d ' ')" "$su_n"
elif [ -d "$su" ]; then printf 'staged: no manifest at %s/PENDING.md, %s directories under it\n' "$su" "$su_n"
else printf 'staged: no skill-updates/ at %s/\n' "$root"; fi
if [ -d "$ls_old" ] && [ -d "$su" ]; then
finding "NOTE: SPLIT STAGING — staged work under both $su/ and skill-observations/skill-updates/ ($(find "$ls_old" -mindepth 1 -maxdepth 1 -type d | wc -l | tr -d ' ') round directories); step 6 reads only the first: move the legacy rounds and their PENDING entries into it by hand, then remove the legacy root"
elif [ -d "$ls_old" ]; then
finding "NOTE: legacy staging root skill-observations/skill-updates/ exists ($(find "$ls_old" -mindepth 1 -maxdepth 1 -type d | wc -l | tr -d ' ') round directories) — 3.0+ pins [workspace]/skill-updates/; move its rounds and their PENDING entries by hand, then remove it"
fi
# --- pointer: skill-observations/MOVED.md marks a root as abandoned ------------
# Left by a consolidation or a re-anchor (references/environments.md, "Before
# creating a log, search for one"). A session still anchored here is the one
# that has to see it, and nothing else in the protocol lists the root. Data,
# not an order: report it, with how many entries were written here after it.
mv_ptr="$root/skill-observations/MOVED.md"
if [ -f "$mv_ptr" ]; then
mv_line=$(head -n 1 "$mv_ptr" | tr -d '\r' | cut -c 1-200)
mv_after=$(find "$d" -maxdepth 1 -name '[0-9]*.md' -newer "$mv_ptr" 2>/dev/null | wc -l | tr -d ' ')
finding "NOTE: pointer at this root (skill-observations/MOVED.md): \"$mv_line\" — $mv_after entries written here since it; report both roots and ask, never consolidate or re-anchor on it"
fi
# --- review: the age of the last review, printed on every run ----------------
# GAP says whether the protocol kept running; this line says whether the
# review did. A capture loop whose processing step stops keeps logging, and
# nothing else at session start shows the backlog ageing. Days since
# last-review-date.txt, and the open entries dated after it or undated (an
# entry with no status: is open, as reviews read it): entries no review has
# seen. A plain line, not a finding: Session Start step 3 decides whether
# the review is due.
rvd=$(sed '1!d' "$root/skill-observations/last-review-date.txt" 2>/dev/null | tr -d '\r' | cut -c 1-40)
case $rvd in ([0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9]*) since=${rvd%"${rvd#??????????}"} ;; (*) since= ;; esac
unrev=$(LC_ALL=C find "$d" -maxdepth 1 -name '[0-9]*.md' -exec awk -v since="$since" '
function val(s) { sub(/^[a-z_]+:[[:space:]]*/, "", s); sub(/[[:space:]]+#.*$/, "", s); gsub(/["\047\r[:space:]]/, "", s); return s }
FNR==1 {sub(/^\357\273\277/, ""); fm=/^---[[:space:]]*$/; st=""; dt=""; if (!fm) nextfile; next}
fm && /^---[[:space:]]*$/ {if ((st == "" || st == "open") && (since == "" || dt == "" || dt > since)) print FILENAME; nextfile}
fm && /^status:/ {st=val($ 0)}
fm && /^date:/ {dt=substr(val($ 0), 1, 10)}' {} + | wc -l | tr -d ' ')
if [ -n "$since" ]; then
rage=$(LC_ALL=C awk -v today="$(date +%F)" -v last="$since" '
function dn(s, y, m, d) { y = substr(s, 1, 4) + 0; m = substr(s, 6, 2) + 0; d = substr(s, 9, 2) + 0
if (m < 3) { y--; m += 12 }
return 365 * y + int(y / 4) - int(y / 100) + int(y / 400) + int((153 * (m - 3) + 2) / 5) + d }
BEGIN { print dn(today) - dn(last) }')
printf 'review: last %s, %s days ago; %s open entries dated after it or undated, never reviewed\n' "$since" "$rage" "$unrev"
elif [ "$rvd" = never ]; then
printf 'review: none recorded (last-review-date.txt reads never); %s open entries, never reviewed\n' "$unrev"
else
printf 'review: last-review-date.txt absent or not a date (read "%s"); %s open entries\n' "${rvd:-}" "$unrev"
fi
# --- gap: days since the previous session-start scan --------------------------
# Read before this run's trace line is appended. The previous scan's date is
# the last day a session ran the protocol; a gap of 7 days or more (the
# review interval) while the user kept working is the one sign a skill that
# stopped being activated can leave: the sessions in between never reached
# the step that would say so. Day numbers come from awk, so no `date -d`
# (GNU) or `date -j` (BSD) is needed. No earlier scan line: no note.
ck="$root/skill-observations/checkpoints.log"
gap=$( [ -f "$ck" ] && LC_ALL=C awk -v today="$(date +%F)" '
function dn(s, y, m, d) { y = substr(s, 1, 4) + 0; m = substr(s, 6, 2) + 0; d = substr(s, 9, 2) + 0
if (m < 3) { y--; m += 12 }
return 365 * y + int(y / 4) - int(y / 100) + int(y / 400) + int((153 * (m - 3) + 2) / 5) + d }
/ session-start scan:/ && /^[0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9]/ { last = substr($ 0, 1, 10) }
END { if (last != "") { g = dn(today) - dn(last); if (g >= 7) print last " " g } }' "$ck")
[ -n "$gap" ] && finding "GAP: the previous session-start scan ran ${gap% *}, ${gap#* } days ago. If work happened in between, the skill was not activated in those sessions: check the activation instruction (references/environments.md, \"Verify activation in a NEW session\")"
# --- the trace: one line per session, with date, time and source -------------
printf '%s [%s] session-start scan: files=%s parsed=%s principles=%s\n' "$(date '+%F %H:%M')" "${PWD##*/}" "$n" "$parsed" "$pr" \
>> "$root/skill-observations/checkpoints.log"
# --- the session-start record: the checklist items this scan can measure ----
# The Session Start checklist is recorded in the log, not in the agent's
# reply: a reply the user cannot act on costs their attention, and a run
# nobody reads (scheduled, delegated) leaves no reply to check. The items a
# script can measure are written here, one line per session, to
# skill-observations/session-starts.log, and printed; the review's Step 1
# checks every session that loaded the skill left one. Items 4 (activation)
# and 5 (concurrency) are judgements: the session appends them as its own line.
rv=$(sed '1!d' "$root/skill-observations/last-review-date.txt" 2>/dev/null | tr -d '\r'); rv=${rv:-absent}
rs=$(sed '1!d' "$root/skill-observations/review-started.txt" 2>/dev/null | tr -d '\r' | cut -c 1-40); rs=${rs:-absent}
if [ -f "$su/PENDING.md" ]; then sg="manifest $(grep -c . "$su/PENDING.md" | tr -d ' ') lines, $su_n dirs"
elif [ -d "$su" ]; then sg="no manifest, $su_n dirs"; else sg="none"; fi
rec=$(printf '%s [%s] session start: 1 storage=%s 2 scan=files %s parsed %s 3 review=last %s, marker %s 6 staged=%s 7 log=%s entries; 4-5 appended by the session' \
"$(date '+%F %H:%M')" "${PWD##*/}" "${miss:+missing: $miss}" "$n" "$parsed" "$rv" "$rs" "$sg" "$n")
rec=${rec/1 storage= /1 storage=ok }
printf '%s\n' "$rec" >> "$root/skill-observations/session-starts.log"
printf '%s\n' "$rec"
# --- content: printed with the headers below ---------------------------------
# The active principles' headings.
[ -f "$p" ] && awk "$pa"' a && /^### / {sub(/\r$/, ""); print}' "$p"
# Every numbered entry, one awk for the whole set over the directory's own
# glob (no word splitting of a spaced path). This is the only half a content
# classifier can refuse, so everything above has already run when it is.
# Step 2 holds four fields per entry, so the print carries those four and
# the id, one line each; the whole headers (about five times the bytes at a
# few hundred entries — enough for a session to cut the output) go to the
# headers file. With --entries-to, the listing goes to that file: a failed
# redirect skips the print and surfaces as the content print's exit status.
headers="$root/skill-observations/last-scan-headers.txt"
print_headers() {
( export LC_ALL=C; [ "$n" -eq 0 ] || { cd "$d" && awk 'FNR==1 && NR>1 && fm {print "---"}
FNR==1 {sub(/^\357\273\277/, ""); fm=/^---[[:space:]]*$/; print "# " FILENAME; if (!fm) {print "---"; nextfile}; next}
fm && /^---[[:space:]]*$/ {fm=0; print "---"; nextfile}
fm
END {if (fm) print "---"}' [0-9]*.md; } )
}
print_entries() {
( export LC_ALL=C; [ "$n" -eq 0 ] || { cd "$d" && awk -v skip="$res" 'function v(k) { if (k in bl) return "[" f[k] "]"; return (k in f && f[k] != "") ? f[k] : "-" }
function emit( l, s) { l = v("id") " | " v("status") " | " v("skill") " | " v("proposes_skill") " | " v("title")
s = f["status"]; gsub(/["\047[:space:]]/, "", s)
if (s ~ /^(actioned|declined|superseded)$/) l = v("id") " | " s " | " v("skill") " | " v("proposes_skill") " | resolved " v("resolved") " — title withheld"
if (s == "parked") pk = pk l "\n"; else print l }
FNR==1 {if (NR>1 && fm) print "--- " prev " (header not closed)"; split("", f); split("", bl); key = ""; prev = FILENAME
if (skip != "" && index(skip, "/" FILENAME "/")) {fm=0; nextfile}
sub(/^\357\273\277/, ""); fm=/^---[[:space:]]*$/; if (!fm) {print "--- " FILENAME " (no header)"; nextfile}; next}
fm {sub(/\r$/, "")}
fm && /^---[[:space:]]*$/ {fm=0; emit(); nextfile}
fm && /^[A-Za-z_]+:/ {key=$0; sub(/:.*/, "", key); x=$0; sub(/^[A-Za-z_]+:[[:space:]]*/, "", x); sub(/[[:space:]]+$/, "", x); if (x !~ /^["\047]/) sub(/[[:space:]]+#.*$/, "", x); f[key]=x; next}
fm && key != "" && f[key] == "" && /^[[:space:]]+-[[:space:]]/ {bl[key]=1}
fm && key in bl && /^[[:space:]]+-[[:space:]]/ {x=$0; sub(/^[[:space:]]+-[[:space:]]*/, "", x); f[key] = (f[key] == "" ? x : f[key] ", " x); next}
END {if (fm) print "--- " prev " (header not closed)"; printf "%s", pk}' [0-9]*.md; } )
}
hd_note="$headers"
print_headers > "$headers" 2>/dev/null || hd_note="$headers (write failed)"
if [ -n "$entries" ]; then
print_entries > "$entries"; rc=$?
ent="; entries written to $entries"
# A zero-line entries file beside files: N > 0 is a broken run, not an
# empty log: said in the summary block and the sidecar, and the exit is 3.
if [ "$rc" -eq 0 ] && [ "$n" -gt 0 ] && [ ! -s "$entries" ]; then
findings="${findings}NOTE: entries file '$entries' is empty beside files: $n — a broken run, not an empty log; re-run the scan into a new mktemp file"$'\n'
rc=3; empty_ent=1
fi
else
print_entries; rc=$?
ent=
fi
# --- sibling logs: every observation log at the plausible anchors ----------
# Run AFTER the entries, and bounded: on a root whose parent is the home
# folder (a ~/.claude workspace) the unbounded walk read the whole home tree
# five levels deep before a single entry printed, and a stalled walk held
# the scan. So the output so far is flushed to stdout and the findings to
# the sidecar first, and the search runs in the background under a time
# limit (TASK_OBSERVER_SEARCH_SECONDS, default 10; bash's SECONDS and a
# polled kill, since stock macOS has no `timeout`); a search cut at the
# limit is a NOTE naming the anchor it was in and how many it never reached.
# A report, never a reason to consolidate from here. One directory's ancestry
# cannot see a store kept at another scope, so the anchors are the homes
# references/environments.md names: the root's parent (the root, its
# siblings, a renamed folder), the parent's siblings, the user-scope config
# home (~/.claude, and CLAUDE_CONFIG_DIR when set) and its projects/ (the
# project identity roots and their memory/ directories). The parent keeps
# five levels (a log one project folder below a projects folder, with
# margin) — four, no margin, where the parent is the home folder, the folder
# of homes or / (a ~/.claude workspace), with Library and .Trash pruned there
# and the parent's siblings (other users' homes) skipped; every other anchor is searched to a workspace two folders
# below it; .git, node_modules and skill-updates trees are pruned. The
# parent's siblings are skipped when the parent is a top-level directory (its
# siblings are system trees). A workspace
# holding only a legacy log.md is listed too. Each log carries its entry
# count (`-` without the directory), its checkpoints.log's last date, so a
# shard still being written reads differently from an abandoned one, and
# legacy=N for a log.md beside it: the split-store check reads every log
# found, and another root's split store is a finding of its own. Finding
# lines from here print below the entries, beside the listing, and are
# repeated and written to the sidecar with every other.
printf '%s' "$findings" > "$sidecar" 2>/dev/null # provisional: a run stopped in the search keeps its findings on disk
if [ -n "$buf" ]; then
by0=$(wc -c < "$buf" | tr -d ' '); cat "$buf" >&5; : > "$buf"
fi
par=$(dirname "${root%/}"); anchors="$par"
par_r=$(rp "$par"); [ -n "$par_r" ] || par_r=$par
home_r=; [ -n "${HOME:-}" ] && home_r=$(rp "$HOME")
shallow=
# the parent is the home folder, the folder of homes above it, or the filesystem root
case $par_r in (/|"${home_r:-/}"|"$(dirname "${home_r:-/}")") shallow=1 ;; esac
gp=$(dirname "$par")
case $gp in
(/|.|[A-Za-z]:|[A-Za-z]:[/\\]) ;;
(*) [ -n "$shallow" ] || for s_a in "$gp"/*; do [ -d "$s_a" ] && [ "$s_a" != "$par" ] && anchors="$anchors"$'\n'"$s_a"; done ;;
esac
for c_a in "${CLAUDE_CONFIG_DIR:-}" "${HOME:+$HOME/.claude}"; do
[ -n "$c_a" ] && anchors="$anchors"$'\n'"${c_a%/}"$'\n'"${c_a%/}/projects"
done
lim=${TASK_OBSERVER_SEARCH_SECONDS:-10}; case $lim in (""|*[!0-9]*|0) lim=10 ;; esac
tf=$(mktemp 2>/dev/null) || tf=
found=; srch=
if [ -z "$tf" ]; then
finding "NOTE: sibling-log search skipped — no mktemp for its bounded run; the 'logs at the plausible anchors' line is empty, not 'no other log': search the anchors by hand before creating or consolidating a log (references/environments.md, \"Before creating a log, search for one\")"
else
# The search, in a background subshell: each anchor's find runs as its own
# job and is waited on, so the TERM sent at the limit interrupts the wait
# and the trap kills that find. `#A <anchor>` marks each anchor's start and
# `#END` a search that finished.
( fp=; trap 'kill "${fp:-}" 2>/dev/null; exit 0' TERM
while IFS= read -r a; do
[ -n "$a" ] && [ -d "$a" ] || continue
md=4; pr_x=
if [ "$a" = "$par" ]; then md=5; [ -n "$shallow" ] && { md=4; pr_x=1; }; fi
printf '#A %s\n' "$a" >> "$tf"
if [ -n "$pr_x" ]; then
find "$a" -maxdepth "$md" \( -name .git -o -name node_modules -o -name skill-updates -o -name Library -o -name .Trash \) -prune \
-o \( -type d -path '*/skill-observations/observation-log' -o -type f -path '*/skill-observations/log.md' \) -print >> "$tf" 2>/dev/null &
else
find "$a" -maxdepth "$md" \( -name .git -o -name node_modules -o -name skill-updates \) -prune \
-o \( -type d -path '*/skill-observations/observation-log' -o -type f -path '*/skill-observations/log.md' \) -print >> "$tf" 2>/dev/null &
fi
fp=$!; wait "$fp"; fp=
done <<< "$anchors"
printf '#END\n' >> "$tf" ) &
spid=$!; dl=$((SECONDS + lim)); zz=0.01 # the poll starts short: an ordinary search ends in milliseconds
while kill -0 "$spid" 2>/dev/null; do
if [ "$SECONDS" -ge "$dl" ]; then kill -TERM "$spid" 2>/dev/null; break; fi
sleep "$zz" 2>/dev/null || sleep 1
case $zz in (0.01) zz=0.03 ;; (0.03) zz=0.1 ;; esac
done
wait "$spid" 2>/dev/null
# Each found workspace is resolved (rp, as for the split-store check) before
# the dedup, so two spellings of one directory — a drive-letter and an MSYS
# path, a symlinked home — are one log; the pinned root keeps its own spelling.
found=$(grep -v '^#' "$tf" | sed 's|/skill-observations/observation-log$||; s|/skill-observations/log\.md$||' |
while IFS= read -r w; do
w_r=$(rp "$w"); [ -n "$w_r" ] || w_r=$w
[ "$w_r" = "$root_r" ] && w_r=${root%/}
printf '%s\n' "$w_r"
done | LC_ALL=C sort -u)
if ! grep -q '^#END$' "$tf"; then
cut_a=$(sed -n 's/^#A //p' "$tf" | tail -n 1)
n_all=$(printf '%s\n' "$anchors" | while IFS= read -r a; do [ -n "$a" ] && [ -d "$a" ] && echo x; done | wc -l | tr -d ' ')
n_done=$(grep -c '^#A ' "$tf" | tr -d ' ')
finding "NOTE: sibling-log search stopped at its ${lim}-second limit while searching ${cut_a:-the first anchor} ($((n_all - n_done)) more anchor(s) never searched) — the 'logs at the plausible anchors' line is partial, not 'no other log': search there by hand before creating or consolidating a log (references/environments.md, \"Before creating a log, search for one\"); TASK_OBSERVER_SEARCH_SECONDS raises the limit"
fi
rm -f "$tf"
fi
[ -n "$shallow" ] && srch="; the home folder as parent: searched 4 levels, Library and .Trash pruned"
sib=
while IFS= read -r w; do
[ -n "$w" ] || continue
o="$w/skill-observations/observation-log"; w_lg="$w/skill-observations/log.md"; w_ck="$w/skill-observations/checkpoints.log"
cnt=-; [ -d "$o" ] && cnt=$(find "$o" -maxdepth 1 -name '[0-9]*.md' | wc -l | tr -d ' ')
lc=none
[ -f "$w_ck" ] && lc=$(tail -n 1 "$w_ck" | cut -c 1-10) && case $lc in ([0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9]) ;; (*) lc=none ;; esac
lgn=; [ -f "$w_lg" ] && lgn=$(grep -c '^### Observation ' "$w_lg" | tr -d ' ')
sib="$sib $w=$cnt last=$lc${lgn:+ legacy=$lgn}"
# the pinned root's own split store is the SPLIT STORE line above
if [ -n "$lgn" ] && [ -d "$o" ] && [ "$w" != "${root%/}" ]; then
finding "SPLIT STORE — $w: log.md holds $lgn observations beside that root's observation-log/: an older installed copy still writes there; report the root and its copy's version, never migrate or consolidate another root from this scan (references/migration.md)"
fi
done <<< "$found"
printf 'logs at the plausible anchors (report; never consolidate from here%s):%s\n' "$srch" "$sib"
# --- LAST: the summary block — the findings again, then the end-of-scan line -
# The finding lines are repeated here VERBATIM, after the entries, and written
# to the sidecar file (overwritten every run; empty when there are none): a
# view cut to its last lines, or a grep over the end, still carries every
# finding, and a run that cut the output anyway finds them on disk. The end
# line repeats the counts, says how many finding lines stand above the
# entries, and names the sidecar; it is a pointer to the whole output, never
# its replacement.
sc="$sidecar"
printf '%s' "$findings" > "$sidecar" 2>/dev/null || sc="$sidecar (write failed)"
printf '%s' "$findings"
st=; [ "$rc" -eq 0 ] || st="; content print exited $rc"
[ -n "${empty_ent:-}" ] && st="; the entries file is EMPTY (exit 3)"
bytes="bytes above this line not counted (no mktemp)"
if [ -n "$buf" ]; then
by=$(( by0 + $(wc -c < "$buf" | tr -d ' ') ))
exec >&5; cat "$buf"; rm -f "$buf"; trap - EXIT
bytes="$by bytes above this line: a saved or cut copy holding fewer is a truncated scan"
fi
printf 'end of scan — files: %s parsed: %s suspect: %s archive-suspect: %s resurrected: %s principles: %s; finding lines above the entries (DUE / NOTE / LOST ENTRIES / UNFILLED / DUPLICATE ID / RESURRECTED / SPLIT STORE / GAP): %s, repeated just above this line and written to %s%s%s; full headers in %s; %s. Read the output whole: never cut it with head, tail or grep — session-start-scan.sh v%s\n' \
"$n" "$parsed" "$suspect" "$a_sus" "$nres" "$pr" "$fx" "$sc" "$ent" "$st" "$hd_note" "$bytes" "$VERSION"
exit "$rc"
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |