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/validate-skill-bundle.py
View on GitHub#!/usr/bin/env python3
"""
validate-skill-bundle.py — the pre-delivery gate, as assertions.
Checks a staged skill directory (and optionally its packed .skill bundle)
against the criteria the INSTALLER enforces, not against what seems
sensible. Every check compares a measurement to a bound in the same step:
an unasserted metric manufactures confidence that no defect exists.
Usage
-----
python3 validate-skill-bundle.py <staged-skill-dir> [--live <live-skill-dir>] [--bundle file.skill] [--pack out.skill]
python3 validate-skill-bundle.py [--live <live-skill-dir>] [--repo <repo-dir>] <staged-skill-dir> # options in any order
python3 validate-skill-bundle.py --repo-only <repo-dir>
python3 validate-skill-bundle.py --selftest # check fixtures and the scan script; exit 1 on any mismatch
python3 validate-skill-bundle.py --compare-frontmatter <live/SKILL.md> <staged/SKILL.md>
python3 validate-skill-bundle.py --help # print this usage block; exit 0 (also -h)
--compare-frontmatter the reconciliation gate's installed-vs-staged
compare: frontmatter by parsed value (installer quoting and
folding ignored), body byte for byte. Exit 0 = equal, 1 = a
real difference (named), 2 = unreadable input.
--pack writes a well-formed bundle (POSIX separators on any platform)
after the directory checks pass, then validates it. An
unquoted frontmatter `name:` is rewritten to the quoted form
in the staged SKILL.md first, so the packed copy carries it.
The written bundle must round-trip: its members are exactly
the directory's files (build artefacts excluded), each equal
byte for byte to what the packer wrote and to the file on
disk; any mismatch fails the run (exit 1).
--live the installed skill directory the staged copy was made from:
every regular file in it must be in the staged set (VCS
metadata, build artefacts and a checkout's .claude-plugin/
excepted at any depth), so a copy staged as SKILL.md alone
fails. Not a directory = skipped, one note.
Options and the one skill directory may come in any order; each of
--live, --bundle, --pack and --repo takes the next argument. An option
without its value, an unknown option or a second directory is a usage
error (exit 2), never a skipped check.
--repo additionally check the repo's manifests against the skill.
--repo-only check ONLY the repo's manifests, skipping the skill checks.
Also runs the markdown shape check over the repo-root .md
files (README, guides): a blank line splitting one list in
two is reported as a failure with file:line.
Why --repo-only exists: in a repo whose root IS the skill directory
(`SKILL.md` at the top level), the two check sets contradict each other.
The skill checks require the directory name to equal the frontmatter `name`
and forbid a plugin manifest; the repo is named after the repository, not
the skill, and is the one place the manifest belongs. Running the skill
checks over a repo root therefore reports two failures that are both
correct behaviour. Point the skill checks at the staged skill directory and
`--repo-only` at the repo.
Exit status 0 = every check passed; 1 = at least one failed (all failures
are listed, not just the first).
Limits are stated as numbers and labelled with where they come from, so
the check is implementable without guessing and can be updated when the
consumer changes them.
"""
import contextlib as _ctx
import io as _io
import pathlib
import re
import struct
import sys
import tempfile
import zipfile
MAX_DESCRIPTION_CHARS = 1024 # installer's documented cap on the folded description
NAME_RE = re.compile(r"^[a-z0-9]+(-[a-z0-9]+)*$") # kebab-case
SEMVER_RE = re.compile(r"^\d+\.\d+\.\d+$")
# --- Core-size ratchet -------------------------------------------------------
# The per-session core is loaded in full, every session, by every consumer of
# the skill. It has grown before: a split brought it down and two months of
# ordinary review rounds put it back, because nothing in the loop pushed the
# other way. A guideline that is only prose loses to a hundred individually
# reasonable additions.
#
# CEILING ONLY EVER GOES DOWN. Raising it is not a fix for a failing gate; it
# is the failure. A release that needs more room in the core needs a split
# instead, and the reference files are where the room is. The number below is
# the high-water mark at the release that introduced this check — every later
# release either holds it or lowers it.
#
# TARGET is the size the core is trying to reach. The gap between CEILING and
# TARGET is reported on every run, passing or failing, so the debt stays
# visible rather than being rediscovered by a contributor with a line counter.
# The ceiling is a property of the SKILL, not of this script. It is read from
# the skill under test — `core_max_lines:` in SKILL.md frontmatter (top
# level, or one level under `metadata:`, the spec-conformant form), or a
# `.core-ceiling` file beside it holding the number. A skill that declares
# neither has not opted in: the count is reported and nothing is gated. This
# script ships inside task-observer but is run against every skill in a
# library, and a constant that describes one skill must never bound another.
#
# The ceiling also FOLLOWS the core down. A check that only blocks growth
# leaves every trim as open headroom, and the next ordinary additions spend it
# without anyone deciding to. So a declared ceiling more than
# CEILING_SLACK_TOLERANCE lines above the core fails too; the fix is to lower
# the declared number to the current count in the same commit as the trim.
CORE_CEILING_FILE = ".core-ceiling"
CORE_CEILING_KEY = "core_max_lines"
CEILING_SLACK_TOLERANCE = 3
TARGET_CORE_LINES = 500
# No net growth across releases. A ceiling that may be raised with a reason
# records growth instead of preventing it: every raise is locally justified,
# and the sum only goes up. So a skill may also declare the ceiling its last
# RELEASE shipped, as `# released core ceiling: N (<version>)` in
# references/ceilings.txt; a declared ceiling above it fails until the core is
# paid back by moving text out to a reference file in the same release. The
# release that merges writes its own ceiling into that line. Absent line: not
# gated, as for a skill that declares no ceiling at all.
RELEASED_CEILING_RE = re.compile(r"^#\s*released core ceiling:\s*(\d+)", re.M)
PATH_RE = re.compile(r"`((?:references|scripts|assets)/[^`\s*?]+\.[A-Za-z0-9]+)`")
# A path the agent EXECUTES rarely fills a whole backtick span: it sits after
# an interpreter, with arguments behind it, inline or in a fenced block, and
# PATH_RE never extracts it. So code is also split into commands, and an
# unqualified bundled path counts when the token before it is an interpreter.
# A bare path with no interpreter stays unchecked, which keeps a quoted
# example (`scripts/x/generate.py --logo ...`) out. Measured over 127 local
# skills: 28 hits, 0 missing, no normalisation needed.
CMD_PATH_RE = re.compile(r"(?:references|scripts|assets)/[^\s`'\"*?<>;|&]+\.[A-Za-z0-9]+")
CMD_INTERP = {"python3", "python", "py", "bash", "sh", "zsh", "node", "swift", "ruby", "perl", "run", "source"}
# A placeholder segment in a cited path — `<study>` or `{study}`, never
# spanning a `/` — marks a naming pattern, checked as a glob (check_dir).
SLOT_SEG_RE = re.compile(r"<[^<>/\s]+>|\{[^{}/\s]+\}")
# An interpreter's own options sit between it and the script: `py -3 x.py`
# (the Windows launcher, which migration.md recommends where `python3` is the
# Store alias), `python3 -X utf8 x.py`, `bash -eu x.sh`. Reading only the
# token right after the interpreter missed every one. Per family: options
# that take no value, options whose value is the next token, and options
# after which the next token is not a script at all (`-m`, `-c`), so nothing
# is checked. Other interpreters keep the token-right-after rule: their
# option grammars are not tabled here.
CMD_OPTS = {
"python": (re.compile(r"-[bBdEiIOPqRsSuvx]+|-[0-9]+(\.[0-9]+)?(-(32|64))?|-[XW]\S+"),
{"-X", "-W"}, re.compile(r"-[bBdEiIOPqRsSuvx]*[mc]\S*|-")),
"shell": (re.compile(r"[-+][aefhiklnpuvxBCEHPT]+|--(norc|noprofile|login|posix|verbose|noediting|restricted)"),
{"-o", "+o", "-O", "+O", "--rcfile", "--init-file"}, re.compile(r"-[a-zA-Z]*c[a-zA-Z]*|-s|-")),
}
CMD_FAMILY = {"python3": "python", "python": "python", "py": "python", "bash": "shell", "sh": "shell", "zsh": "shell"}
BUILD_JUNK = {"__pycache__", ".DS_Store"}
# Version-control metadata: a live skill can be a clone, a staged copy must
# not be. The other checks ask what is MISSING; this one asks what is there
# that should not be (a clone packed its whole history and passed).
VCS_DIRS = {".git", ".hg", ".svn"}
# A skill installed as a repository checkout carries the repository's plugin
# manifests, at its root and in any plugin directory below it; a skill bundle
# must not, so the live-set check does not ask the staged copy for them at any
# depth (as the compare snippet's `diff -x` and scripts/diff-staged.sh do).
CHECKOUT_ONLY = {".claude-plugin"}
# Edit residue: strings that only ever enter a file through a failed
# replacement, an unresolved template slot or an unfinished merge. The gate
# checks bundle FORM; this is the one CONTENT assertion, because a literal
# backreference passed apply, gate and install once.
SLOT_WHY = "unresolved template slot"
RESIDUE_RES = [
(re.compile(r"(?m)^\\[0-9]\s*$"), "literal regex backreference on its own line"),
(re.compile(r"(?<![\w`])\\[1-9](?![\w])"), "literal regex backreference in prose"),
(re.compile(r"(?m)^(<<<<<<<|=======|>>>>>>>)( |$)"), "merge conflict marker"),
(re.compile(r"\{\{[A-Za-z_][A-Za-z0-9_ .-]*\}\}"), SLOT_WHY),
(re.compile(r"\b(TODO|FIXME|XXX)\b: ?(fill|replace|write)", re.I), "placeholder note left in"),
]
# A file that IS a template carries its slots as the deliverable, not as
# residue: exempt it from the SLOT rule only — every other residue rule and
# every other gate check still runs on it, so the exemption never becomes the
# hand-zip that also skips the checks nobody questioned.
TEMPLATE_MARKER = "<!-- template: slots intentional -->"
def slots_are_intentional(path, body):
return "template" in str(path).lower() or body.lstrip().startswith(TEMPLATE_MARKER)
# The first block ends at its FIRST closing `---` line; the lookahead stops
# `.*?` from running on to a later pair of horizontal rules in the body.
SECOND_FRONTMATTER_RE = re.compile(r"^---\n(?:(?!\n---\n).)*?\n---\n\s*(---\n|name:|description:)", re.S)
def frontmatter(text):
m = re.match(r"^---\n(.*?)\n---\n", text, re.S)
return m.group(1) if m else None
def frontmatter_version(fm):
"""The skill's version from a frontmatter block, or None: `metadata.version`
(one level under `metadata:`, the form this skill carries), else a
top-level `version:` (other skills and older installs still carry it).
Either quote style is stripped."""
parent = None
for line in (fm or "").splitlines():
if re.match(r"^\S", line):
pm = re.match(r"^([A-Za-z_][\w-]*):", line)
parent = pm.group(1) if pm else None
continue
km = re.match(r"""^[ \t]+version:[ \t]*["']?([^"'\s]+)["']?[ \t]*$""", line)
if km and parent == "metadata":
return km.group(1)
top = re.search(r"""(?m)^version:[ \t]*["']?([^"'\s]+)["']?[ \t]*$""", fm or "")
return top.group(1) if top else None
# (name, frontmatter body, version read)
VERSION_READ_FIXTURES = [
("metadata.version, quoted, is read", 'name: x\nmetadata:\n author: a\n version: "1.2.0"\n', "1.2.0"),
("a top-level version: (older install) is still read", "name: x\nversion: 1.2.0\n", "1.2.0"),
("version nested under another parent is not read", "name: x\nother:\n version: 1.2.0\n", None),
("no version: None", "name: x\n", None),
]
def folded_description(fm):
"""The description as the installer sees it, for both YAML block styles.
Folded (`>`) joins its lines with spaces; literal (`|`) keeps the line
breaks. Both accept a chomping indicator (`-`, `+`) and an explicit indent
digit. Matching only `>` meant a `|` description fell through to the
single-line branch below, which measured the string "|" — one character,
inside every cap by construction, so the gate reported a pass having
measured nothing at all. Any block style must be recognised here or the
length check silently stops being a length check.
"""
m = re.search(r"(?ms)^description:\s*([>|])[-+]?\d?\s*\n(.*?)(?=^\S|\Z)", fm)
if m:
body = m.group(2)
if m.group(1) == ">":
return " ".join(body.split())
return "\n".join(line.strip() for line in body.strip("\n").splitlines())
m = re.search(r"(?m)^description:\s*(.+)$", fm)
return m.group(1).strip().strip('"\'') if m else ""
def fallback_name(fm):
"""`name` as a YAML parser reads it, for the no-PyYAML branch.
One layer of matching quotes is not part of the value (the template asks
for `name: "x"`), and neither is a trailing comment: PyYAML ends the
value at `#` after a closing quote, and at ` #` after a plain scalar.
Stripping quotes only when the line ENDS in the quote left
`name: 'x' # c` failing here while the parser passed it. A tab
before `#` is a scanner error to PyYAML, so it is left in and fails too.
"""
raw = (re.search(r"(?m)^name:\s*(.+)$", fm) or [None, ""])[1].strip()
m = re.match(r"""^(["'])([^"'\\]*)\1 *(?:#.*)?$""", raw)
return m.group(2) if m else re.sub(r" +#.*$", "", raw)
# (frontmatter `name:` value, kebab verdict the fallback must give) — each
# pins the fallback to what PyYAML returns for the same line.
FALLBACK_NAME_FIXTURES = [
("x", True), ('"x"', True), ("'x'", True),
("'x' # c", True), ('"x" # c', True), ("x # c", True), ("'x'#c", True),
("x#c", False), ("'a #b' # c", False), ("x\t# c", False), ("'x'y", False),
]
# --- Installed-vs-staged frontmatter comparison ------------------------------
# The installer rewrites the frontmatter it writes back: it quotes or unquotes
# `name:`, re-quotes `version: 1.5.0` as `version: '1.5.0'`, and turns a folded
# `description: >` block into one double-quoted line. A text diff reports every
# such copy as differing, and a normaliser that covers only some of those
# rewrites turns the rest into routine false alarms — which train the reader
# to wave real differences through. So the comparison is by PARSED VALUE: both
# headers are parsed with every scalar kept as a string (PyYAML's BaseLoader,
# so `1.5.0` and '1.5.0' are the same value and nothing is type-coerced), the
# trailing newline a block scalar carries is stripped, and the body after the
# closing `---` is compared byte for byte. Without PyYAML the fallback below
# reads top-level keys only and says so.
def split_skill_md(text):
"""(frontmatter text, body after the closing `---` line), or (None, text)."""
m = re.match(r"^---\n(.*?)\n---\n", text, re.S)
return (m.group(1), text[m.end():]) if m else (None, text)
def _unquote(raw):
"""One YAML flow scalar as the parser returns it: quotes and escapes
resolved, a trailing comment dropped from a plain scalar."""
raw = raw.strip()
if len(raw) >= 2 and raw[0] == raw[-1] == '"':
return re.sub(r'\\(["\\n/])', lambda m: "\n" if m.group(1) == "n" else m.group(1), raw[1:-1])
if len(raw) >= 2 and raw[0] == raw[-1] == "'":
return raw[1:-1].replace("''", "'")
return re.sub(r"[ \t]+#.*$", "", raw)
def fallback_fields(fm):
"""Top-level keys of a frontmatter block without PyYAML: flow scalars via
_unquote(), a quoted value continued over several lines folded with
spaces, block scalars (`>`, `|`) via folded_description()'s rules, and a
nested block (indented lines under an empty value) kept as its
whitespace-normalised text. A floor, not a parser: it reads the shapes the
installer writes and the template asks for."""
out, key, buf = {}, None, []
def close():
if key is None:
return
first, rest = buf[0], buf[1:]
if re.match(r"^[>|][-+]?\d?\s*$", first):
out[key] = folded_description("description: " + "\n".join([first] + rest))
elif first[:1] in ('"', "'") and rest:
out[key] = _unquote(" ".join([first] + [r.strip() for r in rest]))
elif not first and rest:
out[key] = " ".join(" ".join(rest).split())
else:
out[key] = _unquote(first)
for line in fm.splitlines():
m = re.match(r"^([A-Za-z_][\w.-]*):(?:[ \t]+(.*))?$", line)
if m:
close()
key, buf = m.group(1), [(m.group(2) or "").strip()]
elif key is not None:
buf.append(line)
close()
return out
def parse_frontmatter_values(fm, use_yaml=True):
"""(dict of top-level key -> value, parser label). Strings lose the
trailing newline(s) a block scalar or an installer's `\\n` carries."""
data, how = None, "fallback (no PyYAML: top-level keys only)"
if use_yaml:
try:
import yaml
# BaseLoader builds only strings, lists and maps (`1.10` stays a
# string, which the compare needs); no load-function call for a scanner to misread.
loader = yaml.BaseLoader(fm)
try:
data = loader.get_single_data()
finally:
loader.dispose()
how = "PyYAML BaseLoader"
except ImportError:
pass
if data is None:
data = fallback_fields(fm)
if not isinstance(data, dict):
raise ValueError("frontmatter does not parse to a mapping")
return {k: (v.rstrip("\n") if isinstance(v, str) else v) for k, v in data.items()}, how
def compare_frontmatter_texts(a, b, use_yaml=True):
"""Compare two SKILL.md texts the way the reconciliation gate needs:
returns (differing frontmatter keys, body equal?, parser label)."""
(fa, ba), (fb, bb) = split_skill_md(a), split_skill_md(b)
if fa is None or fb is None:
raise ValueError("no leading --- frontmatter block")
va, how = parse_frontmatter_values(fa, use_yaml)
vb, _ = parse_frontmatter_values(fb, use_yaml)
keys = sorted(k for k in set(va) | set(vb) if va.get(k) != vb.get(k))
return keys, ba == bb, how
def compare_frontmatter_main(path_a, path_b):
"""--compare-frontmatter A B: exit 0 = same skill text (installer quoting
aside), 1 = a real difference (each one named), 2 = unreadable input."""
try:
ta = pathlib.Path(path_a).read_text(encoding="utf-8")
tb = pathlib.Path(path_b).read_text(encoding="utf-8")
keys, body_equal, how = compare_frontmatter_texts(ta, tb)
except (OSError, ValueError, UnicodeDecodeError) as e:
print(f"compare: cannot compare: {e}"); return 2
except Exception as e: # a YAML error: the file is broken, say so
print(f"compare: frontmatter did not parse: {e}"); return 2
print(f"parser: {how}")
print("frontmatter: equal by value" if not keys
else "frontmatter: DIFFERS in " + ", ".join(keys))
if body_equal:
print("body: equal byte for byte")
else:
la = split_skill_md(ta)[1].splitlines()
lb = split_skill_md(tb)[1].splitlines()
n = next((i for i, (x, y) in enumerate(zip(la, lb)) if x != y), min(len(la), len(lb)))
print(f"body: DIFFERS (first at body line {n + 1}; {len(la)} vs {len(lb)} lines)")
return 0 if not keys and body_equal else 1
_FOLDED = ("---\nname: x\ndescription: >\n One two: three,\n four.\n---\nbody\n")
# (name, text A, text B, frontmatter keys that must differ, body must be equal)
COMPARE_FM_FIXTURES = [
("quoted vs unquoted name", '---\nname: "x"\n---\nbody\n', "---\nname: x\n---\nbody\n", [], True),
("version '1.5.0' vs 1.5.0", "---\nname: x\nversion: '1.5.0'\n---\nb\n",
"---\nname: x\nversion: 1.5.0\n---\nb\n", [], True),
("folded description vs one-line quoted string, same text", _FOLDED,
'---\nname: "x"\ndescription: "One two: three, four.\\n"\n---\nbody\n', [], True),
("a real value change is still reported", "---\nname: x\nversion: 1.5.0\n---\nb\n",
"---\nname: x\nversion: '1.6.0'\n---\nb\n", ["version"], True),
("a body change is still reported", '---\nname: "x"\n---\nbody\n', "---\nname: x\n---\nbody2\n", [], False),
]
def check_frontmatter_shape(fm, fails, yaml_available):
"""Structural checks that do not need PyYAML.
The gate's `frontmatter parses` item degrades to a regex when PyYAML is
absent, and a regex happily accepts a block a YAML parser rejects. The
case that got through: a cosmetic re-wrap turned a single-line
`description:` into a key line followed by UNINDENTED continuation lines.
The body loaded fine, so the defect surfaced only in the client's skill
listing, where the description had been replaced by the H1 title.
So: check the shape here, always, whichever branch ran above — and say
which branch ran, because `OK` from the regex branch and `OK` from the
parser branch are not the same assurance.
"""
in_block = False
for n, line in enumerate(fm.splitlines(), 1):
if not line.strip() or line.lstrip().startswith("#"):
continue
if re.match(r"^[A-Za-z_][\w.-]*:", line):
in_block = bool(re.search(r":\s*[>|][-+]?\d?\s*$", line))
continue
if line[:1].isspace() or line.lstrip().startswith("- "):
continue # indented continuation or list item: fine
if in_block:
# A block scalar's body must be indented. An unindented line ends
# the block, and since it is not a `key:` line either, it is the
# re-wrap defect.
fails.append(
f"frontmatter:{n}: unindented continuation line inside a block "
f"scalar — YAML ends the block here and rejects the rest "
f"({line.strip()[:60]!r})")
else:
fails.append(
f"frontmatter:{n}: line is neither `key: value` nor an indented "
f"continuation ({line.strip()[:60]!r})")
in_block = False
if not yaml_available:
print("note: PyYAML not installed — frontmatter checked structurally, "
"not parsed. Install PyYAML for the stronger check.")
# The top-level frontmatter keys the Agent Skills specification defines, and
# so the set an installer's validator accepts (skill-creator's quick_validate
# rejects any other). Update it when the specification changes.
AGENT_SKILLS_KEYS = ("name", "description", "license", "allowed-tools", "metadata", "compatibility")
# Keys published skills still carry at the top level from before the gate
# checked: reported as warnings until each skill moves them under
# `metadata:` at its next release; any other key fails.
TRANSITIONAL_KEYS = ("version", "core_max_lines", "origin", "maintainer", "author")
def check_top_level_keys(fm, fails):
"""A top-level key outside the Agent Skills set fails the gate, except a
transitional key, which warns naming where it belongs. Read from the
unindented `key:` lines, so it runs with or without PyYAML."""
seen = []
for line in fm.splitlines():
m = re.match(r"^([A-Za-z_][\w.-]*)[ \t]*:", line)
if m and m.group(1) not in seen:
seen.append(m.group(1))
for key in seen:
if key in AGENT_SKILLS_KEYS:
continue
if key in TRANSITIONAL_KEYS:
print(f"warn: frontmatter: top-level key `{key}` is outside the Agent Skills set "
f"({', '.join(AGENT_SKILLS_KEYS)}) — it belongs under `metadata:` as a string "
f"(`metadata.{key}`); accepted until the skill's next release moves it")
else:
fails.append(f"frontmatter: top-level key `{key}` is outside the Agent Skills set "
f"({', '.join(AGENT_SKILLS_KEYS)}), which installers enforce — move it under "
f"`metadata:` as a string")
# (name, frontmatter keys after name/description, fail substring or None, warn substring or None)
TOP_KEY_FIXTURES = [
("a clean header passes with no warning", "license: MIT\nmetadata:\n author: A\n", None, None),
("an unknown top-level key fails, naming metadata:", "requires: [git]\n",
"top-level key `requires` is outside the Agent Skills set", None),
("a transitional key warns, naming where it belongs", "version: 1.2.0\n", None,
"warn: frontmatter: top-level key `version` is outside the Agent Skills set"),
("a key nested under metadata: is not top-level", "metadata:\n version: \"1.2.0\"\n requires: git\n",
None, None),
]
def core_ceiling_value(fm):
"""The raw `core_max_lines` value from a frontmatter block, or None.
Two places are read: the top level, and one level under `metadata:` —
the spec-conformant form, since the Agent Skills spec types `metadata`
as string→string and a top-level key of a skill's own fails its
validators. Top-level wins where both exist; a disagreement is noted
with both values. The key nested under any other parent is not read,
and says so, instead of the plain "not gated" a silent miss printed.
"""
top = re.search(r"(?m)^%s:[ \t]*(\S+)[ \t]*$" % CORE_CEILING_KEY, fm)
meta = None
parent = None
nested_elsewhere = []
for line in fm.splitlines():
if re.match(r"^\S", line):
pm = re.match(r"^([A-Za-z_][\w-]*):", line)
parent = pm.group(1) if pm else None
continue
km = re.match(r"^[ \t]+%s:[ \t]*(\S+)[ \t]*$" % CORE_CEILING_KEY, line)
if km:
if parent == "metadata" and meta is None:
meta = km.group(1)
elif parent != "metadata":
nested_elsewhere.append(parent or "?")
for p in nested_elsewhere:
print(f"note: {CORE_CEILING_KEY} found nested under {p}: — not read "
f"(top level or under metadata: only)")
if top and meta is not None and top.group(1).strip("\"'") != meta.strip("\"'"):
print(f"note: {CORE_CEILING_KEY} is declared twice and they disagree — "
f"top level {top.group(1)!r}, under metadata: {meta!r}; the top-level value is used")
if top:
return top.group(1)
return meta
def read_core_ceiling(skill_md):
"""The skill's own ceiling, or None if it has not declared one.
Two sources, frontmatter first: `core_max_lines: N` in SKILL.md, else a
`.core-ceiling` file beside it containing the number. None means the skill
has not opted in — which is not a failure and must not be treated as one.
A malformed value is also None, and says so, because silently falling back
to some default is how one skill's number ends up bounding another.
"""
text = skill_md.read_text(encoding="utf-8")
m = re.match(r"(?s)^---\n(.*?)\n---\n", text)
if m:
raw = core_ceiling_value(m.group(1))
if raw is not None:
v = raw.strip("\"'") # a quoted number is still the number (spec metadata values are strings)
if v.isdigit():
return int(v)
print(f"note: {CORE_CEILING_KEY} is not a whole number "
f"({raw!r}) — core size not gated")
return None
f = skill_md.parent / CORE_CEILING_FILE
if f.exists():
raw = f.read_text(encoding="utf-8").strip()
if raw.isdigit():
return int(raw)
print(f"note: {CORE_CEILING_FILE} is not a whole number ({raw!r}) — "
f"core size not gated")
return None
def installed_line_count(text):
"""Lines of a SKILL.md as the INSTALLER will see it.
The installer rewrites a block-scalar `description: >` / `|` as one
double-quoted line, so a core staged with a ten-line description loses
nine lines on install: measured on the staged file, the ratchet passed at
staging and failed the installed copy at the next live-set pass, with a
fix (lower the ceiling) that would fail the staged form. So the key line
is counted and its continuation lines are not. Only `description` is
folded this way; every other line counts as `wc -l` counts it.
"""
n = len(text.splitlines())
fm = frontmatter(text)
if fm:
m = re.search(r"(?ms)^description:[ \t]*[>|][-+]?\d?[ \t]*\n(.*?)(?=^\S|\Z)", fm)
if m:
n -= len(m.group(1).splitlines())
return n
# (name, SKILL.md text, lines fewer than `wc -l` the installed count must be)
_FOLDED_DESC = "---\nname: x\ndescription: >\n" + "".join(f" line {i}\n" for i in range(9)) + "---\nbody\n"
CORE_COUNT_FIXTURES = [
("a 10-line folded description counts as one line (9 fewer)", _FOLDED_DESC, 9),
("a literal | description folds the same way", _FOLDED_DESC.replace("description: >", "description: |"), 9),
("a one-line quoted description counts as wc -l does",
'---\nname: x\ndescription: "d"\n---\nbody\n', 0),
("a folded block in the BODY is not a description: nothing folded",
"---\nname: x\n---\ndescription: >\n not frontmatter\n", 0),
]
# (name, frontmatter body, ceiling read, substring the printed notes must hold or None)
CORE_CEILING_FIXTURES = [
("top-level key is read", 'name: x\ncore_max_lines: 10\n', 10, None),
("under metadata:, unquoted, is read", 'name: x\nmetadata:\n author: a\n core_max_lines: 10\n', 10, None),
("under metadata:, quoted (spec values are strings), is read",
'name: x\nmetadata:\n core_max_lines: "10"\n', 10, None),
("nested under another parent: a note, not gated",
'name: x\nother:\n core_max_lines: 10\n', None, "found nested under other: — not read"),
("both present and disagreeing: top level used, both named",
'core_max_lines: 10\nmetadata:\n core_max_lines: "12"\n', 10, "they disagree"),
("both present and equal: no note", 'core_max_lines: 10\nmetadata:\n core_max_lines: "10"\n', 10, ""),
]
RELEASED_CEILING_FIXTURES = [
("a ceiling above the released one fails", 12, 10, True),
("a ceiling equal to the released one passes", 10, 10, False),
("a ceiling below the released one passes", 9, 10, False),
("no released line: not gated", 12, None, False),
]
def core_ceiling_case(fm):
"""read_core_ceiling over a fixture SKILL.md; returns (ceiling, notes)."""
import contextlib
import io
with tempfile.TemporaryDirectory() as td:
p = pathlib.Path(td) / "SKILL.md"
p.write_text("---\n" + fm + "---\nbody\n", encoding="utf-8")
buf = io.StringIO()
with contextlib.redirect_stdout(buf):
got = read_core_ceiling(p)
return got, buf.getvalue()
def read_released_ceiling(skill_md):
"""The core ceiling the skill's last release shipped, or None."""
f = skill_md.parent / "references" / REF_CEILINGS_FILE
if not f.exists():
return None
m = RELEASED_CEILING_RE.search(f.read_text(encoding="utf-8"))
return int(m.group(1)) if m else None
def check_core_size(skill_md, fails):
"""The ratchet, against the skill's OWN declared ceiling.
Counted with splitlines() so the number matches `wc -l` on a
newline-terminated file. Counting newlines and adding one reports 755 for
a 754-line file, which is a one-line phantom in a check whose whole job is
to compare a count to a bound. A folded description counts as the one
line the installer writes (`installed_line_count`).
"""
text = skill_md.read_text(encoding="utf-8")
raw, lines = len(text.splitlines()), installed_line_count(text)
over_target = lines - TARGET_CORE_LINES
target_note = (f" ({over_target} over the {TARGET_CORE_LINES}-line target)"
if over_target > 0 else "")
ceiling = read_core_ceiling(skill_md)
if ceiling is None:
print(f"core {lines} / ceiling none / slack n/a — not gated{target_note}")
return
if raw != lines:
print(f"note: core counted as the installer writes it: {raw} staged lines, "
f"the folded description counts as one")
slack = ceiling - lines
print(f"core {lines} / ceiling {ceiling} / slack {slack}{target_note}")
released = read_released_ceiling(skill_md)
if released is not None:
print(f"released core ceiling {released}")
if ceiling > released:
fails.append(
f"core ceiling {ceiling} > the released core ceiling {released} "
f"(references/{REF_CEILINGS_FILE}): no net growth across releases. "
f"Move rationale out of the core into a reference file until the "
f"core is at most {released} lines, then lower {CORE_CEILING_KEY}.")
if lines > ceiling:
fails.append(
f"core SKILL.md {lines} lines > this skill's declared ceiling "
f"{ceiling}. Trim it, move episodic content to a reference file, "
f"or raise {CORE_CEILING_KEY} to {lines} with a short stated reason "
f"(beside the core line in references/{REF_CEILINGS_FILE} where the "
f"skill keeps one).")
elif slack > CEILING_SLACK_TOLERANCE:
fails.append(
f"core SKILL.md {lines} lines, declared ceiling {ceiling}: slack "
f"{slack} > tolerance {CEILING_SLACK_TOLERANCE}. Lower "
f"{CORE_CEILING_KEY} (or {CORE_CEILING_FILE}) to {lines} in this "
f"commit — a trim is locked in, not left as headroom.")
def _norm(s):
return " ".join(s.split())
def _index_entries(body):
"""(match, entry groups) of a file's `## Contents` index, or (None, []).
The index ends at the next `## ` heading, or — in a file whose entries
are all `###` (a numbered principles list) — at the first `###` entry, a
horizontal rule, or the end of the file. Bounding it by `## ` alone
matched nothing in such a file, so the check skipped exactly the index
that changes most often, and a numbered entry shipped with no Contents
line. Within that span the ENTRIES end at the first paragraph — a
non-blank line that neither opens a list item nor is indented under one
— because a preamble between the index and the first section is prose,
and reading its lines as entries let a later list in that preamble
stand in for headings nothing indexed. Each group holds one entry's
forms: the text, and for a numbered item the text with its marker.
"""
def plain(s):
# An entry written as an anchor link, `[Alpha](#alpha)`, is the
# other common way to write an index; reading the brackets as text
# failed every heading of a correct index, so the link is reduced
# to its text before matching.
return _norm(re.sub(r"\[([^\]]+)\]\([^)]*\)", r"\1", s))
m = re.search(r"(?ms)^## Contents[ \t]*\n(.*?)(?=^## |^### |^-{3,}[ \t]*$|\Z)", body)
if not m:
return None, [] # a file may legitimately have no index
# Index entries wrap, and legitimately carry a parenthetical the
# heading does not ("Lean Content (including progressive
# disclosure…)"). So: join continuation lines into their entry, then
# match a heading as a PREFIX of an entry, not by equality. Requiring
# equality reported a correctly-indexed section as missing — the
# check's own first finding was its own defect.
groups, cur, num = [], None, ""
# A bullet is `-`, `*` or `+`: all three are Markdown lists, and an
# index written with `*` otherwise had no entries at all. A numbered
# list (`1. Alpha`, `1) Alpha`) is a list too; its entry is kept both
# whole and without the marker, so it indexes `## 1. Alpha` and
# `## Alpha` alike — reading it as no entry reported every heading
# of a correct numbered index as missing.
def flush():
groups.append([plain(cur)] + ([plain(num + cur)] if num else []))
for line in m.group(1).splitlines():
mk = re.match(r"^\s*([-*+]|\d+[.)])\s+", line)
if mk:
if cur is not None:
flush()
cur = line[mk.end():]
num = mk.group(1) + " " if mk.group(1)[0].isdigit() else ""
elif cur is not None and line.strip():
if not line[0].isspace():
break # a paragraph: the entries are over
cur += " " + line.strip()
if cur is not None:
flush()
return m, groups
def heading_matches(short, long):
"""ONE qualifier rule for both heading matchers — the core-pointer check
and the index checks: a name matches a heading when it is the heading,
or the heading up to its ` — ` or ` (` qualifier (a dated parenthetical
included). Two matchers with two rules accepted `A — x` and rejected
`A (x)` in one place and the reverse in the other, so a heading had to
be renamed to pass both."""
return short == long or long.startswith(short + " — ") or long.startswith(short + " (")
def _entry_covers(entry, anchor):
# an index entry may carry MORE than the heading (a parenthetical the
# heading lacks) or LESS (the heading's own qualifier dropped)
return (entry == anchor or entry.startswith(anchor + " ") or entry.startswith(anchor + "(")
or heading_matches(entry, anchor))
def index_misses(body, depth=3):
"""Headings below a file's `## Contents` index that the index lacks.
Every `##`/`###` heading after the index, numbered `### N.` entries
included, must have its line (`_index_entries` says where the index
ends and how an entry is read). `depth=4` reads `####` headings too:
measured over the installed library before it was added, that depth
newly failed one skill, so the gate stays at 3 and a `####` miss is
printed as a note (check_reference_indexes).
"""
m, groups = _index_entries(body)
if not m:
return []
entries = [e for g in groups for e in g]
missing = []
for h in re.findall(r"(?m)^#{2,%d}\s+(.+?)\s*$" % depth, body[m.end():]):
hn = _norm(h)
if not any(_entry_covers(e, hn) for e in entries):
missing.append(h)
return missing
def index_orphans(body):
"""Index entries that resolve to no anchor in the same file — the
reverse of `index_misses`. The forward pass certifies a stale index: an
entry whose heading was renamed or deleted passes it, and a stale index
is exactly what a trim or a relocation leaves behind. An anchor is a
`##`–`####` heading below the index, or a bold lead opening a paragraph
(`**Step 1 — load.**`, its closing `.` or `:` dropped) — an index
legitimately lists the steps of a procedure written that way. A lead
is a sentence where a heading is a title, so an entry may name a lead
by its opening clause (`Step 2 — inventory skills` for a lead that
goes on to say how). Measured before those rules: every hit on the
bundle was one of the three shapes, and none was a defect.
"""
m, groups = _index_entries(body)
if not m:
return []
below = body[m.end():]
if not re.search(r"(?m)^#{2,3}\s+\S", below):
return [] # no sections below the index: a prose contents line is its form
heads = {_norm(h) for h in re.findall(r"(?m)^#{2,4}\s+(.+?)\s*$", below)}
leads = {_norm(h).rstrip(".:") for h in re.findall(r"(?ms)^\*\*(.+?)\*\*", below)} # a lead wraps
return [g[0] for g in groups
if not any(_entry_covers(e, a) for e in g for a in heads)
and not any(_entry_covers(e, a) or a.startswith(e + " ") for e in g for a in leads)]
# (name, reference-file text, headings index_misses must report)
INDEX_FIXTURES = [
("###-only file with every entry indexed passes",
"# T\n\n## Contents\n\n- 1. One\n- 2. Two\n\n---\n\n### 1. One\ntext\n\n### 2. Two\ntext\n", []),
("###-only file missing one Contents line fails",
"# T\n\n## Contents\n\n- 1. One\n\n### 1. One\ntext\n\n### 2. Two\ntext\n", ["2. Two"]),
("## sections still bound the index",
"# T\n\n## Contents\n\n- A\n\n## A\n\n### Sub\n", ["Sub"]),
("anchor-link entries match their headings",
"# R\n\n## Contents\n\n- [Alpha](#alpha)\n- [Beta two](#beta-two) — what it covers\n\n## Alpha\n\ntext\n\n## Beta two\n\ntext\n", []),
("anchor-link index missing one heading still fails",
"# R\n\n## Contents\n\n- [Alpha](#alpha)\n\n## Alpha\n\n## Beta\n", ["Beta"]),
("`*` bullets are entries too",
"# R\n\n## Contents\n\n* [Alpha](#alpha)\n* Beta\n\n## Alpha\n\n## Beta\n", []),
("a numbered list indexes numbered headings",
"# R\n\n## Contents\n\n1. Alpha\n2. Beta\n\n## 1. Alpha\n\n## 2. Beta\n", []),
("a numbered list indexes unnumbered headings too",
"# R\n\n## Contents\n\n1. Alpha\n2) Beta two\n\n## Alpha\n\n## Beta two\n\n## Gamma\n", ["Gamma"]),
("a preamble paragraph ends the entries; a list inside it is not the index",
"# R\n\n## Contents\n\n- Alpha\n\nPreamble prose.\n\n- Not an entry\n\n## Alpha\n\n## Beta\n", ["Beta"]),
("a #### heading missing from the index is not a miss at the gate's depth",
"# R\n\n## Contents\n\n- Alpha\n\n## Alpha\n\n#### Deep\n", []),
]
# (name, reference-file text, headings index_misses(depth=4) must report
# that the gate's depth does not): the `####` note, never a failure.
DEEP_INDEX_FIXTURES = [
("a #### heading missing from the index is reported at depth 4",
"# R\n\n## Contents\n\n- Alpha\n\n## Alpha\n\n#### Deep\n", ["Deep"]),
("a #### heading the index names is not reported",
"# R\n\n## Contents\n\n- Alpha\n- Deep\n\n## Alpha\n\n#### Deep\n", []),
]
# (name, reference-file text, entries index_orphans must report): the
# reverse pass — every entry resolves to a heading or a bold lead.
ORPHAN_FIXTURES = [
("every entry has its heading: nothing reported",
"# R\n\n## Contents\n\n- Alpha\n- Beta two — what it covers\n\n## Alpha\n\n## Beta two\n", []),
("an entry whose heading was deleted is an orphan",
"# R\n\n## Contents\n\n- Alpha\n- Beta\n\n## Alpha\n", ["Beta"]),
("an entry whose heading was renamed is an orphan",
"# R\n\n## Contents\n\n- [Alpha](#alpha)\n\n## Alpha one\n", ["Alpha"]),
("a bold lead with its closing period anchors a step entry",
"# R\n\n## Contents\n\n- Steps\n - Step 1 — load\n\n## Steps\n\n**Step 1 — load.** Text.\n", []),
("an entry naming a lead's opening clause passes; a heading's prefix does not",
"# R\n\n## Contents\n\n- Steps\n - Step 2 — inventory\n- Alpha\n\n## Steps\n\n"
"**Step 2 — inventory skills,\nby survival.** Text.\n\n## Alpha one\n", ["Alpha"]),
("a #### heading anchors an entry",
"# R\n\n## Contents\n\n- Alpha\n- Deep\n\n## Alpha\n\n#### Deep\n", []),
("a numbered entry resolves through either of its forms",
"# R\n\n## Contents\n\n1. Alpha\n2. Beta\n\n## 1. Alpha\n\n## Beta\n", []),
("a list in the preamble is not read as entries",
"# R\n\n## Contents\n\n- Alpha\n\nPreamble prose.\n\n- Not an entry\n\n## Alpha\n", []),
("a file with no headings below its index is exempt: the entries are a prose contents line",
"# R\n\n## Contents\n\n- Alpha\n- Beta\n\nOne paragraph.\n\nAnother, with **a bold run** inside.\n", []),
("an entry naming a heading up to its ` (` qualifier resolves",
"# R\n\n## Contents\n\n- Site mechanics\n- Beta\n\n## Site mechanics (stock vertical)\n\n## Beta (2026-01)\n", []),
]
# (name, reference-file text, headings index_misses must report): the
# forward pass under the same one qualifier rule.
QUALIFIER_INDEX_FIXTURES = [
("an index entry without the heading's ` (` qualifier is not a miss",
"# R\n\n## Contents\n\n- Site mechanics\n\n## Site mechanics (stock vertical)\n", []),
("an index entry without the heading's ` — ` qualifier is not a miss",
"# R\n\n## Contents\n\n- Alpha\n\n## Alpha — what it covers\n", []),
("a heading that merely extends the entry's words is still a miss",
"# R\n\n## Contents\n\n- Alpha\n\n## Alpha one\n", ["Alpha one"]),
]
# (name, pointer text, file heading, must match): the core-pointer side of
# the same rule.
POINTER_HEADING_FIXTURES = [
("exact", "Alpha", "Alpha", True),
("up to the ` — ` qualifier", "Alpha", "Alpha — what it covers", True),
("up to the ` (` qualifier, dated", "Site mechanics", "Site mechanics (2026-01-31)", True),
("a prefix of a word is not a match", "Alpha", "Alphabet", False),
("a longer pointer than the heading is not a match", "Alpha — what it covers", "Alpha", False),
]
def check_reference_indexes(skill_dir, fails):
"""Every heading in a reference file appears in that file's own Contents.
The per-file `## Contents` index exists so a reader can see what the file
covers without loading it, and so the core's pointers have something to
resolve against. Nothing kept it current: an index is edited by hand, in a
different part of the file from the section being added, and a stale one
is indistinguishable from a complete one at a glance. Both misses this
check caught were made while writing the rule that the index matters.
Pointer targets are checked too — a core pointer naming a heading that
does not exist sends the reader to a file to find nothing, which is worse
than no pointer, because they stop looking.
"""
def norm(s):
return " ".join(s.split())
def defence(text):
"""Blank fenced blocks, keeping line count, so a `##` inside a
template (a summary skeleton, a principles entry, a registry stanza)
is not mistaken for a section of the file. Every early failure this
check reported was of exactly that kind."""
return blank_fenced_code(text)
refs = skill_dir / "references"
if not refs.is_dir():
return
for p in sorted(refs.glob("*.md")):
text = defence(p.read_text(encoding="utf-8"))
shallow = index_misses(text)
for h in shallow:
fails.append(f"{p.name}: heading not in its own Contents index: {h!r}")
for h in index_misses(text, 4):
if h not in shallow:
print(f"note: {p.name}: #### heading not in its own Contents index: {h!r} "
f"— reported, not gated")
for e in index_orphans(text):
fails.append(f"{p.name}: index entry without a heading: {e!r}")
core = (skill_dir / "SKILL.md").read_text(encoding="utf-8")
check_reference_shape(skill_dir, core, fails)
# Both pointer forms name a target: `references/x.md` ("Heading") and
# (`references/x.md`, "Heading"). The second form was invisible to this
# check, so its targets went unverified. A pointer may name a heading up
# to its qualifier, by the one rule a Contents entry follows (heading_matches).
named, _ = core_pointers(core)
for fname in sorted(named):
target = refs / fname
if not target.is_file():
fails.append(f"SKILL.md points at a reference that does not exist: {fname}")
continue
heads = {norm(x) for x in re.findall(r"(?m)^#{2,4}\s+(.+?)\s*$",
defence(target.read_text(encoding="utf-8")))}
for heading in sorted(named[fname]):
if not any(heading_matches(heading, h) for h in heads):
fails.append(f"SKILL.md pointer has no target heading: {fname} -> {heading!r}")
# --- Reference-file growth barrier ---------------------------------------------
# The core's ceiling does not transfer to reference files as a size rule,
# because their cost is conditional: a long file loaded once a month is cheap,
# and the signal that matters is how many DISTINCT episodes pull a file in,
# since every one of them pays for the whole file. Measured on this bundle,
# the largest reference had a single trigger and was correctly shaped while a
# smaller one carried many — a size rule alone flags the healthy file and
# misses the mis-shaped one. The figures are whatever the `reference shape`
# line prints on this run; never copy them into this comment.
#
# What a ceiling CAN do is stop silent growth, so the barrier combines the
# two: every reference file of a skill that opts in carries a line ceiling,
# and exceeding it fails and forces a decision whose remedy is chosen by the
# file's load-trigger count —
# * more than SPLIT_TRIGGER_THRESHOLD triggers: split by episode;
# * that many or fewer: trim, or raise the ceiling with a short one-line
# reason written beside the number.
# Size alone never forces a split, so a single-episode file is never split to
# meet a size rule. The ceiling follows trims down with the core's tolerance.
#
# Opt-in, per skill: a `references/ceilings.txt` file holds one line per file —
# <file.md> <ceiling> [<short neutral reason for the last raise>]
# with `#` comments and blank lines allowed. No date: the file ships to every
# adopter, and when a raise happened is version control's record. A line from
# an older version, with a date before its reason, still parses; the date is
# ignored. Not a dotfile: an install route
# that drops dotfiles would silently switch the gate off. A skill without one
# has not opted in: the shape line is printed and nothing is gated, so the public validator
# imposes no budget on a skill whose author never set one.
#
# The trigger count is DECLARED, not inferred: each reference carries one
# `Load triggers: a; b; c` line in its header (before its first `## `
# heading), and the count is the number of distinct entries. A trigger is an
# EPISODE — a reason to load the file — not a pointer: one episode may be
# cited from several places and may cover several sections, and a file a
# run walks once (every step of a cycle) has one episode however many of its
# sections the core names. Pointer scanning therefore cannot be exact, so it
# is kept as the fallback figure for a file that declares nothing (printed
# with `~`) and as a cross-check printed beside the declaration: the number
# of distinct SECTIONS of the core that cite the file is the cheapest lower
# bound on its episodes — a once-per-run file is cited from the one core
# section that runs it — and a declaration below that bound by more than
# POINTER_SLACK is noted as under-declared, since the count is self-declared
# and a file could otherwise stay under the split threshold by declaring less.
# A note, not a gate.
#
# The threshold is set from the measured distribution over one library at
# last measurement, not from intuition: one to eight triggers almost
# everywhere, three files above eight, and the two files just under the
# earlier threshold of 12 were the ones readers described as overloaded. A
# file above the threshold whose split is decided but not yet made carries a
# `split_pending: <file.md> [<reason>]` line in the sidecar: the
# split remedies then print as notes and the trim-or-raise remedy applies
# until the split lands.
REF_CEILINGS_FILE = "ceilings.txt"
SPLIT_TRIGGER_THRESHOLD = 8
POINTER_SLACK = 2
# The plain line, or the bold prose form a header already written as a
# sentence carries (`**Load trigger:** …`, `**Load triggers:** …`): matching
# the plain form only made a file that declared its episodes in prose fail
# the gate until a second, mechanical line was added beside the first.
# The plain line wins over a bold one wherever both appear: a bold sentence
# above the plain list is prose, and reading the first match counted it.
LOAD_TRIGGERS_RE = re.compile(r"(?m)^(\*\*)?Load triggers?:(?:\*\*)?[ \t]*(.*?)[ \t]*$")
# (name, reference-file text, entries declared_load_triggers must return)
LOAD_TRIGGER_FIXTURES = [
("the plain line", "# A\n\nLoad triggers: one; two\n\n## S\n", ["one", "two"]),
("the bold prose form, plural", "# A\n\n**Load triggers:** one; two\n\n## S\n", ["one", "two"]),
("the bold prose form, singular", "# A\n\n**Load trigger:** one\n\n## S\n", ["one"]),
("a duplicate entry counts once, case apart", "# A\n\nLoad triggers: One; one; two\n\n## S\n", ["One", "two"]),
("a line after the first ## heading is not a declaration", "# A\n\n## S\n\nLoad triggers: one\n", None),
("no line at all", "# A\n\n## S\n", None),
("a bold prose sentence above the plain line: the plain line wins",
"# A\n\n**Load trigger:** read before the first draft.\n\n"
"Load triggers: one; two; three; four; five\n\n## S\n",
["one", "two", "three", "four", "five"]),
]
# An optional YYYY-MM-DD before the reason is the older dated form: read and
# ignored, so an install that predates the undated form keeps validating.
REF_CEILING_LINE_RE = re.compile(
r"^(?P<file>[^\s/]+\.md)[ \t]+(?P<ceiling>\d+)"
r"(?:[ \t]+\d{4}-\d{2}-\d{2})?(?:[ \t]+(?P<reason>\S.*?))?[ \t]*$")
# The marker is read bare or behind `# `: a validator that predates it reads
# the commented form as a comment and still passes the bundle, so a round
# can declare a pending split before the validator that knows the word is
# the installed one. Once it is, write the bare form.
SPLIT_PENDING_LINE_RE = re.compile(
r"^(?:#[ \t]*)?split_pending:[ \t]+(?P<file>[^\s/]+\.md)"
r"(?:[ \t]+\d{4}-\d{2}-\d{2})?(?:[ \t]+(?P<reason>\S.*?))?[ \t]*$")
# `references/x.md` ("Heading") — up to 40 characters between, newlines
# included, no backtick — and the parenthesised (`references/x.md`, "Heading").
REF_POINTER_RE = re.compile(r'`references/([a-z0-9-]+\.md)`(?:[^(`]{0,40}\(|,\s*)"([^"]+)"')
REF_ANY_POINTER_RE = re.compile(r"`references/([a-z0-9-]+\.md)`")
def core_pointers(core):
"""({file: {section names}}, {file: number of filename-only pointers}).
Frontmatter is skipped. Filename-only pointers are counted once per
paragraph or list item, so a sentence that cites a file twice is one
pointer, not two."""
m = re.match(r"(?s)^---\n.*?\n---\n", core)
body = core[m.end():] if m else core
named, named_at = {}, set()
for pm in REF_POINTER_RE.finditer(body):
named.setdefault(pm.group(1), set()).add(" ".join(pm.group(2).split()))
named_at.add(pm.start())
# block index for each line: a blank line or a list-item start opens one
block, starts = 0, []
for line in body.splitlines(True):
if not line.strip() or re.match(r"^\s*(?:[-*]|\d+\.)\s", line):
block += 1
starts.append(block)
offsets = [0]
for line in body.splitlines(True):
offsets.append(offsets[-1] + len(line))
unnamed = {}
for pm in REF_ANY_POINTER_RE.finditer(body):
if pm.start() in named_at:
continue
ln = body.count("\n", 0, pm.start())
unnamed.setdefault(pm.group(1), set()).add(starts[ln] if ln < len(starts) else -1)
return named, {f: len(b) for f, b in unnamed.items()}
def core_pointer_sections(core):
"""{file: number of distinct `## ` sections of the core that cite it}.
The cross-check's lower bound on a reference's episodes: a pointer sits
in the core section whose moment it serves, so two pointers from one
section are one episode and pointers from four sections are at least
four. The body before the first `## ` heading is one section. Fenced
blocks are read too — a fenced snippet that cites a file loads it."""
m = re.match(r"(?s)^---\n.*?\n---\n", core)
body = core[m.end():] if m else core
sections, sec = {}, 0
for line in body.splitlines(True):
if line.startswith("## "):
sec += 1
for pm in REF_ANY_POINTER_RE.finditer(line):
sections.setdefault(pm.group(1), set()).add(sec)
return {f: len(s) for f, s in sections.items()}
def declared_load_triggers(text):
"""The distinct entries of the header's `Load triggers:` line, or None."""
head = re.split(r"(?m)^## ", text, maxsplit=1)[0]
found = list(LOAD_TRIGGERS_RE.finditer(head))
if not found:
return None
m = next((f for f in found if not f.group(1)), found[0])
seen = []
for t in m.group(2).split(";"):
t = " ".join(t.split())
if t and t.lower() not in (s.lower() for s in seen):
seen.append(t)
return seen
def read_ref_ceilings(refs, fails):
"""({file: (ceiling, reason)}, {file: reason, split pending})
from references/ceilings.txt, or (None, {}) when the skill has not opted
in. Every malformed line fails: a skill that opted in and wrote a line
the gate cannot read must not pass ungated."""
f = refs / REF_CEILINGS_FILE
if not f.is_file():
return None, {}
out, pending = {}, {}
for i, raw in enumerate(f.read_text(encoding="utf-8").splitlines(), 1):
line = raw.strip()
where = f"references/{REF_CEILINGS_FILE}:{i}"
sp = SPLIT_PENDING_LINE_RE.match(line) # before the comment test: the marker may sit behind `# `
if sp:
pending[sp.group("file")] = sp.group("reason") or ""
continue
if not line or line.startswith("#"):
continue
m = REF_CEILING_LINE_RE.match(line)
if not m:
fails.append(f"{where}: unreadable line {line!r} — the form is "
f"`<file.md> <lines> [<reason>]` (or `split_pending: "
f"<file.md> [<reason>]` for a decided split)")
continue
name = m.group("file")
if name in out:
fails.append(f"{where}: {name} has a second ceiling line")
continue
out[name] = (int(m.group("ceiling")), m.group("reason"))
return out, pending
def check_reference_shape(skill_dir, core, fails):
"""Print the `reference shape` line; gate it when the skill opted in."""
refs = pathlib.Path(skill_dir) / "references"
if not refs.is_dir():
return
named, unnamed = core_pointers(core)
citing = core_pointer_sections(core)
ceilings, pending = read_ref_ceilings(refs, fails)
N, tol = SPLIT_TRIGGER_THRESHOLD, CEILING_SLACK_TOLERANCE
rows = []
for p in sorted(refs.glob("*.md")):
text = p.read_text(encoding="utf-8")
lines = len(text.splitlines())
declared = declared_load_triggers(text)
scanned = len(named.get(p.name, ())) + unnamed.get(p.name, 0)
rows.append((p.name, lines, declared, scanned))
shown = []
for name, lines, declared, scanned in rows:
c = ceilings.get(name) if ceilings is not None else None
t = str(len(declared)) if declared is not None else f"~{scanned}"
shown.append(f"{name}={lines}/{c[0] if c else '-'}/{t}")
gated = ("ceilings in references/" + REF_CEILINGS_FILE if ceilings is not None
else "no references/" + REF_CEILINGS_FILE + " — not gated")
print(f"reference shape (lines / ceiling / load triggers declared in the header, "
f"~ = scanned from the core, none declared; split by episode above {N}; {gated}): "
+ ", ".join(shown))
# The pointer cross-check: declared episodes against the number of core
# sections that cite the file (the lower bound on episodes) — never
# against named sections, which a once-per-run file has one trigger for.
for name, lines, declared, scanned in rows:
if declared is None:
continue
secs = citing.get(name, 0)
flag = " — UNDER-DECLARED" if secs - len(declared) > POINTER_SLACK else ""
print(f"note: pointer cross-check — {name} declares {len(declared)} load trigger(s); "
f"the core cites it from {secs} section(s), naming {len(named.get(name, ()))} of "
f"its sections{flag}")
if len(declared) > N:
print(f"note: {name} declares {len(declared)} load triggers (> {N}) — split "
f"by episode is indicated"
+ (" once it outgrows its ceiling" if ceilings is not None
else "; size is not the signal")
+ (f"; split pending" + (f": {pending[name]}" if pending[name] else "")
if name in pending else ""))
if ceilings is None:
return
present = {name for name, *_ in rows}
for name in sorted(set(ceilings) - present):
fails.append(f"references/{REF_CEILINGS_FILE} names {name}, which is not in "
f"references/ — remove its line, or lower it with the file it moved to")
for name in sorted(set(pending) - present):
fails.append(f"references/{REF_CEILINGS_FILE} marks a split pending for {name}, "
f"which is not in references/ — remove the line")
for name, lines, declared, _ in rows:
if name not in ceilings:
fails.append(f"references/{name} has no ceiling: this skill opted in with "
f"references/{REF_CEILINGS_FILE}, so add `{name} {lines}` there")
continue
ceiling, reason = ceilings[name]
if declared is None:
fails.append(f"references/{name} declares no load triggers: add one "
f"`Load triggers: a; b; c` line to its header (before the first "
f"`## ` heading), one entry per distinct episode that loads it")
continue
n = len(declared)
if name in pending and n <= N:
print(f"note: references/{REF_CEILINGS_FILE} marks a split pending for {name}, "
f"which declares {n} load triggers (<= {N}) — the line can go")
split_due = n > N and name not in pending
if lines > ceiling and split_due:
fails.append(
f"references/{name} {lines} lines > ceiling {ceiling}, with {n} load "
f"triggers (> {N}): split it by episode, so each trigger loads only "
f"its own part — a raise is not the remedy for a file this many "
f"episodes pull in")
elif lines > ceiling:
# Reached with n > N only while a split is pending: say so, not `<= N`.
count_vs_n = f"> {N}, split pending" if n > N else f"<= {N}"
fails.append(
f"references/{name} {lines} lines > ceiling {ceiling}, with {n} load "
f"trigger(s) ({count_vs_n}): trim it back to {ceiling} lines or fewer, or raise the "
f"ceiling in references/{REF_CEILINGS_FILE} to {lines} with a short "
f"one-line reason beside the number (`{name} {lines} why`)")
elif ceiling - lines > tol:
fails.append(
f"references/{name} {lines} lines, ceiling {ceiling}: slack "
f"{ceiling - lines} > tolerance {tol}. Lower its line in "
f"references/{REF_CEILINGS_FILE} to {lines} in this commit — a trim "
f"is locked in, not left as headroom")
if reason and split_due:
fails.append(
f"references/{name} carries a raised ceiling ({reason}) but "
f"declares {n} load triggers (> {N}): with that many episodes the "
f"remedy is a split by episode, not a raise")
# A `## Bundle manifest` section (in SKILL.md or a reference) is a hand-kept
# inventory of the directories it names, so it is checked against them: every
# file under scripts/ and references/ is named there (as `scripts/x`,
# `references/x` or the bare file name), and every file it names exists. A
# skill without the section has not opted in and nothing is checked.
MANIFEST_FILE_RE = re.compile(r"`([A-Za-z0-9_./-]+\.(?:md|sh|py|txt|json))`")
# (name, manifest section, bundle files, (unlisted, missing) manifest_misses must return)
MANIFEST_FIXTURES = [
("every file listed, every entry present",
"`SKILL.md`, `a.md`, `scripts/x.sh` and `references/ceilings.txt`.\n",
["SKILL.md", "references/a.md", "references/ceilings.txt", "scripts/x.sh"], ([], [])),
("a shipped script the list lacks",
"`a.md` and `scripts/x.sh`.\n",
["references/a.md", "scripts/x.sh", "scripts/y.py"], (["scripts/y.py"], [])),
("a listed file that does not ship",
"`a.md`, `b.md` and `scripts/x.sh`.\n",
["references/a.md", "scripts/x.sh"], ([], ["b.md"])),
("Windows backslash paths match the forward-slash list",
"`a.md` and `scripts/x.sh`.\n",
["references\\a.md", "scripts\\x.sh", "scripts\\y.py"], (["scripts/y.py"], [])),
]
def manifest_misses(section, files):
"""(unlisted, missing) for a manifest section and the bundle's relative paths."""
named = set(MANIFEST_FILE_RE.findall(section))
have = {f.replace("\\", "/") for f in files} # a Windows relative path arrives with backslashes
unlisted = [f for f in sorted(have) if f.split("/")[0] in ("scripts", "references")
and f not in named and f.rsplit("/", 1)[-1] not in named]
missing = [n for n in sorted(named) if not ({n} if "/" in n else
{n, "references/" + n, "scripts/" + n}) & have]
return unlisted, missing
def check_bundle_manifest(skill_dir, fails):
docs = [skill_dir / "SKILL.md"] + sorted((skill_dir / "references").glob("*.md"))
for doc in docs:
text = doc.read_text(encoding="utf-8") if doc.is_file() else ""
m = re.search(r"(?ms)^## Bundle manifest[ \t]*\n(.*?)(?=^## |\Z)", text)
if not m:
continue
files = [p.relative_to(skill_dir).as_posix() for p in skill_dir.rglob("*")
if p.is_file() and not any(x.startswith(".") or x in BUILD_JUNK
for x in p.relative_to(skill_dir).parts)
and p.suffix != ".pyc"]
unlisted, missing = manifest_misses(m.group(1), files)
where = doc.relative_to(skill_dir)
for f in unlisted:
fails.append(f"bundle manifest ({where}): {f} ships but is not listed — add it")
for f in missing:
fails.append(f"bundle manifest ({where}): lists {f}, which does not exist — "
f"restore it or drop it from the list")
return
def check_plugin_manifest(skill_dir, fails):
"""A skill bundle must NOT contain a plugin manifest.
The uploader refuses it outright: *"A skill cannot contain a plugin
manifest (…/.claude-plugin/plugin.json). Remove it, or upload this content
as a plugin instead."* Skill and plugin are two upload kinds, not one
artefact wearing both hats.
This check was originally written the other way round, because the plugin
reference documents a skills-directory plugin: a folder under a skills
directory carrying this manifest loads as a plugin in place. That is true
of a directory copied there by hand, and says nothing about what the
uploader accepts — a distinction no amount of reading the plugin docs
surfaces, because the constraint lives in the other product surface. The
manifest is therefore repo-only, and `check_repo_versions` validates it
there.
The practical consequence, worth stating where someone will read it: a
user who installs the `.skill` gets a skill, not a plugin. Only the
repo-copy install path yields plugin behaviour.
"""
manifest = skill_dir / ".claude-plugin" / "plugin.json"
if manifest.is_file():
fails.append(
"a skill bundle must not contain .claude-plugin/plugin.json — the "
"uploader rejects it ('upload this content as a plugin instead'). "
"Keep the manifest at the repo root only; check_repo_versions "
"validates it there.")
def check_cited_path(skill_dir, rel, where, fails):
"""One cited bundled path exists in the staged set (a `<slot>` segment
is matched as a glob); `where` names the citing file when it is not
SKILL.md. The message keeps its `cited path` prefix for every caller."""
if SLOT_SEG_RE.search(rel):
pat = SLOT_SEG_RE.sub("*", rel)
if not any(q.is_file() for q in skill_dir.glob(pat)):
fails.append(f"cited path pattern has no staged instance: {rel}{where} "
f"(no file matches {pat})")
return
if not (skill_dir / rel).is_file():
fails.append(
f"cited path missing from staged set: {rel}{where} "
f"— if this file belongs to another skill, cite it as "
f"`<skill-name>/{rel}`; if it is a file in the repository the "
f"skill operates on, cite it as `./{rel}`; both forms are "
f"exempt from this check")
def check_orphans(skill_dir):
"""Warn on a staged file under references/, scripts/ or assets/ that
neither SKILL.md nor any reference file names, by path or by file name.
A warning, not a gate: a script-only asset is legitimate, and the prose
scrape that names files is approximate. Returns the orphan paths."""
texts = [(skill_dir / "SKILL.md").read_text(encoding="utf-8", errors="replace")]
refs = skill_dir / "references"
texts += [q.read_text(encoding="utf-8", errors="replace")
for q in sorted(refs.glob("*.md"))] if refs.is_dir() else []
orphans = []
for top in ("references", "scripts", "assets"):
base = skill_dir / top
for q in sorted(base.rglob("*")) if base.is_dir() else []:
rel = q.relative_to(skill_dir)
if not q.is_file() or any(part in BUILD_JUNK or part in VCS_DIRS for part in rel.parts) \
or q.suffix == ".pyc":
continue
pat = re.compile(r"(?<![\w.-])" + re.escape(q.name) + r"(?![\w-])")
own = q.read_text(encoding="utf-8", errors="replace") if q.suffix == ".md" else None
if not any(pat.search(x) for x in texts if x is not own):
orphans.append(rel.as_posix())
for rel in orphans:
print(f"warn: staged file named nowhere in SKILL.md or references/: {rel} "
f"— cite it, or confirm it is reached another way (a script-only asset)")
return orphans
def check_live_set(skill_dir, live_dir, fails):
"""--live: every regular file of the live skill is in the staged set. A
staged copy is the FULL directory, so a file live has and staging lacks
is a truncation unless the manifest names the removal."""
live = pathlib.Path(live_dir)
if not live.is_dir():
print(f"note: --live {live_dir} is not a directory — the live-set check is skipped")
return
staged = pathlib.Path(skill_dir).resolve()
for q in sorted(live.rglob("*")):
rel = q.relative_to(live)
if not q.is_file() or q.is_symlink() or q.suffix == ".pyc" or \
any(part in VCS_DIRS or part in BUILD_JUNK or part in CHECKOUT_ONLY
for part in rel.parts):
continue
if not (staged / rel).is_file():
fails.append(f"live file absent from staged set: {rel.as_posix()} — a staged copy "
f"is the full directory (skill-authoring.md, rule 5); name the "
f"removal in the manifest or restore it")
def check_dir(skill_dir, fails):
# Resolve before comparing names: Path('.').name is '' for a relative
# argument naming the current directory, which false-fails a correct
# bundle and blames the frontmatter for an argument problem.
skill_dir = pathlib.Path(skill_dir).resolve()
skill_md = skill_dir / "SKILL.md"
if not skill_md.is_file():
fails.append("SKILL.md missing"); return
text = skill_md.read_text(encoding="utf-8")
fm = frontmatter(text)
if fm is None:
fails.append("frontmatter: no leading --- block"); return
# `yaml_available` is about the LIBRARY, not about this file parsing. A
# parse failure is a defect in the file and is reported as one; only a
# missing library downgrades the check, and only that case earns the note.
yaml_available = True
try:
import yaml # optional; fall back to regex checks if absent
data = yaml.safe_load(fm)
if not isinstance(data, dict):
fails.append("frontmatter: does not parse to a mapping")
data = {}
except ImportError:
yaml_available = False
# Strip one layer of matching surrounding quotes: the template asks
# for `name: "x"`, a real parser never sees the quote characters as
# part of the value, and .strip() removes whitespace, not quotes —
# so the hardened fallback failed the bundle it ships inside.
data = {"name": fallback_name(fm), "description": folded_description(fm)}
except Exception as e: # yaml error
# Name the cause the check can detect, not the first field it then
# fails to find: an unquoted `: ` inside a description is the common
# way a whole block stops parsing, and "name missing" sends the
# author to fix a field that is present.
fails.append(
f"frontmatter did not parse (likely an unquoted `: ` in a value — "
f"double-quote the value or reword it): {e}")
data = None
name = str((data or {}).get("name") or "").strip()
if data is None:
pass # already reported above; a missing-name report here would mislead
elif not name:
fails.append("frontmatter: `name` missing")
elif not NAME_RE.match(name):
fails.append(f"frontmatter: `name` not kebab-case: {name!r}")
elif name != skill_dir.name:
fails.append(f"frontmatter: `name` {name!r} != directory {skill_dir.name!r}")
desc = folded_description(fm)
# A space before `#` starts a YAML comment, so a plain (unquoted) value
# ends there and the block still parses: the raw line reads whole, the
# installer gets a shorter value, and no parse check can see it.
line = (re.search(r"(?m)^description:[ \t]*(.*)$", fm) or [None, ""])[1]
if line[:1] not in ("", '"', "'", ">", "|") and re.search(r"[ \t]#", line):
fails.append(
"frontmatter: unquoted `description` contains ` #`, which starts a "
"YAML comment and cuts the value there — double-quote the value")
parsed = (data or {}).get("description")
if yaml_available and isinstance(parsed, str):
desc = parsed.strip() # measure what the installer's parser returns
if not desc:
fails.append("frontmatter: `description` missing")
elif len(desc) > MAX_DESCRIPTION_CHARS:
fails.append(f"description {len(desc)} chars > cap {MAX_DESCRIPTION_CHARS}")
elif len(desc) > 900:
print(f"warn: description {len(desc)} chars (cap {MAX_DESCRIPTION_CHARS}) — near the boundary")
check_top_level_keys(fm, fails)
for ln, tok in template_tokens(text):
print(f"warn: SKILL.md:{ln}: {tok!r} is rewritten when the skill is invoked with "
f"arguments — write an awk field as `$ 2`, or move the text to a reference or script")
# Every cited bundled path exists (backticked, real extension — globs in
# prose are skipped, and a naming pattern with a `<slot>` or `{slot}`
# segment is matched as a glob against the staged set, not looked up:
# `references/studies/<study>.md` documents a family of files, and it
# passes when at least one staged file fits the pattern, fails when
# none does). Ownership is inferred from the shape of the span, so
# the convention has to make the two cases distinguishable: PATH_RE requires
# the reserved prefix IMMEDIATELY after the backtick, which means a path
# qualified with its owning skill's name — `<skill-name>/references/x.md` —
# does not match and is exempt by construction. That qualified form is how a
# skill cites a file belonging to a different skill. A skill that operates
# on a repository names that repository's `scripts/` files too, in prose and
# in run commands; the convention for those is the repository-relative
# form, `./scripts/x.py`, exempt the same way (the `./` is not the prefix),
# in prose and in command position alike. Both forms are conventions, not
# disguises: re-wording a legitimate cross-reference so the backtick no
# longer starts with the prefix is. Either form also passes a skill's OWN
# missing file spelt that way — the same trade-off, accepted for both.
# The failure message names both conventions, because a false FAIL here is
# otherwise indistinguishable from a genuinely missing file.
for rel in sorted(set(PATH_RE.findall(text)) | command_paths(text)):
check_cited_path(skill_dir, rel, "", fails)
# A reference file's fenced command names a script too (`python3
# scripts/x.py` in a recipe), and only SKILL.md was read: measured over
# the installed library, every such path existed, so this is a gate.
refs = skill_dir / "references"
for p in sorted(refs.glob("*.md")) if refs.is_dir() else []:
for rel in sorted(command_paths(p.read_text(encoding="utf-8"))):
check_cited_path(skill_dir, rel, f" (in references/{p.name})", fails)
# exactly one frontmatter block: a second `---` block (or stray
# name:/description: lines) directly after the first is a duplicated
# header that every field check passes by construction
if SECOND_FRONTMATTER_RE.match(text):
fails.append("frontmatter: a second frontmatter block follows the first")
check_frontmatter_shape(fm, fails, yaml_available)
check_core_size(skill_md, fails)
check_reference_indexes(skill_dir, fails)
check_plugin_manifest(skill_dir, fails)
check_bundle_manifest(skill_dir, fails)
check_orphans(skill_dir)
for p in skill_dir.rglob("*"):
parts = p.relative_to(skill_dir).parts
if any(part in VCS_DIRS for part in parts):
if not any(part in VCS_DIRS for part in parts[:-1]): # report the top only
fails.append(f"version-control metadata in staged tree: "
f"{p.relative_to(skill_dir)} (seed without it)")
continue
if p.name in BUILD_JUNK or p.suffix == ".pyc" or p.name.startswith(".~lock"):
fails.append(f"build artefact in staged tree: {p.relative_to(skill_dir)}")
# content residue in every text file of the bundle, not only SKILL.md
if p.is_file() and p.suffix.lower() in (".md", ".txt", ".yml", ".yaml", ".json"):
body = p.read_text(encoding="utf-8", errors="replace")
rel = p.relative_to(skill_dir)
for line, why, hit in residue_hits(rel, body):
fails.append(f"edit residue in {rel}:{line}: {why} ({hit!r})")
FENCE_OPEN_RE = re.compile(r"^[ \t]*(`{3,}|~{3,})")
def blank_fenced_code(text, fill=lambda h: re.sub(r"[^\n]", " ", h)):
"""Blank every fenced code block, at ANY indentation, keeping line count.
A fence is ``` or ~~~ (three or more) after any leading whitespace, and it
is closed only by a line of the same character, at least as long, with
nothing after it. Detecting fences at column zero only read a block
indented under a list item — the usual shape for a command inside a
numbered step — as prose, so a correct `sed` with a backreference failed
the residue check and was rewritten worse to pass it. A fence that never
closes is left as prose: the gate errs toward reporting. Every check that
must not read code as prose calls this one function (`fill` sets what a
blanked line becomes), so the fence model cannot drift between checks.
"""
out, held, fence = [], [], None
for line in text.splitlines(keepends=True):
if fence is None:
m = FENCE_OPEN_RE.match(line)
if m:
fence, held = m.group(1), [line]
else:
out.append(line)
continue
held.append(line)
if re.match(r"^[ \t]*%s{%d,}[ \t]*$" % (re.escape(fence[0]), len(fence)), line):
out.extend(fill(h) for h in held)
fence, held = None, []
out.extend(held) # unclosed fence: prose
return "".join(out)
# A `$` right before a digit, and `$ARGUMENTS`, are rewritten by Claude
# Code's skill loader when the skill is invoked with arguments: `$0` becomes
# the first argument word, `$2` the third. The file on disk is unchanged, so
# no read of it shows the damage; an awk field reference in SKILL.md then
# runs as `{st=only,}`, a syntax error the snippet's `2>/dev/null` hides.
# `$ 2` (awk allows the space) and `${2}` arrive intact. Reported as a
# warning, never a failure: other skills use `$1` placeholders on purpose,
# and reference files and scripts are read or run as files, not templated.
TEMPLATE_TOKEN_RE = re.compile(r"\$(?:[0-9]|ARGUMENTS\b)")
def template_tokens(text):
"""[(line, token)] for every loader-substituted token in a SKILL.md."""
return [(text.count("\n", 0, m.start()) + 1, m.group(0))
for m in TEMPLATE_TOKEN_RE.finditer(text)]
# (name, SKILL.md text, tokens template_tokens must report)
TEMPLATE_FIXTURES = [
("awk field reference $2 is reported", " fm && /^status:/ {st=$2}\n", [(1, "$2")]),
("$0 and $ARGUMENTS in prose are reported", "x\nquote $0 and $ARGUMENTS here\n",
[(2, "$0"), (2, "$ARGUMENTS")]),
("spaced $ 2, ${2}, $NF and $d pass", "{st=$ 2} ${2} $NF \"$d\"\n", []),
]
def interp_name(tok):
"""`python3.12`, `python.exe`, `/usr/bin/python3` -> the CMD_INTERP name, else None."""
name = re.sub(r"(?i)\.exe$", "", tok.rsplit("/", 1)[-1])
name = re.sub(r"^python3\.?[0-9]+$", "python3", name)
return name if name in CMD_INTERP else None
def script_index(toks, i):
"""Index of the script after the interpreter at toks[i], past its own
options (CMD_OPTS); None where an option means no script follows."""
j = i + 1
fam = CMD_OPTS.get(CMD_FAMILY.get(interp_name(toks[i]), ""))
if not fam:
return j
flag, takes_value, no_script = fam
while j < len(toks):
t = toks[j]
if no_script.fullmatch(t):
return None
if t in takes_value:
j += 2
elif flag.fullmatch(t):
j += 1
else:
break
return j
def command_paths(text):
"""Unqualified bundled paths in command position (see CMD_PATH_RE)."""
prose = blank_fenced_code(text)
chunks = [a for a, b in zip(text.splitlines(), prose.splitlines()) if a != b]
chunks += re.findall(r"`([^`\n]+)`", prose)
out = set()
for chunk in chunks:
for seg in re.split(r"&&|\|\||;|\|", chunk):
toks = seg.split()
for i, t in enumerate(toks):
if not interp_name(t):
continue
j = script_index(toks, i)
if j is not None and j < len(toks) and CMD_PATH_RE.fullmatch(toks[j]):
out.add(toks[j])
return out
def residue_hits(rel, body):
"""Gate item 7 on one file: [(line, why, matched text)], first hit per rule.
Code is where backreferences legitimately live: fenced blocks (at any
indentation) and inline spans are blanked first, keeping line numbers.
"""
prose = blank_fenced_code(body)
prose = re.sub(r"`[^`\n]*`", lambda m: " " * len(m.group(0)), prose)
exempt_slots = slots_are_intentional(rel, body)
hits = []
for rx, why in RESIDUE_RES:
if why == SLOT_WHY and exempt_slots:
continue
m = rx.search(prose)
if m:
hits.append((body.count("\n", 0, m.start()) + 1, why, m.group(0).strip()))
return hits
# (name, text, must_fail): each fixture pins one boundary of the residue
# check. Run with --selftest; exit 1 if any case disagrees.
RESIDUE_FIXTURES = [
("indented ``` block holding \\1 passes",
"1. Normalise:\n\n ```bash\n sed -E 's/x(y)/\\1/' f\n ```\n", False),
("indented ~~~ block holding \\1 passes",
"- step\n ~~~\n sed -E 's/(a)/\\1/'\n ~~~\n", False),
("column-0 ``` block holding \\1 passes",
"```\ns/(a)/\\1/\n```\n", False),
("indented prose line holding \\1 fails",
"1. Step\n\n Replace it with \\1 here.\n", True),
("prose after a closed indented fence fails",
" ```\n ok\n ```\n then \\1 leaked\n", True),
("a shorter or other-char line does not close the fence",
"````\n```\n~~~\ns/(a)/\\1/\n````\n", False),
("unclosed fence stays prose and fails",
" ```\n s/(a)/\\1/\n", True),
]
def roundtrip_case(after_pack):
"""Pack a three-file fixture skill (one the ceilings sidecar the bundle must
carry), apply `after_pack` to the directory, and report whether
verify_roundtrip() failed — None if the sidecar was not packed. Runs in a
temporary directory outside any staged tree."""
with tempfile.TemporaryDirectory() as tmp:
src = pathlib.Path(tmp) / "fixture-skill"
(src / "references").mkdir(parents=True)
(src / "SKILL.md").write_text('---\nname: "fixture-skill"\n---\nbody\n', encoding="utf-8")
(src / "references" / "a.md").write_text("one\n", encoding="utf-8")
(src / "references" / REF_CEILINGS_FILE).write_text("a.md 1\n", encoding="utf-8")
out = pathlib.Path(tmp) / "fixture-skill.skill"
written = pack(src, out)
if f"fixture-skill/references/{REF_CEILINGS_FILE}" not in written:
return None # the sidecar left out of the bundle
after_pack(src)
fails = []
verify_roundtrip(out, src, written, fails)
return bool(fails)
def _junk(src):
(src / "__pycache__").mkdir()
(src / "__pycache__" / "x.cpython-312.pyc").write_bytes(b"\0")
# (name, action on the directory after packing, must_fail): each pins one
# boundary of the --pack round-trip check.
SECOND_FM_FIXTURES = [
("duplicated header block", "---\nname: a\n---\n---\nname: a\n---\nbody\n", True),
("stray name: line after the header", "---\nname: a\n---\nname: a\nbody\n", True),
("two horizontal rules later in the body", "---\nname: a\n---\n\n# T\n\ntext\n\n---\n\n---\n\n## S\n", False),
]
# (name, SKILL.md body, paths command_paths must return)
COMMAND_PATH_FIXTURES = [
("inline run command with flags", "Run `python3 scripts/check.py --strict in.json` first.\n", {"scripts/check.py"}),
("fenced block, indented under a list item", "1. Build:\n\n ```bash\n cd x && python3 scripts/build.py --out dist\n ```\n", {"scripts/build.py"}),
("uv run", "`uv run scripts/a.py`\n", {"scripts/a.py"}),
("quoted example with no interpreter is skipped", "e.g. `scripts/x/generate.py --logo l.png`\n", set()),
("qualified path is skipped", "`python3 other-skill/scripts/a.py`\n", set()),
("repository-relative ./ path is skipped", "`python3 ./scripts/report.py --check`\n", set()),
("path outside code is skipped", "python3 scripts/a.py in prose\n", set()),
("py launcher", "`py scripts/a.py`\n", {"scripts/a.py"}),
("py -3 version selector", "`py -3 scripts/a.py --x`\n", {"scripts/a.py"}),
("py -3.12 version selector", "`py -3.12 scripts/a.py`\n", {"scripts/a.py"}),
("py -3 -X utf8, fenced", "```\npy -3 -X utf8 scripts/a.py\n```\n", {"scripts/a.py"}),
("python3 -X utf8", "`python3 -X utf8 scripts/a.py`\n", {"scripts/a.py"}),
("python -u and python -B", "`python -u scripts/a.py && python -B scripts/b.py`\n",
{"scripts/a.py", "scripts/b.py"}),
("python.exe and python3.12 spellings", "`python.exe scripts/a.py; python3.12 scripts/b.py`\n",
{"scripts/a.py", "scripts/b.py"}),
("bash -eu and bash -o pipefail", "`bash -eu scripts/a.sh; bash -o pipefail scripts/b.sh`\n",
{"scripts/a.sh", "scripts/b.sh"}),
("python3 -m pytest stays unchecked", "`python3 -m pytest scripts/test_x.py`\n", set()),
("bash -c stays unchecked", "`bash -c scripts/a.sh`\n", set()),
("npm run with -- stays unchecked", "`npm run build -- --out assets/out.png`\n", set()),
]
# The cited-path check end to end, over a minimal staged skill with no
# scripts/: (name, SKILL.md body, substring every failure must carry, or None
# when the body must pass; an optional fourth element lists files to stage
# beside SKILL.md). The `./` and `<skill-name>/` spellings are the two
# exemptions the failure message names; a `<slot>`/`{slot}` segment makes
# the span a naming pattern, matched as a glob.
CITED_PATH_FIXTURES = [
("unqualified prose path fails, naming both conventions",
"The `scripts/report.py` vs `pkg/` collision fails partial runs.\n",
"cite it as `./scripts/report.py`; both forms are exempt"),
("unqualified command path fails the same way",
"Run `python3 scripts/report.py --check` first.\n", "cite it as `./scripts/report.py`"),
("repository-relative prose path passes",
"The `./scripts/report.py` vs `pkg/` collision fails partial runs.\n", None),
("repository-relative command path passes",
"Run `python3 ./scripts/report.py --check` first.\n", None),
("another skill's qualified path passes",
"See `other-skill/references/x.md`.\n", None),
("a `<slot>` naming pattern passes when a staged file fits it",
"One file per study: `references/studies/<study>.md`.\n", None, ["references/studies/alpha.md"]),
("a `{slot}` naming pattern with no staged instance fails, naming the glob",
"One file per study: `references/studies/{study}.md`.\n",
"cited path pattern has no staged instance: references/studies/{study}.md (no file matches references/studies/*.md)"),
# a staged entry given as (path, text) stages that text: a reference
# file's fenced command is read for bundled paths like SKILL.md's
("a fenced command in a reference file naming a missing script fails, naming the file",
"Recipes: `references/how.md`.\n",
"cited path missing from staged set: scripts/run.py (in references/how.md)",
[("references/how.md", "# How\n\n```bash\npython3 scripts/run.py --all\n```\n")]),
("the same command with its script staged passes",
"Recipes: `references/how.md`.\n", None,
[("references/how.md", "# How\n\n```bash\npython3 scripts/run.py --all\n```\n"), "scripts/run.py"]),
("a bare path quoted in a reference file with no interpreter stays unchecked",
"Recipes: `references/how.md`.\n", None,
[("references/how.md", "# How\n\nThe runner is `scripts/run.py --all`.\n")]),
]
# --live and the orphan warning: (name, staged files, live files or None for
# a missing live dir, live-set failure substring or None, orphans warned).
# A file is (path, text); SKILL.md cites references/b.md, and b.md names a.md.
_LS_CORE = ("SKILL.md", "Read `references/b.md`.\n")
_LS_B = ("references/b.md", "# B\n\nThen a.md.\n")
_LS_A = ("references/a.md", "# A\n")
LIVE_SET_FIXTURES = [
("--live: a copy staged as SKILL.md alone fails, naming the dropped file",
[_LS_CORE], [_LS_CORE, _LS_B, _LS_A], "live file absent from staged set: references/a.md", []),
("--live: the full copy passes", [_LS_CORE, _LS_B, _LS_A], [_LS_CORE, _LS_B, _LS_A], None, []),
("--live: VCS metadata and build artefacts in live are not required",
[_LS_CORE, _LS_B, _LS_A], [_LS_CORE, _LS_B, _LS_A, (".git/HEAD", "x\n"),
("scripts/__pycache__/x.cpython-312.pyc", "x")], None, []),
("--live: a checkout's .claude-plugin/ manifests in live are not required",
[_LS_CORE, _LS_B, _LS_A], [_LS_CORE, _LS_B, _LS_A, (".claude-plugin/plugin.json", "{}\n"),
(".claude-plugin/marketplace.json", "{}\n")], None, []),
("--live: a nested plugin's .claude-plugin/ manifest in live is not required",
[_LS_CORE, _LS_B, _LS_A], [_LS_CORE, _LS_B, _LS_A,
("plugins/x/.claude-plugin/plugin.json", "{}\n")], None, []),
("--live: a nested .git/ in live is not required",
[_LS_CORE, _LS_B, _LS_A], [_LS_CORE, _LS_B, _LS_A, ("plugins/x/.git/HEAD", "x\n")], None, []),
("--live: a live path that is not a directory is skipped, no failure",
[_LS_CORE, _LS_B, _LS_A], None, None, []),
("orphan: a reference cited only from another reference is not warned",
[_LS_CORE, _LS_B, _LS_A], [_LS_CORE, _LS_B, _LS_A], None, []),
("orphan: a staged file named nowhere is warned, never failed",
[_LS_CORE, _LS_B, _LS_A, ("references/orphan.md", "# O\n")], [_LS_CORE, _LS_B, _LS_A], None,
["references/orphan.md"]),
]
def live_set_case(staged_files, live_files):
import contextlib
import io
with tempfile.TemporaryDirectory() as tmp:
roots = {}
for side, files in (("staged", staged_files), ("live", live_files or [])):
roots[side] = pathlib.Path(tmp) / side
roots[side].mkdir()
for rel, text in files:
(roots[side] / rel).parent.mkdir(parents=True, exist_ok=True)
(roots[side] / rel).write_text(text, encoding="utf-8")
fails = []
with contextlib.redirect_stdout(io.StringIO()):
orphans = check_orphans(roots["staged"])
check_live_set(roots["staged"], roots["live"] if live_files else pathlib.Path(tmp) / "none", fails)
return fails, orphans
ROUNDTRIP_FIXTURES = [
("fresh pack round-trips", lambda src: None, False),
("directory edited after packing fails",
lambda src: (src / "references" / "a.md").write_text("two\n", encoding="utf-8"), True),
("file added after packing fails",
lambda src: (src / "references" / "b.md").write_text("new\n", encoding="utf-8"), True),
("file removed after packing fails",
lambda src: (src / "references" / "a.md").unlink(), True),
("build artefact is not a member and not a mismatch", _junk, False),
]
# The session-start scan ships as scripts/session-start-scan.sh beside this
# file. Each case runs it against a throwaway workspace (with a space in its
# path) and pins one boundary: (name, scenario, args, exit status, stdout
# substring, checkpoint lines written, stdout substring that must be ABSENT).
# Skipped, not failed, where no bash is on PATH: the scan is a bash script
# and the gate is not. The "gap" and "recent" scenarios seed checkpoints.log
# with one earlier scan line, 21 and 2 days old; "moved" adds a MOVED.md.
SCAN_SCRIPT = pathlib.Path(__file__).resolve().parent / "session-start-scan.sh"
SCAN_FIXTURES = [
("healthy log scans: counts line, one checkpoint line", "healthy", True, 0,
"files: 2 parsed: 2 suspect (awk, a floor): 1", 1, "NOTE: pointer"),
("the suspect-YAML NOTE names each file with its rule and key, archive/ included", "susarch", True, 0,
"a colon in an unquoted list entry): 0002-b.md rule 3 title, archive/0009-z.md rule 5 source — quote", 1, "`x`"),
("no header parses: guard halts before the checkpoint", "broken", True, 1,
"SCAN COMMAND BROKEN", 0, ""),
("no workspace root: refused, nothing written", "healthy", False, 2, "", 0, ""),
("previous scan 21 days old: GAP line names its date", "gap", True, 0,
"GAP: the previous session-start scan ran ", 2, ""),
("previous scan 2 days old: no GAP line", "recent", True, 0, "files: 2", 2, "GAP:"),
("MOVED.md at the root: NOTE names it and its first line", "moved", True, 0,
'NOTE: pointer at this root (skill-observations/MOVED.md): "Moved to /new/root', 1, ""),
("the helper's skeleton (empty title) is UNFILLED, not LOST", "skeleton", True, 0,
"UNFILLED — a header with an empty title", 1, "LOST ENTRIES —"),
("id: below the filename prefix is named with its value", "idmis", True, 0,
"NOTE: id: does not read as the filename prefix", 1, ""),
("a zero-padded id reads as its prefix; only the wrong number is named", "padded", True, 0,
"after reading the body: 0004-d.md (id: 5)", 1, "0002-b.md (id"),
("a pre-3.0 log.md beside the directory: SPLIT STORE with its count", "split", True, 0,
"SPLIT STORE — log.md holds 2 observations not in observation-log/", 1, ""),
("use_evidence and next_actor in a header: parsed, not suspect", "fields", True, 0,
"files: 2 parsed: 2 suspect (awk, a floor): 0", 1, "NOTE:"),
("two files share a prefix across active and archive: DUPLICATE ID names both", "dupid", True, 0,
"DUPLICATE ID — 0002: 0002-b.md, archive/0002-z.md", 1, ""),
("a zero-padded and a bare prefix are one id", "dupid-pad", True, 0,
"DUPLICATE ID — 0002: 0002-b.md, 2-c.md", 1, ""),
("an active file byte-identical to its archive copy is RESURRECTED, not a duplicate", "resurrect", True, 0,
"RESURRECTED — 1 active file(s) byte-identical to their archive/ copy, a sync or mirror restoring archived entries: 0002-b.md;",
1, "DUPLICATE ID — 0002"),
("beside a resurrected pair, a real collision is still a DUPLICATE ID", "resurrect", True, 0,
"DUPLICATE ID — 0003: 0003-c.md, archive/0003-z.md", 1, ""),
("a resurrected entry is counted and left out of the entries print", "resurrect", True, 0,
"archive-suspect: 0 resurrected: 1", 1, "restored copy"),
("an unknown option is refused, nothing written", "healthy", True, 2, "", 0, "", ["--bogus"]),
("a workspace missing step 1's artefacts: DUE: workspace creation names them", "fresh", True, 0,
"DUE: workspace creation — missing: last-review-date.txt, cross-cutting-principles.md", 1, ""),
("no starter marker: DUE: starter-set reconciliation", "fresh", True, 0,
"DUE: starter-set reconciliation — skill-observations/starter-principles-reviewed.txt is absent", 1, ""),
("a marker below the shipped set: DUE names both versions", "oldmarker", True, 0,
"DUE: starter-set reconciliation — marker v1 < shipped set v", 1, "DUE: workspace creation"),
("the artefacts and a current marker: no DUE line", "healthy", True, 0, "files: 2", 1, "DUE: "),
("a marker with text beside the version: a NOTE quoting it, never parsed as other digits", "textmarker", True, 0,
"NOTE: starter-set marker skill-observations/starter-principles-reviewed.txt is not one line holding only a version number (line 1: 'v2 (13 imported)')",
1, "v213"),
("a current marker with a BOM and a CRLF ending: no DUE line, no NOTE", "crlfmarker", True, 0, "files: 2", 1,
"starter-set"),
("a recorded import with no imported entry in Active Principles: DUE: starter-set import lost", "lostimport",
True, 0, "DUE: starter-set import lost — checkpoints.log records 'starter set v5 reconciled: 3 imported (3, 7, 11)'",
2, ""),
("a recorded import with an imported entry still active: no DUE line", "keptimport", True, 0, "files: 2", 2,
"DUE: "),
("--skill-dir without a starter set: a NOTE, not a silent skip", "healthy", True, 0,
"NOTE: shipped starter set not found at /nonexistent/skill/references/starter-principles.md", 1, "DUE: ",
["--skill-dir", "/nonexistent/skill"]),
("the session-start record is printed with its measured items", "healthy", True, 0,
"session start: 1 storage=ok 2 scan=files 2 parsed 2", 1, ""),
("a missing artefact shows in the record's storage item", "fresh", True, 0,
"1 storage=missing: last-review-date.txt", 1, "1 storage=ok"),
("the pre-3.0 staging root: NOTE names it with its round count", "oldstage", True, 0,
"NOTE: legacy staging root skill-observations/skill-updates/ exists (2 round directories)", 1, ""),
("a resolved entry prints without its title; a value's # comment is dropped", "resolved", True, 0,
"2 | actioned | - | - | resolved 2026-01-01 — title withheld", 1, '"defect still present"'),
("a log one project level deeper (depth 4) is listed, with no checkpoints.log read as last=none",
"siblings", True, 0, "/work/projB=3 last=none", 1, "node_modules"),
("a sibling's entry count carries the date of its checkpoints.log's last line", "siblings", True, 0,
"/projA=1 last=2026-01-05", 1, "/c/d="),
("depth 5 is the bound: a log there is listed", "siblings", True, 0, "/a/b/c=1 last=none", 1, ".git"),
("a user-scope workspace is listed; past two folders below an anchor is not", "userscope", True, 0,
"/home dir/.claude=1 last=none ", 1, "/x/y="),
("the project identity root's memory/ workspace is listed", "userscope", True, 0,
"/home dir/.claude/projects/-w/memory=2 last=none", 1, ""),
("another root's log.md beside its directory: SPLIT STORE names that root", "splitsib", True, 0,
"/old: log.md holds 2 observations beside that root's observation-log/", 1, ""),
("a legacy count rides on another root's listing", "splitsib", True, 0,
"/old=1 last=none legacy=2", 1, ""),
("a log.md-only workspace is listed with -, not a split store", "splitsib", True, 0,
"/legacy=- last=none legacy=1", 1, "/legacy: log.md"),
("a header key written twice is a NOTE naming the file and the key, active and archive", "dupkey", True, 0,
"keep one line, never batch-rewrite: 0002-b.md (resolved), archive/0009-z.md (status)", 1, ""),
("a key-shaped run beside api_key: the file is named, never the match", "secret", True, 0,
"NOTE: 1 file(s) hold a key-shaped run beside key / token / secret / password (names only, never the match): 0002-b.md — read",
1, "sk9ABCdef"),
("a commit hash, a sha256 and a long path beside key words are not secrets", "secret", True, 0,
"files: 3", 1, "0003-c.md —"),
("the staging root beside skill-observations/ is named in one staged: line", "staged", True, 0,
"/skill-updates/PENDING.md (2 non-blank lines), 1 directories under it", 1, "SPLIT STAGING"),
("no staging root: the staged: line says so", "healthy", True, 0, "staged: no skill-updates/ at ", 1, ""),
("both staging roots: SPLIT STAGING replaces the legacy NOTE", "splitstage", True, 0,
"NOTE: SPLIT STAGING — staged work under both ", 1, "NOTE: legacy staging root"),
("no review yet: the review line counts every open entry, status-less ones included", "healthy", True, 0,
"review: none recorded (last-review-date.txt reads never); 2 open entries, never reviewed", 1, ""),
("a dated review: its age, and the open entries dated after it or undated", "reviewed", True, 0,
", 10 days ago; 3 open entries dated after it or undated, never reviewed", 1, ""),
]
def shipped_starter_version():
"""The `Starter set version:` the scan compares a marker against, read
from the reference beside scripts/; 999 where it is not there."""
sp = pathlib.Path(__file__).resolve().parent.parent / "references" / "starter-principles.md"
m = re.search(r"(?m)^Starter set version:\s*(\d+)", sp.read_text(encoding="utf-8")) if sp.is_file() else None
return m.group(1) if m else "999"
def scan_case(scenario, pass_root, extra=None, entries=None, after=None, headers=False,
under=None, env_path=None):
"""Run the scan script over a fixture workspace; return (status, stdout,
checkpoint lines written, sidecar text[, entries-file text when `entries`
names a file under the workspace to pass as --entries-to][, stderr when
`after` lists arguments to pass AFTER the root]). `under` passes a path
below the root as the root; `env_path` replaces PATH; "fresh" omits
step 1's artefacts and the starter marker."""
import os
import subprocess
with tempfile.TemporaryDirectory() as tmp:
root = pathlib.Path(tmp) / "work space"
log = root / "skill-observations" / "observation-log"
(log / "archive").mkdir(parents=True)
so = root / "skill-observations"
if scenario != "fresh":
(so / "last-review-date.txt").write_text("never\n", encoding="utf-8")
(so / "cross-cutting-principles.md").write_text("# P\n\n## Active Principles\n", encoding="utf-8")
(so / "starter-principles-reviewed.txt").write_text(
{"oldmarker": "1\n", "textmarker": "v2 (13 imported)\n", "crlfmarker": "\ufeff5\r\n"}.get(scenario, "5\n"),
encoding="utf-8")
if scenario == "reviewed": # a review 10 days ago; entries before, after and undated
import datetime
(so / "last-review-date.txt").write_text(
f"{datetime.date.today() - datetime.timedelta(days=10)}\n", encoding="utf-8")
fixture_skill = pathlib.Path(tmp) / "skill" # the shipped set the scan reads, wherever this copy runs
(fixture_skill / "references").mkdir(parents=True)
(fixture_skill / "references" / "starter-principles.md").write_text(
"# Starter principles\n\nStarter set version: 5\n", encoding="utf-8")
if scenario in ("oldstage", "splitstage"):
for rnd in ("2025-01-01", "2025-01-08"):
(so / "skill-updates" / rnd).mkdir(parents=True)
if scenario in ("staged", "splitstage"):
(root / "skill-updates" / "2025-02-01").mkdir(parents=True)
(root / "skill-updates" / "PENDING.md").write_text("# PENDING\n\n- an entry\n", encoding="utf-8")
if scenario == "siblings": # logs beside the root, at depths 3 to 6 under its parent, and pruned trees
for rel, k in (("projA", 1), ("work/projB", 3), ("a/b/c", 1), ("a/b/c/d", 1),
("node_modules/pkg", 1), (".git/x", 1)):
sl = pathlib.Path(tmp) / rel / "skill-observations" / "observation-log"
sl.mkdir(parents=True)
for j in range(1, k + 1):
(sl / f"{j:04d}-x.md").write_text(f"---\nid: {j}\n---\n", encoding="utf-8")
(pathlib.Path(tmp) / "projA" / "skill-observations" / "checkpoints.log").write_text(
"2026-01-05 09:00 [w] session-start scan: files=1 parsed=1 principles=absent\n", encoding="utf-8")
# HOME for the run, deeper than the parent's five levels: only the user-scope anchor reaches it
home = pathlib.Path(tmp) / "h" / "i" / "j" / "home dir"
if scenario == "userscope": # the user scope, an identity root's memory/, one past the bound
for rel, k in ((".claude", 1), (".claude/projects/-w/memory", 2), (".claude/projects/-w/x/y", 1)):
sl = home / rel / "skill-observations" / "observation-log"
sl.mkdir(parents=True)
for j in range(1, k + 1):
(sl / f"{j:04d}-x.md").write_text(f"---\nid: {j}\n---\n", encoding="utf-8")
if scenario == "splitsib": # a split store and a log.md-only workspace beside the root
so_old = pathlib.Path(tmp) / "old" / "skill-observations"
(so_old / "observation-log").mkdir(parents=True)
(so_old / "observation-log" / "0001-x.md").write_text("---\nid: 1\n---\n", encoding="utf-8")
(so_old / "log.md").write_text("### Observation 1: A\n\n### Observation 2: B\n", encoding="utf-8")
(pathlib.Path(tmp) / "legacy" / "skill-observations").mkdir(parents=True)
(pathlib.Path(tmp) / "legacy" / "skill-observations" / "log.md").write_text(
"### Observation 1: A\n", encoding="utf-8")
if scenario == "dupkey":
(log / "archive" / "0009-z.md").write_text('---\nid: 9\nstatus: actioned\nstatus: open\n---\n', encoding="utf-8")
if scenario == "resurrect":
(log / "archive" / "0002-b.md").write_text('---\nid: 2\ntitle: "restored copy"\nstatus: open\n---\n', encoding="utf-8")
(log / "archive" / "0003-z.md").write_text('---\nid: 3\ntitle: "old"\nstatus: actioned\n---\n', encoding="utf-8")
if scenario == "dupid":
(log / "archive" / "0002-z.md").write_text('---\nid: 2\ntitle: "old"\nstatus: actioned\n---\n', encoding="utf-8")
ck = root / "skill-observations" / "checkpoints.log"
ck.write_text("", encoding="utf-8")
if scenario in ("gap", "recent"):
import datetime
day = datetime.date.today() - datetime.timedelta(days=21 if scenario == "gap" else 2)
ck.write_text(f"{day} 09:00 [w] session-start scan: files=2 parsed=2 principles=absent\n",
encoding="utf-8")
if scenario in ("lostimport", "keptimport"): # a reconciliation that imported three entries
ck.write_text("2026-01-01 09:00 starter set v5 reconciled: 3 imported (3, 7, 11)\n", encoding="utf-8")
if scenario == "keptimport":
(so / "cross-cutting-principles.md").write_text(
"# P\n\n## Active Principles\n\n### 3. A rule\n**Origin:** imported from starter set (#3)\n",
encoding="utf-8")
if scenario == "broken":
(log / "0001-a.md").write_text('---\nid: 1\ntitle: "never closed"\n', encoding="utf-8")
else:
(log / "0001-a.md").write_text('---\nid: 1\ntitle: "ok"\n---\nbody\n', encoding="utf-8")
rest = {"skeleton": [("0002-b.md", '---\nid: 2\ntitle: ""\nstatus: open\nskill: []\n---\n')],
"idmis": [("0002-b.md", '---\nid: 1\ntitle: "retyped"\n---\n')],
# the two optional fields: a bare word, and an append-only list
"fields": [("0002-b.md", '---\nid: 2\ntitle: "DECIDED: fields"\nstatus: open\n'
'next_actor: review\nuse_evidence:\n'
' - 2026-01-02 accepted — one line of context\n'
' - 2026-01-03 used — unattended run\n---\n')],
# both id forms exist in live logs: padded and unpadded read as the prefix
"padded": [("0002-b.md", '---\nid: 0002\ntitle: "padded"\n---\n'),
("0003-c.md", '---\nid: 3\ntitle: "plain"\n---\n'),
("0004-d.md", '---\nid: 5\ntitle: "wrong"\n---\n')],
"dupid": [("0002-b.md", '---\nid: 2\ntitle: "new"\n---\n')],
"dupkey": [("0002-b.md", '---\nid: 2\ntitle: "twice"\nresolved:\nresolved: 2026-01-01\n---\n')],
"secret": [("0002-b.md", '---\nid: 2\ntitle: "leak"\n---\napi_key: sk9ABCdef1234567890ghijklmnopqrs\n'),
("0003-c.md", '---\nid: 3\ntitle: "digests"\n---\ncommit 0123456789abcdef0123456789abcdef01234567 key\n'
'sha256 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef password\n'
'token file: /home/user/projects/client-work/notes/token-handling-notes.md\n')],
"resurrect": [("0002-b.md", '---\nid: 2\ntitle: "restored copy"\nstatus: open\n---\n'),
("0003-c.md", '---\nid: 3\ntitle: "new"\n---\n')],
"dupid-pad": [("0002-b.md", '---\nid: 2\ntitle: "padded"\n---\n'),
("2-c.md", '---\nid: 2\ntitle: "bare"\n---\n')],
# the compact listing: parked last, a block list, a BOM, no header
"compact": [("0002-b.md", '---\nid: 2\nstatus: parked\nskill: [foo]\ntitle: "waits"\n---\n'),
("0003-c.md", '\ufeff---\nid: 3\nstatus: open\nskill:\n - foo\n - bar\n'
'proposes_skill: baz\ntitle: "bom"\nsiblings_checked: [x]\n---\n'),
("0004-d.md", "no header\n")],
# 0001-a (undated, no status) counts; 0002 is before the review, 0003 actioned
"reviewed": [("0002-b.md", '---\nid: 2\ntitle: "old"\nstatus: open\ndate: 2000-01-01\n---\n'),
("0003-c.md", '---\nid: 3\ntitle: "done"\nstatus: actioned\ndate: 2999-01-01\n---\n'),
("0004-d.md", '---\nid: 4\ntitle: "new"\nstatus: "open" # open\ndate: 2999-01-01\n---\n'),
("0005-e.md", '---\nid: 5\ntitle: "bare"\ndate: 2999-01-02\n---\n')],
"resolved": [("0002-b.md", '---\nid: 2\ntitle: "defect still present"\n'
'status: actioned # open | actioned\nresolved: 2026-01-01\n---\n')]}
for f, text in rest.get(scenario, [("0002-b.md", "---\nid: 2\ntitle: Fix: unquoted\n---\n")]):
(log / f).write_text(text, encoding="utf-8")
if scenario == "susarch":
(log / "archive" / "0009-z.md").write_text("---\nid: 9\nsource: `x`\n---\n", encoding="utf-8")
if scenario == "moved":
(root / "skill-observations" / "MOVED.md").write_text(
"Moved to /new/root on 2026-01-01\r\n", encoding="utf-8")
if scenario == "split":
(root / "skill-observations" / "log.md").write_text(
"### Observation 1: A\n\n### Observation 2: B\n", encoding="utf-8")
env = {k: v for k, v in os.environ.items() if k not in ("TASK_OBSERVER_WORKSPACE", "CLAUDE_CONFIG_DIR")}
home.mkdir(parents=True, exist_ok=True)
env["HOME"] = str(home)
import shutil
args = [shutil.which("bash") or "bash", str(SCAN_SCRIPT), "--skill-dir", str(fixture_skill)] + list(extra or [])
if env_path is not None:
env["PATH"] = env_path
ef = None
if entries is not None: # (name under the root, pre-existing text or None)
ef = root / entries[0]
if entries[1] is not None:
ef.write_text(entries[1], encoding="utf-8")
args += ["--entries-to", str(ef)]
args += [str(root / under) if under else str(root)] if pass_root else []
args += [str(root / a) if a.startswith("./") else a for a in (after or [])]
r = subprocess.run(args, cwd=tmp, env=env, capture_output=True, text=True,
encoding="utf-8", errors="replace")
side = root / "skill-observations" / "last-scan-findings.txt"
out = (r.returncode, r.stdout, len(ck.read_text(encoding="utf-8").splitlines()),
side.read_text(encoding="utf-8") if side.is_file() else None)
if entries is not None:
out += (ef.read_text(encoding="utf-8") if ef.is_file() else None,)
if after is not None or under is not None or env_path is not None:
out += (r.stderr,)
if headers:
hf = root / "skill-observations" / "last-scan-headers.txt"
out += (hf.read_text(encoding="utf-8") if hf.is_file() else None,)
return out
def scan_repeat_ok(scenario, prefix):
"""The finding line opening with `prefix` is printed above the entries,
repeated verbatim after them (before the end line), and is the whole
sidecar; with no prefix, the run must leave no finding and an EMPTY
sidecar. Returns (ok, detail)."""
rc, out, _, side = scan_case(scenario, True)
if not prefix:
return (rc == 0 and side == "" and ", repeated just above this line" in out
and "finding lines above the entries (DUE / NOTE / LOST ENTRIES / UNFILLED / DUPLICATE ID / RESURRECTED / SPLIT STORE / GAP): 0," in out,
f"sidecar {side!r}")
lines = [l for l in out.splitlines() if l.startswith(prefix)]
if len(lines) != 2 or lines[0] != lines[1]:
return False, f"{len(lines)} copies of the line"
first, second, end = out.index(lines[0]), out.rindex(lines[0]), out.rindex("end of scan")
entries_at = out.index("logs at the plausible anchors")
counted = re.search(r"GAP\): (\d+), repeated", out)
ok = (first < entries_at < second < end and side is not None and lines[0] + "\n" in side
and counted is not None and side.count("\n") == int(counted.group(1)))
return ok, f"positions {first} < {entries_at} < {second} < {end}, sidecar {side!r}"
# (name, scenario, prefix of the one finding line, or "" for a run with none)
SCAN_REPEAT_FIXTURES = [
("a NOTE is printed first, repeated after the entries, and is the sidecar", "idmis",
"NOTE: id: does not read as the filename prefix"),
("a GAP line is repeated and written the same way", "gap", "GAP: the previous session-start scan ran"),
("no finding: nothing repeated, the sidecar is written empty", "fields", ""),
("a DUPLICATE ID line is repeated, counted and written like the others", "dupid",
"DUPLICATE ID — 0002: 0002-b.md, archive/0002-z.md"),
]
def scan_entries_ok():
"""--entries-to: the per-entry headers land in the file and leave stdout;
the findings, counts and summary stay on stdout; the end line names the
file. Returns (ok, detail)."""
rc, out, ck, side, ent = scan_case("idmis", True, entries=("scan-entries.txt", None))
ok = (rc == 0 and ck == 1 and ent is not None and '| "retyped"' in ent and '| "ok"' in ent
and '"retyped"' not in out and "\n---\n" not in out and "files: 2 parsed: 2" in out
and out.count("NOTE: id: does not read as the filename prefix") == 2
and "entries written to " in out and "scan-entries.txt" in out
and side is not None and side.startswith("NOTE: id:"))
return ok, f"exit {rc}, checkpoint {ck}, entries {ent!r}, out tail {out[-300:]!r}"
def scan_compact_ok():
"""One line per entry with the four Step 2 fields and the id, parked
entries last, a `---` marker for a file whose header did not parse; the
whole headers in last-scan-headers.txt, which the end line names."""
rc, out, ck, side, hd = scan_case("compact", True, headers=True)
lines = [l for l in out.splitlines() if " | " in l or l.startswith("--- ")]
want = ['1 | - | - | - | "ok"', '3 | open | [foo, bar] | baz | "bom"',
"--- 0004-d.md (no header)", '2 | parked | [foo] | - | "waits"']
ok = (rc == 0 and sorted(lines[:3]) == sorted(want[:3]) and lines[3:] == want[3:]
and "siblings_checked" not in out and hd is not None and "siblings_checked: [x]" in hd
and hd.count("\n---\n") >= 3 and "full headers in " in out and "last-scan-headers.txt" in out
and "files: 4 parsed: 3" in out)
return ok, f"exit {rc}, lines {lines!r}, headers {hd!r}"
def scan_wrong_root_ok():
"""A root with no observation-log/ under it is refused by name before any
command runs: the log's own directory, skill-observations/, a directory
with neither (a first run) — exit 2, nothing on stdout, no checkpoint
line, no sidecar."""
res = []
for under, named in (("skill-observations/observation-log", "that is the log itself"),
("skill-observations/observation-log/archive", "a first run")):
rc, out, ck, side, err = scan_case("healthy", True, under=under)
res.append(rc == 2 and out == "" and ck == 0 and side is None and named in err
and "No such file" not in err)
return all(res), f"cases {res}"
def scan_child_root_ok():
"""A root named skill-observations/ that holds the log is resolved to its
parent: a NOTE line says so (and the sidecar carries it), the scan runs
normally, and the checkpoint line lands under the parent."""
rc, out, ck, side, err = scan_case("healthy", True, under="skill-observations")
want = "NOTE: root resolved: "
ok = (rc == 0 and ck == 1 and want in out and "(argument named skill-observations/)" in out
and "files: 2 parsed: 2" in out and side is not None and want in side)
return ok, f"exit {rc}, checkpoint {ck}, sidecar {side!r}, err {err!r}"
def scan_tools_missing_ok():
"""With the scan's commands off PATH the run halts: exit 1, SCAN TOOLS
MISSING on stdout and in the sidecar, no checkpoint line."""
rc, out, ck, side, err = scan_case("healthy", True, env_path="/nonexistent")
ok = rc == 1 and out.startswith("SCAN TOOLS MISSING —") and ck == 0 and side is not None \
and side.startswith("SCAN TOOLS MISSING —")
return ok, f"exit {rc}, checkpoint {ck}, out {out!r}, sidecar {side!r}"
def scan_size_ok():
"""Forty populated entries print in well under a 30,000-character tool
output cap: the listing is one line per entry."""
import os
import subprocess
with tempfile.TemporaryDirectory() as tmp:
root = pathlib.Path(tmp) / "work space"
log = root / "skill-observations" / "observation-log"
(log / "archive").mkdir(parents=True)
pad = "x" * 1500
for i in range(1, 41):
(log / f"{i:04d}-e.md").write_text(
f'---\nid: {i}\ntitle: "an observation title of ordinary length, number {i}"\nstatus: open\n'
f'type: open-source\nskill: [foo]\nsiblings_checked: "none"\nsession_context: "{pad}"\n---\nbody\n',
encoding="utf-8")
env = {k: v for k, v in os.environ.items() if k != "TASK_OBSERVER_WORKSPACE"}
r = subprocess.run(["bash", str(SCAN_SCRIPT), str(root)], cwd=tmp, env=env, capture_output=True,
text=True, encoding="utf-8", errors="replace")
return r.returncode == 0 and len(r.stdout) < 30000 and r.stdout.count(" | open | ") == 40, \
f"exit {r.returncode}, {len(r.stdout)} characters"
def scan_bytes_ok():
"""The end line names the bytes printed above it, counted in bytes (a
title with an em dash), and a halted run's output still reaches stdout
through the buffer."""
import os
import subprocess
with tempfile.TemporaryDirectory() as tmp:
root = pathlib.Path(tmp) / "work space"
log = root / "skill-observations" / "observation-log"
(log / "archive").mkdir(parents=True)
for i in range(1, 4):
(log / f"{i:04d}-e.md").write_text(f'---\nid: {i}\ntitle: "entry {i} \u2014 dash"\nstatus: open\n---\nbody\n',
encoding="utf-8")
env = {k: v for k, v in os.environ.items() if k != "TASK_OBSERVER_WORKSPACE"}
r = subprocess.run(["bash", str(SCAN_SCRIPT), str(root)], cwd=tmp, env=env, capture_output=True)
above, _, last = r.stdout.rstrip(b"\n").rpartition(b"\n")
m = re.search(rb"; (\d+) bytes above this line: ", last)
ok = r.returncode == 0 and last.startswith("end of scan".encode()) and m is not None \
and int(m.group(1)) == len(above) + 1
(log / "0004-x.md").write_text("no header\n", encoding="utf-8")
for i in range(1, 4):
(log / f"{i:04d}-e.md").write_text("no header either\n", encoding="utf-8")
h = subprocess.run(["bash", str(SCAN_SCRIPT), str(root)], cwd=tmp, env=env, capture_output=True)
ok = ok and h.returncode == 1 and b"SCAN COMMAND BROKEN" in h.stdout
return ok, f"exit {r.returncode}/{h.returncode}, end line {last[-160:]!r}, {len(above) + 1} bytes above"
def scan_disp_ok():
"""An actioned entry whose resolution: gives a skill: member no
disposition is named on a NOTE line with the member; a fully
dispositioned one and an open one are not."""
import os
import subprocess
with tempfile.TemporaryDirectory() as tmp:
root = pathlib.Path(tmp) / "work space"
log = root / "skill-observations" / "observation-log"
(log / "archive").mkdir(parents=True)
for i, st, sk, res in ((1, "actioned", "[a, b]", '"a: applied in x.md"'),
(2, "actioned", "\n - a\n - c", '"a: added; c: excluded, no such step"'),
(3, "open", "[a, b]", "")):
(log / f"{i:04d}-e.md").write_text(f'---\nid: {i}\ntitle: "t"\nstatus: {st}\nskill: {sk}\n'
f'resolution: {res}\n---\nbody\n', encoding="utf-8")
env = {k: v for k, v in os.environ.items() if k != "TASK_OBSERVER_WORKSPACE"}
r = subprocess.run(["bash", str(SCAN_SCRIPT), str(root)], cwd=tmp, env=env, capture_output=True,
text=True, encoding="utf-8", errors="replace")
lines = [l for l in r.stdout.splitlines() if "without a disposition for every skill: member" in l]
ok = r.returncode == 0 and len(lines) == 2 and all(l.endswith(": 0001-e.md (b)") for l in lines)
return ok, f"exit {r.returncode}, lines {lines!r}"
def _scan_ws(root):
"""A step-1-complete workspace at `root` holding one entry, 0001-a.md."""
so = root / "skill-observations"
(so / "observation-log" / "archive").mkdir(parents=True)
(so / "last-review-date.txt").write_text("never\n", encoding="utf-8")
(so / "cross-cutting-principles.md").write_text("# P\n\n## Active Principles\n", encoding="utf-8")
(so / "starter-principles-reviewed.txt").write_text("5\n", encoding="utf-8")
(so / "observation-log" / "0001-a.md").write_text('---\nid: 1\ntitle: "ok"\n---\nbody\n', encoding="utf-8")
def _scan_run(args, cwd, home, extra_env=None, path_prefix=None):
import os
import subprocess
import time
env = {k: v for k, v in os.environ.items() if k not in ("TASK_OBSERVER_WORKSPACE", "CLAUDE_CONFIG_DIR",
"TASK_OBSERVER_SEARCH_SECONDS")}
env["HOME"] = str(home)
env.update(extra_env or {})
if path_prefix:
env["PATH"] = str(path_prefix) + os.pathsep + env.get("PATH", "")
t0 = time.monotonic()
r = subprocess.run(["bash", str(SCAN_SCRIPT), *map(str, args)], cwd=str(cwd), env=env, capture_output=True,
text=True, encoding="utf-8", errors="replace", timeout=120)
return r.returncode, r.stdout, r.stderr, time.monotonic() - t0
def scan_order_ok():
"""The entries print BEFORE the sibling-log search's listing: a
stalled search can no longer hold them back."""
rc, out, *_ = scan_case("healthy", True)
e, l, end = out.find('1 | - | - | - | "ok"'), out.find("logs at the plausible anchors"), out.rfind("end of scan")
return rc == 0 and -1 < e < l < end, f"exit {rc}, entry at {e}, logs line at {l}, end at {end}"
def scan_stall_ok():
"""A sibling-log search that stalls (a `find` stub that sleeps on the
parent anchor) is cut at TASK_OBSERVER_SEARCH_SECONDS=1: exit 0 well
inside 10 seconds, the entries printed, a NOTE naming the limit and the
anchor printed and repeated, the sidecar carrying it, the end line last."""
import shutil
with tempfile.TemporaryDirectory() as tmp:
t = pathlib.Path(tmp)
root, home, stub = t / "work space", t / "home dir", t / "stub bin"
_scan_ws(root)
home.mkdir()
stub.mkdir()
real = shutil.which("find") or "/usr/bin/find"
(stub / "find").write_text(f'#!/bin/bash\n[ "$1" = "${{STALL_ON:-}}" ] && exec sleep 30\nexec "{real}" "$@"\n',
encoding="utf-8")
(stub / "find").chmod(0o755)
rc, out, err, secs = _scan_run([root], t, home, {"STALL_ON": str(t), "TASK_OBSERVER_SEARCH_SECONDS": "1"}, stub)
want = f"NOTE: sibling-log search stopped at its 1-second limit while searching {t} ("
side = root / "skill-observations" / "last-scan-findings.txt"
side = side.read_text(encoding="utf-8") if side.is_file() else ""
ok = (rc == 0 and secs < 10 and '1 | - | - | - | "ok"' in out and out.count(want) == 2 and want in side
and out.rstrip("\n").splitlines()[-1].startswith("end of scan") and out.find('| "ok"') < out.find(want))
return ok, f"exit {rc}, {secs:.1f}s, out tail {out[-400:]!r}, err {err[-200:]!r}"
def scan_home_parent_ok():
"""A root whose parent is HOME (a ~/.claude workspace) searches the home
folder four levels deep, Library pruned, other users' homes skipped, and
the listing says so: ~/a/p2 is listed, ~/a/b/p3 (five), ~/Library/p4 and
a log under a sibling of HOME are not."""
with tempfile.TemporaryDirectory() as tmp:
t = pathlib.Path(tmp)
home = t / "home dir"
root = home / ".claude"
_scan_ws(root)
for rel in ("home dir/a/p2", "home dir/a/b/p3", "home dir/Library/p4", "other user/q"):
(t / rel / "skill-observations" / "observation-log").mkdir(parents=True)
rc, out, err, _ = _scan_run([root], t, home)
line = next((l for l in out.splitlines() if l.startswith("logs at the plausible anchors")), "")
ok = (rc == 0 and "the home folder as parent: searched 4 levels, Library and .Trash pruned" in line
and f"{home}/a/p2=0 last=none" in line and "/p3=" not in line and "/p4=" not in line
and "/other user/" not in line)
return ok, f"exit {rc}, line {line!r}"
def scan_spellings_ok():
"""Two spellings of one directory are one log: HOME is a symlink to the
real home that holds the root (~/.claude) and a CLAUDE_CONFIG_DIR log, so
the parent anchor and the user-scope anchors find each twice. The listing
names the root once, in its pinned spelling, and the other log once."""
import os
with tempfile.TemporaryDirectory() as tmp:
t = pathlib.Path(tmp).resolve()
home, link = t / "home dir", t / "home link"
root = home / ".claude"
_scan_ws(root)
(home / "cfg" / "skill-observations" / "observation-log").mkdir(parents=True)
os.symlink(home, link)
rc, out, err, _ = _scan_run([root], t, link, {"CLAUDE_CONFIG_DIR": str(link / "cfg")})
line = next((l for l in out.splitlines() if l.startswith("logs at the plausible anchors")), "")
ok = (rc == 0 and line.count(" last=") == 2 and f" {root}=1 last=" in line and f" {home}/cfg=0 last=" in line
and "home link" not in line)
return ok, f"exit {rc}, line {line!r}"
def scan_anchor_case(where):
"""The scan with a second log at the working directory ("cwd"), beside
the skill's install reached through a symlink ("install"), or the cwd a
symlink to the pinned root itself ("self"). Returns (status, stdout,
the second log's directory)."""
import os
with tempfile.TemporaryDirectory() as tmp:
t = pathlib.Path(tmp)
root, home = t / "work space", t / "home dir"
_scan_ws(root)
home.mkdir()
repo = t / "repo dir"
(repo / "skill-observations" / "observation-log").mkdir(parents=True)
for j in (1, 2):
(repo / "skill-observations" / "observation-log" / f"000{j}-x.md").write_text(f"---\nid: {j}\n---\n", encoding="utf-8")
agents = t / "agents home"
inst = agents / "skills" / "task-observer"
(inst / "references").mkdir(parents=True)
(inst / "SKILL.md").write_text("---\nname: task-observer\n---\n", encoding="utf-8")
(inst / "references" / "starter-principles.md").write_text("Starter set version: 5\n", encoding="utf-8")
(agents / "skill-observations" / "observation-log").mkdir(parents=True)
os.symlink(inst, t / "skill link")
os.symlink(root, t / "root link")
args, cwd, second = [root], t, None
if where == "cwd":
cwd, second = repo, repo
elif where == "install":
args, second = ["--skill-dir", t / "skill link", root], agents
elif where == "self":
cwd = t / "root link"
rc, out, err, _ = _scan_run(args, cwd, home)
return rc, out, str(second.resolve()) if second else None
# (name, scenario, substring the SPLIT STORE line must hold after its path, or None for no such line)
SCAN_ANCHOR_FIXTURES = [
("a log at the working directory that is not the pinned root: SPLIT STORE names it, above the entries",
"cwd", " (2 entries, last scan none), at the working directory, not the pinned root "),
("a log beside the skill's resolved install: SPLIT STORE names it and the install",
"install", " (0 entries, last scan none), beside the skill's install ("),
("the working directory a symlink to the pinned root: no SPLIT STORE line", "self", None),
]
def scan_anchor_ok(scenario, want):
rc, out, second = scan_anchor_case(scenario)
lines = [l for l in out.splitlines() if l.startswith("SPLIT STORE — a second observation log at ")]
if want is None:
return rc == 0 and not lines and "files: 1" in out, f"exit {rc}, lines {lines!r}"
head = f"SPLIT STORE — a second observation log at {second}{want}"
ok = (rc == 0 and len(lines) == 2 and lines[0] == lines[1] and lines[0].startswith(head)
and out.find(lines[0]) < out.find('1 | - | - | - | "ok"') < out.rfind(lines[0]))
return ok, f"exit {rc}, lines {lines!r}"
def scan_entries_refused_ok():
"""--entries-to onto an existing non-empty file is refused before anything
runs: exit 2, no checkpoint line, the file untouched."""
rc, out, ck, side, ent = scan_case("healthy", True, entries=("scan-entries.txt", "another session's scan\n"))
ok = rc == 2 and ck == 0 and out == "" and ent == "another session's scan\n"
return ok, f"exit {rc}, checkpoint {ck}, entries {ent!r}"
def scan_trailing_ok():
"""An argument after the root is refused by name before anything runs —
the misplaced --entries-to that once fell back silently to stdout, and a
bare second positional: exit 2, no checkpoint line, no sidecar."""
res = []
for after, named in ((["--entries-to", "./e.txt"], "'--entries-to'"), (["extra"], "'extra'")):
rc, out, ck, side, err = scan_case("healthy", True, after=after)
res.append(rc == 2 and ck == 0 and out == "" and side is None
and f"argument after the workspace root: {named}" in err)
return all(res), f"cases {res}"
def scan_entries_empty_ok():
"""--entries-to that leaves its file empty while numbered files exist is
a broken run: a NOTE in the summary block and the sidecar, exit 3."""
import os
if not os.path.exists("/dev/null"):
return True, "no /dev/null: skipped"
rc, out, ck, side = scan_case("healthy", True, extra=["--entries-to", "/dev/null"])
want = "NOTE: entries file '/dev/null' is empty beside files: 2"
ok = rc == 3 and ck == 1 and want in out and side is not None and want in side and "EMPTY (exit 3)" in out
return ok, f"exit {rc}, checkpoint {ck}, sidecar {side!r}"
def scan_version_ok():
"""The end line names the script's VERSION, and VERSION equals the
skill's frontmatter `metadata.version` (or a top-level `version:`) when
SKILL.md sits beside scripts/."""
text = SCAN_SCRIPT.read_text(encoding="utf-8")
m = re.search(r'(?m)^VERSION="([^"]+)"', text)
if not m:
return False, "no VERSION constant in the script"
rc, out, *_ = scan_case("healthy", True)
ok = rc == 0 and f"session-start-scan.sh v{m.group(1)}" in out.splitlines()[-1]
detail = f"end line {out.splitlines()[-1][-80:]!r}"
skill_md = SCAN_SCRIPT.parent.parent / "SKILL.md"
if skill_md.is_file():
fv = frontmatter_version(frontmatter(skill_md.read_text(encoding="utf-8"))) # metadata.version, else top level
ok = ok and fv == m.group(1)
detail += f", script {m.group(1)} vs skill {fv}"
return ok, detail
# scripts/skill-load.sh, the per-skill lookup run beside each Skill
# invocation: (name, skill argument, absolute root?, exit status, stdout
# substring, checkpoint lines written[, "nolog"]). The fixture holds one
# match, one prefix-only name, one closed entry, one body-only mention and
# two target_file entries; "nolog" runs it against a root with no
# skill-observations/ at all (the first run, before step 1), "noroot"
# against a root that does not exist under an existing parent. The
# substring is matched against stdout and stderr together.
LOAD_SCRIPT = pathlib.Path(__file__).resolve().parent / "skill-load.sh"
LOAD_FIXTURES = [
("exact name, open only, frontmatter only", "foo", True, 0, "foo: 1 open observations\n0001-a.md", 1),
("plugin-qualified listing finds the bare-name entry", "plug:foo", True, 0,
"plug:foo: 1 open observations\n0001-a.md", 1),
("relative root: refused, nothing written", "foo", False, 2, "", 0),
("a file name finds the target_file entry by its last segment", "reviewer.md", True, 0,
"reviewer.md: 1 open observations\n0005-e.md", 1),
("the bare skill name does not match the file name", "reviewer", True, 0,
"reviewer: 1 open observations\n0006-f.md", 1),
("no log yet: one NOTE line, exit 0, nothing written", "foo", True, 0,
"NOTE: foo: no observation log yet at ", 0, "nolog"),
("no root yet: refused, the message names the first-run branch", "foo", True, 2,
"this is a first run (run Workspace creation, then re-run this lookup); otherwise the pin is wrong", 0, "noroot"),
("a second skill name: refused, nothing written", "foo", True, 2, "", 0, "", ("bar",)),
("a list in one argument: refused, nothing written", "foo, bar", True, 2, "", 0),
]
def load_case(skill, absolute, scenario="", opts=()):
import os
import subprocess
with tempfile.TemporaryDirectory() as tmp:
root = pathlib.Path(tmp) / "work space"
log = root / "skill-observations" / "observation-log"
ck = root / "skill-observations" / "checkpoints.log"
if scenario == "nolog":
root.mkdir(parents=True)
elif scenario == "noroot":
pass
else:
log.mkdir(parents=True)
ck.write_text("", encoding="utf-8")
for f, head, body in [("0001-a.md", "skill: [foo, bar]\nstatus: open", ""),
("0002-b.md", "skill: [foo-extras]\nstatus: open", ""),
("0003-c.md", "skill: foo\nstatus: actioned", ""),
("0004-d.md", "skill: [bar]\nstatus: open", "skill: foo\n"),
("0005-e.md", "skill: []\ntarget_file: [.claude/agents/reviewer.md]\nstatus: open", ""),
("0006-f.md", "skill: [reviewer]\nstatus: open", "")]:
(log / f).write_text(f"---\nid: 1\n{head}\n---\n{body}", encoding="utf-8")
arg = str(root) if absolute else os.path.relpath(root, tmp)
r = subprocess.run(["bash", str(LOAD_SCRIPT), arg, skill, *opts], cwd=tmp, capture_output=True,
text=True, encoding="utf-8", errors="replace")
written = len(ck.read_text(encoding="utf-8").splitlines()) if ck.is_file() else 0
return r.returncode, r.stdout + r.stderr, written
def tools_missing_ok(script, slug_first):
"""With the script's commands off PATH it names them and stops: exit 1,
a TOOLS MISSING line, no checkpoint line, no file. `slug_first`: the
helper's argument order (slug, root) rather than skill-load's (root, name)."""
import os
import shutil
import subprocess
with tempfile.TemporaryDirectory() as tmp:
root = pathlib.Path(tmp) / "work space"
log = root / "skill-observations" / "observation-log"
(log / "archive").mkdir(parents=True)
ck = root / "skill-observations" / "checkpoints.log"
ck.write_text("", encoding="utf-8")
args = ["x-y", str(root)] if slug_first else [str(root), "foo"]
env = {k: v for k, v in os.environ.items() if k != "TASK_OBSERVER_WORKSPACE"}
env["PATH"] = "/nonexistent"
r = subprocess.run([shutil.which("bash") or "/bin/bash", str(script), *args], cwd=tmp, env=env,
capture_output=True, text=True, encoding="utf-8", errors="replace")
made = sorted(p.name for p in log.rglob("*") if p.is_file())
written = ck.read_text(encoding="utf-8")
ok = r.returncode == 1 and "TOOLS MISSING —" in r.stdout + r.stderr and not made and not written
return ok, f"exit {r.returncode}, files {made}, checkpoint {written!r}, out {(r.stdout + r.stderr)!r}"
def load_query_ok():
"""--query-only prints what the lookup prints and appends nothing; an
argument after it is refused."""
rc0, out0, ck0 = load_case("reviewer.md", True)
rc1, out1, ck1 = load_case("reviewer.md", True, opts=("--query-only",))
rc2, _, ck2 = load_case("reviewer.md", True, opts=("--query-only", "x"))
ok = rc0 == rc1 == 0 and out0 == out1 and "0005-e.md" in out1 and ck0 == 1 and ck1 == 0 and rc2 == 2 and ck2 == 0
return ok, f"exits {rc0}/{rc1}/{rc2}, checkpoint lines {ck0}/{ck1}/{ck2}, out {out1!r}"
# skill-load.sh --correct, the line that follows a refused Skill call:
# (name, run the lookup first?, reason, exit status, checkpoint lines in order).
LOAD_CORRECT_FIXTURES = [
("--correct after the lookup: loaded then NOT loaded, nothing printed", True,
"refused: disable-model-invocation", 0, ["loaded x", "NOT loaded x — refused: disable-model-invocation"]),
("--correct with no loaded line today: still written", False, "refused", 0, ["NOT loaded x — refused"]),
("--correct with no reason: refused, nothing written", False, "", 2, []),
]
def load_correct_case(lookup_first, reason):
import subprocess
with tempfile.TemporaryDirectory() as tmp:
root = pathlib.Path(tmp) / "work space"
log = root / "skill-observations" / "observation-log"
log.mkdir(parents=True)
(log / "0001-a.md").write_text("---\nid: 1\nskill: [x]\nstatus: open\n---\n", encoding="utf-8")
ck = root / "skill-observations" / "checkpoints.log"
run = lambda *a: subprocess.run(["bash", str(LOAD_SCRIPT), str(root), "x", *a], cwd=tmp,
capture_output=True, text=True, encoding="utf-8", errors="replace")
if lookup_first:
run()
r = run("--correct", reason)
lines = ck.read_text(encoding="utf-8").splitlines() if ck.is_file() else []
return r.returncode, r.stdout, [ln[17:].split(" — ")[0] if ln[17:].startswith("loaded") else ln[17:]
for ln in lines]
# scripts/diff-staged.sh, the gate's installed-vs-staged compare with one
# verdict line: (name, scenario, exit status, verdict-line prefix). Both
# fixture skills sit under a path with a space; "requoted" differs from live
# only in the installer's `name:` quoting.
DIFFSTAGED_SCRIPT = pathlib.Path(__file__).resolve().parent / "diff-staged.sh"
DIFFSTAGED_FIXTURES = [
("an installer-requoted name: is IDENTICAL", "requoted", 0, "IDENTICAL"),
("a changed, an added and a removed file: DIFFERS names all three", "differs", 1,
"DIFFERS 3 path(s): references/a.md; staged only: references/new.md; live only: references/old.md"),
("a live checkout's .claude-plugin/ is not a difference", "checkout", 0, "IDENTICAL"),
("a missing live path is ERROR, never identical", "missing", 2, "ERROR missing: "),
("a file where a directory belongs is ERROR", "file", 2, "ERROR not a directory: "),
("one argument is ERROR", "onearg", 2, "ERROR usage: "),
("a joined string of two paths is ERROR naming the joined string", "joined", 2, "ERROR missing: "),
]
def diffstaged_case(scenario):
import subprocess
with tempfile.TemporaryDirectory() as tmp:
live, staged = pathlib.Path(tmp) / "live dir" / "sk", pathlib.Path(tmp) / "staged dir" / "sk"
for d, name in ((live, '"sk"'), (staged, "sk" if scenario == "requoted" else '"sk"')):
(d / "references").mkdir(parents=True)
(d / "SKILL.md").write_text(f"---\nname: {name}\ndescription: d\n---\nbody\n", encoding="utf-8")
(d / "references" / "a.md").write_text("a\n", encoding="utf-8")
if scenario == "differs":
(staged / "references" / "a.md").write_text("b\n", encoding="utf-8")
(staged / "references" / "new.md").write_text("n\n", encoding="utf-8")
(live / "references" / "old.md").write_text("o\n", encoding="utf-8")
if scenario == "checkout":
(live / ".claude-plugin").mkdir()
(live / ".claude-plugin" / "plugin.json").write_text("{}\n", encoding="utf-8")
args = {"missing": [str(staged), str(live) + "-gone"], "file": [str(staged), str(live / "SKILL.md")],
"onearg": [str(staged)], "joined": [f"{staged} {live}", str(live)]}.get(scenario, [str(staged), str(live)])
r = subprocess.run(["bash", str(DIFFSTAGED_SCRIPT), *args], cwd=tmp, capture_output=True,
text=True, encoding="utf-8", errors="replace")
return r.returncode, r.stdout
# scripts/bin-check.sh, the digest gate in front of the workspace copy of the
# scripts: (name, scenario, exit status, stdout substring, stderr substring).
# The fixture .bin/ holds one script that echoes its arguments; the digests
# file is computed over a copy standing in for the installed scripts.
BINCHECK_SCRIPT = pathlib.Path(__file__).resolve().parent / "bin-check.sh"
BINCHECK_FIXTURES = [
("every digest matches: the script runs with its arguments", "match", 0, "hello a b", ""),
("the .bin/ copy differs from the installed script: refused, nothing runs", "differs", 3, "", "BIN REFUSED — hello.sh differs"),
("a .bin/ file with no installed digest: refused", "extra", 3, "", "has no digest in the installed set"),
("the named script is absent from .bin/: refused", "absent", 3, "", "BIN REFUSED — no 'gone.sh'"),
("no digests file: usage, exit 2", "nodig", 2, "", "digests file missing"),
("installed version newer than the MANIFEST's verified_against: refused", "older", 3, "", "is newer than .bin/MANIFEST verified_against 3.8.0"),
("installed version equal to verified_against: the script runs", "same", 0, "hello a b", ""),
("--installed-version newer than verified_against: refused", "flag", 3, "", "installed 3.10.0 is newer"),
("installed version known, MANIFEST without verified_against: refused", "nover", 3, "", "has no verified_against: line"),
("the MANIFEST passed as the digests file: refused", "selfdig", 3, "", "it is the MANIFEST"),
("no installed version anywhere: gate skipped with a note, digests decide", "match", 0, "hello a b", "version gate skipped"),
("an indented metadata.version line in the digests file is read: newer than verified_against, refused",
"metaolder", 3, "", "installed 3.9.0 is newer than .bin/MANIFEST verified_against 3.8.0"),
]
def bincheck_case(scenario):
import hashlib
import subprocess
with tempfile.TemporaryDirectory() as tmp:
root = pathlib.Path(tmp) / "work space"
bin_dir = root / "skill-observations" / ".bin"
bin_dir.mkdir(parents=True)
installed = pathlib.Path(tmp) / "installed"
installed.mkdir()
(installed / "hello.sh").write_text('echo hello "$@"\n', encoding="utf-8")
(bin_dir / "hello.sh").write_text('echo hello "$@"\n', encoding="utf-8")
if scenario == "differs":
(bin_dir / "hello.sh").write_text('echo hello "$@" # older\n', encoding="utf-8")
if scenario == "extra":
(bin_dir / "extra.py").write_text("print(1)\n", encoding="utf-8")
dig = pathlib.Path(tmp) / "installed.sha256"
sums = "".join(f"{hashlib.sha256(p.read_bytes()).hexdigest()} {p}\n"
for p in sorted(installed.iterdir()))
head = 'version: "3.9.0"\n' if scenario in ("older", "same", "nover", "selfdig") else ""
if scenario == "metaolder":
head = ' version: "3.9.0"\n'
dig.write_text(head + sums, encoding="utf-8")
manifest = bin_dir / "MANIFEST"
va = {"older": "3.8.0", "metaolder": "3.8.0", "same": "3.9.0", "flag": "3.9.0", "selfdig": "3.9.0"}.get(scenario)
manifest.write_text((f"verified_against: {va}\n" if va else "") + sums, encoding="utf-8")
if scenario == "selfdig":
dig = manifest
flag = ["--installed-version", "3.10.0"] if scenario == "flag" else []
args = ["bash", str(BINCHECK_SCRIPT), *flag, str(root),
str(dig if scenario != "nodig" else pathlib.Path(tmp) / "none"),
"gone.sh" if scenario == "absent" else "hello.sh", "a", "b"]
r = subprocess.run(args, cwd=tmp, capture_output=True, text=True, encoding="utf-8", errors="replace")
return r.returncode, r.stdout, r.stderr
def _py_stubs(tmp, python_works):
"""A directory to put first on PATH: `python3` (and, unless python_works,
`python`) is a Windows Store alias stand-in that prints the install hint
and exits 9009; with python_works, `python` runs this interpreter."""
import os
d = pathlib.Path(tmp) / "stub bin"
d.mkdir()
alias = '#!/bin/sh\necho "Python was not found; run without arguments to install from the Microsoft Store" >&2\nexit 9009\n'
(d / "python3").write_text(alias, encoding="utf-8")
(d / "python").write_text(f'#!/bin/sh\nexec "{sys.executable}" "$@"\n' if python_works else alias, encoding="utf-8")
for f in d.iterdir():
f.chmod(0o755)
env = {k: v for k, v in os.environ.items()}
env["PATH"] = str(d) + os.pathsep + env.get("PATH", "")
return env
def diffstaged_nopy_case(python_works, meta=False):
"""diff-staged.sh with python3 a Store-alias stub: the live name: quoted,
the staged one bare (the installer's quoting), and with python_works a
changed body line too; with meta, a metadata.version quoted on one side
and bare on the other. Returns (status, stdout, stderr)."""
import subprocess
with tempfile.TemporaryDirectory() as tmp:
live, staged = pathlib.Path(tmp) / "live dir" / "sk", pathlib.Path(tmp) / "staged dir" / "sk"
for d, name, body in ((live, '"sk"', "body"), (staged, "sk", "body2" if python_works else "body")):
d.mkdir(parents=True)
mv = ('"1.0"' if d == live else "1.0") if meta else ""
md = f"metadata:\n version: {mv}\n" if meta else ""
(d / "SKILL.md").write_text(f"---\nname: {name}\ndescription: d\n{md}---\n{body}\n", encoding="utf-8")
r = subprocess.run(["bash", str(DIFFSTAGED_SCRIPT), str(staged), str(live)], cwd=tmp, env=_py_stubs(tmp, python_works),
capture_output=True, text=True, encoding="utf-8", errors="replace")
return r.returncode, r.stdout, r.stderr
# (name, python works as `python`?, exit status, stdout prefix, stderr substring or "", stderr must lack)
DIFFSTAGED_NOPY_FIXTURES = [
("python3 and python Store-alias stubs: an identical copy is IDENTICAL by the text fallback, stderr says no working Python 3",
False, 0, "IDENTICAL", "diff-staged: no working Python 3", "compare failed"),
("python3 a stub, python a working Python 3: the parsed compare runs (a body difference named as body:)",
True, 1, "DIFFERS 1 path(s): SKILL.md (body: DIFFERS", "", "no working Python 3"),
("no working Python: a metadata.version quoted on one side only is IDENTICAL by the text fallback",
"meta", 0, "IDENTICAL", "diff-staged: no working Python 3", "compare failed"),
]
def bincheck_py_case(python_works):
"""bin-check.sh asked to run a .py whose digests match, with python3 a
Store-alias stub. Returns (status, stdout, stderr)."""
import hashlib
import subprocess
with tempfile.TemporaryDirectory() as tmp:
root = pathlib.Path(tmp) / "work space"
bin_dir = root / "skill-observations" / ".bin"
bin_dir.mkdir(parents=True)
src = 'import sys\nprint("hello py", *sys.argv[1:])\n'
(bin_dir / "hello.py").write_text(src, encoding="utf-8")
dig = pathlib.Path(tmp) / "installed.sha256"
dig.write_text(f"{hashlib.sha256(src.encode()).hexdigest()} /installed/scripts/hello.py\n", encoding="utf-8")
r = subprocess.run(["bash", str(BINCHECK_SCRIPT), str(root), str(dig), "hello.py", "a", "b"], cwd=tmp,
env=_py_stubs(tmp, python_works), capture_output=True, text=True, encoding="utf-8", errors="replace")
return r.returncode, r.stdout, r.stderr
# (name, python works as `python`?, exit status, stdout substring or "", stderr substring or "")
BINCHECK_PY_FIXTURES = [
("a .py with only Store-alias stubs on PATH: BIN REFUSED — no working Python 3, exit 3, nothing ran",
False, 3, "", "BIN REFUSED — no working Python 3 to run 'hello.py'"),
("a .py with python3 a stub and python a working Python 3: it runs under python",
True, 0, "hello py a b", ""),
]
# scripts/migrate-log.py, the pre-3.0 log converter: (name, legacy entry's
# **Skill:** line, overrides for entry 88 or None, exit status, substring the
# written file 0088-*.md must hold, substring it must NOT hold). The known
# skills are companion-a and companion-b.
MIGRATE_SCRIPT = pathlib.Path(__file__).resolve().parent / "migrate-log.py"
MIGRATE_FIXTURES = [
("override siblings_checked and target_file reach the file", "???",
{"_resolves": ["skill-name-unparseable"], "_reason": "t", "skill": ["companion-a"],
"siblings_checked": "PLANTED", "target_file": ["PLANTED/T.md"]}, 0,
'target_file: ["PLANTED/T.md"]\nsiblings_checked: "PLANTED"', None),
("an override key the file cannot carry stops the run", "companion-a",
{"sibling_checked": "typo"}, 2, None, None),
("a string where a list belongs stops the run", "companion-a",
{"skill": "companion-a"}, 2, None, None),
("a known skill inside a qualifier is a review flag, not area", "companion-a (also touches companion-b A9)",
None, 0, "needs review: skill-in-qualifier", "area:"),
("a plain qualifier is still promoted to area", "companion-a (section 3)",
None, 0, 'area: "section 3"', "migration_note"),
("a --known-skills path that is not a directory stops the run", "companion-a",
"BAD-SKILLS-DIR", 2, None, None),
]
def migrate_case(skill_line, ov):
"""Convert a one-entry legacy log; return (status, text of 0088-*.md or None)."""
import json
import subprocess
with tempfile.TemporaryDirectory() as tmp:
t = pathlib.Path(tmp)
for k in ("companion-a", "companion-b"):
(t / "skills" / k).mkdir(parents=True)
(t / "log.md").write_text("### Observation 88: T\n**Date:** 2026-01-01\n**Status:** OPEN\n"
f"**Skill:** {skill_line}\n\n**Issue:** x\n", encoding="utf-8")
args = [sys.executable, str(MIGRATE_SCRIPT), "--convert", str(t / "log.md"),
"--out", str(t / "out"), "--known-skills",
str(t / ("missing" if ov == "BAD-SKILLS-DIR" else "skills"))]
if isinstance(ov, dict):
(t / "ov.json").write_text(json.dumps({"88": ov}), encoding="utf-8")
args += ["--overrides", str(t / "ov.json")]
r = subprocess.run(args, capture_output=True, text=True, encoding="utf-8", errors="replace")
files = sorted((t / "out").glob("0088-*.md")) if (t / "out").is_dir() else []
return r.returncode, files[0].read_text(encoding="utf-8") if files else None
def migrate_count_ok():
"""The conformance count agrees with the written files, field by field,
on a converted set where one record's siblings_checked is empty: the
count reads render_header(), the block render() writes."""
import json
import subprocess
with tempfile.TemporaryDirectory() as tmp:
t = pathlib.Path(tmp)
(t / "skills" / "companion-a").mkdir(parents=True)
(t / "log.md").write_text("".join(f"### Observation {i}: T{i}\n**Date:** 2026-01-01\n**Status:** OPEN\n"
f"**Skill:** companion-a\n\n**Issue:** x\n\n---\n\n" for i in (88, 89)),
encoding="utf-8")
(t / "ov.json").write_text(json.dumps({"88": {"siblings_checked": "none", "_reason": "t"}}), encoding="utf-8")
r = subprocess.run([sys.executable, str(MIGRATE_SCRIPT), "--convert", str(t / "log.md"), "--out", str(t / "out"),
"--known-skills", str(t / "skills"), "--overrides", str(t / "ov.json")],
capture_output=True, text=True, encoding="utf-8", errors="replace")
heads = [p.read_text(encoding="utf-8").split("\n---", 1)[0] for p in sorted((t / "out").glob("00*.md"))]
got = {}
for field in ("status", "siblings_checked"):
m = re.search(rf"^ {field}\s+(\d+)/(\d+)", r.stdout, re.M)
got[field] = (int(m.group(1)), int(m.group(2))) if m else None
want = {f: (sum(f"\n{f}:" in h for h in heads), len(heads)) for f in got}
ok = r.returncode == 0 and len(heads) == 2 and got == want and want["siblings_checked"] == (1, 2)
return ok, f"exit {r.returncode}, counted {got}, files {want}"
# scripts/new-observation.sh, the only write path where a script can run.
# Each case runs it against a throwaway workspace (with a space in its path)
# and pins one boundary: (name, scenario, slug, body text or None, exit
# status, stdout substring, stderr substring, names of the numbered files
# the log holds afterwards, the floor file's content or None). GOOD_BODY
# is a header the schema accepts, with the two placeholders and a backticked
# command span that must reach the file verbatim.
NEWOBS_SCRIPT = pathlib.Path(__file__).resolve().parent / "new-observation.sh"
# The core template's fields (SKILL.md, File format), in order: the skeleton
# the helper writes without --body must carry exactly these.
SKELETON_FIELDS = ["id", "title", "status", "type", "skill", "proposes_skill", "target_file",
"siblings_checked", "area", "date", "session_context", "parked_until",
"resolved", "resolution", "reference", "commands_verified", "next_actor",
"use_evidence", "escalated"]
GOOD_BODY = ('---\nid: __ID__\ntitle: "t"\nstatus: open # open | actioned\n'
'type: open-source # open-source | internal\nskill: [foo]\n'
'siblings_checked: "none — no family"\ndate: __DATE__\n---\n\n'
'**Issue:** `$(date)` on __DATE__ as #__ID__\n')
NEWOBS_FIXTURES = [
("empty log: the path is printed, the skeleton holds the id, the floor moves",
"empty", "first-slug", None, 0, "/0001-first-slug.md", "", ["0001-first-slug.md"], "1"),
("a claimed number is skipped: 0002 issued over a claim on 0001",
"claimed", "second", None, 0, "/0002-second.md", "", ["0002-second.md"], "2"),
("--body: id and date filled, the backticked span intact",
"empty", "with-body", GOOD_BODY, 0, "/0001-with-body.md", "", ["0001-with-body.md"], "1"),
("--body file missing: refused, nothing created",
"nobody", "slug", None, 1, "", "missing or unreadable", [], None),
("--body with status actioned: refused by name, nothing created",
"empty", "slug", GOOD_BODY.replace("status: open ", "status: actioned "), 1, "",
"status: must read open", [], None),
("--body with status parked and a parked_until condition: created in one write",
"empty", "parked", GOOD_BODY.replace("status: open ", "status: parked ").replace(
"date: __DATE__", 'date: __DATE__\nparked_until: "the upstream fix ships"'), 0,
"/0001-parked.md", "", ["0001-parked.md"], "1"),
("--body with status parked and an empty parked_until: refused by name, nothing created",
"empty", "slug", GOOD_BODY.replace("status: open ", "status: parked ").replace(
"date: __DATE__", "date: __DATE__\nparked_until: # the condition"), 1, "",
"status: parked needs a non-empty parked_until:", [], None),
("--body with a type outside the vocabulary: refused",
"empty", "slug", GOOD_BODY.replace("type: open-source ", "type: process "), 1, "",
"type: must be open-source or internal", [], None),
("--body with an empty siblings_checked: refused",
"empty", "slug", GOOD_BODY.replace('siblings_checked: "none — no family"', 'siblings_checked: ""'),
1, "", "siblings_checked: must be non-empty", [], None),
("a prefix in use under another slug the listing cannot see: COLLISION, no file",
"hidden", "slug", None, 1, "", "COLLISION", [], None),
("a slug carrying an id prefix: refused",
"empty", "0001-slug", None, 1, "", "must not start with an id prefix", [], None),
("two files share prefix 0007: refused naming both and the renumber, nothing claimed",
"dup7", "slug", None, 1, "", "id 7 is carried by both 0007-a.md and 0007-b.md", ["0007-a.md", "0007-b.md"], None),
("an active file byte-identical to its archive copy: RESURRECTED, never a renumber, nothing claimed",
"resurrect7", "slug", None, 1, "", "RESURRECTED — 0007-a.md is byte-identical to archive/0007-a.md",
["0007-a.md"], None),
("after the renumber (the later file moved out of the listing): 8 is issued",
"dup7-moved", "renumbered", None, 0, "/0008-renumbered.md", "", ["0007-a.md", "0008-renumbered.md"], "8"),
("--body with an unquoted ': ' in a value: refused naming the key, nothing created",
"empty", "slug", GOOD_BODY.replace("date: __DATE__", "area: tooling: yaml shape\ndate: __DATE__"), 1, "",
"area: holds an unquoted ': '", [], None),
("--body with the same value quoted: created",
"empty", "quoted", GOOD_BODY.replace("date: __DATE__", 'area: "tooling: yaml shape"\ndate: __DATE__'), 0,
"/0001-quoted.md", "", ["0001-quoted.md"], "1"),
("--body with text after a closing quote: refused",
"empty", "slug", GOOD_BODY.replace('title: "t"', 'title: "t" extra'), 1, "",
"title: has text after its closing quote", [], None),
("--body with a 201-character title: refused naming the length and the limit, nothing created",
"empty", "slug", GOOD_BODY.replace('title: "t"', 'title: "' + "x" * 201 + '"'), 1, "",
"title: is 201 characters, over the 200-character limit", [], None),
("--body with a 200-character title of two-byte letters: counted in characters, created",
"empty", "long-title", GOOD_BODY.replace('title: "t"', 'title: "' + "\u00e9" * 200 + '"'), 0,
"/0001-long-title.md", "", ["0001-long-title.md"], "1"),
]
def disp_shared_ok():
"""The dispositions program is one text in the scan and the batch field
editor: the lines between `# >>> disp` and `# <<< disp` are identical."""
def part(path):
m = re.search(r"(?ms)^# >>> disp\b[^\n]*\n(.*?)^# <<< disp$", path.read_text(encoding="utf-8"))
return m.group(1) if m else None
a, b = part(SCAN_SCRIPT), part(SETFIELDS_SCRIPT)
return a is not None and a == b, f"scan {len(a or '')} chars, set-fields {len(b or '')} chars"
def sus_shared_ok():
"""The suspect-YAML program is one text in three scripts: the lines
between the `# >>> sus` and `# <<< sus` markers are identical in the
scan, the creation helper and the batch field editor."""
def part(path):
text = path.read_text(encoding="utf-8")
m = re.search(r"(?ms)^# >>> sus\b[^\n]*\n(.*?)^# <<< sus$", text)
return m.group(1) if m else None
a, b, c = part(SCAN_SCRIPT), part(NEWOBS_SCRIPT), part(SETFIELDS_SCRIPT)
return a is not None and a == b == c, \
f"scan {len(a or '')} chars, helper {len(b or '')} chars, set-fields {len(c or '')} chars"
# scripts/set-fields.sh, the checked path for changing several existing
# entries: (name, scenario, plan lines (tab-joined), --check?, exit status,
# substring of stdout+stderr, {file: lines expected to differ from before}
# — None = every file byte-identical after the run).
SETFIELDS_SCRIPT = pathlib.Path(__file__).resolve().parent / "set-fields.sh"
_T = "\t"
SETFIELDS_FIXTURES = [
("a clean plan: each file differs from its old text on exactly the named lines", "plain",
[_T.join(["set", "0001-a.md", "status", "actioned"]), _T.join(["set", "0001-a.md", "resolved", "2026-01-02"]),
_T.join(["set", "0002-b.md", "resolution", '"done: staged"'])], False, 0,
"done — 2 file(s) written and re-read", {"0001-a.md": 2, "0002-b.md": 1, "0003-c.md": 0}),
("one new text carrying another entry's id: (B over A) refuses the WHOLE plan, nothing written", "plain",
[_T.join(["set", "0003-c.md", "status", "actioned"]), _T.join(["set", "0001-a.md", "id", "2"])], False, 1,
"would not read as its filename prefix", None),
("a named key that occurs twice in a header refuses the plan", "dupkey",
[_T.join(["set", "0001-a.md", "status", "actioned"]), _T.join(["set", "0002-b.md", "resolved", "2026-01-02"])],
False, 1, "header key(s) occur twice: resolved", None),
("rename: a fresh id above the floor, filename and id: together, the old number in the body", "plain",
[_T.join(["rename", "0002-b.md", "next"])], False, 0, "renamed 0002-b.md -> 0006-b.md", "rename"),
("--check runs phase 1 only and writes nothing", "plain",
[_T.join(["set", "0001-a.md", "status", "actioned"])], True, 0, "PLAN OK", None),
("a value the scan's suspect rules flag is refused", "plain",
[_T.join(["set", "0001-a.md", "title", "Fix: unquoted"])], False, 1, "looks like invalid YAML", None),
("a key absent from the header is refused, not appended", "plain",
[_T.join(["set", "0001-a.md", "nope", "x"])], False, 1, "key nope occurs 0 times", None),
("a key holding a block value is refused", "block",
[_T.join(["set", "0001-a.md", "skill", "[a]"])], False, 1, "holds a block value", None),
("a plan line that is not tab-separated is refused by line number", "plain",
["set 0001-a.md status actioned"], False, 1, "plan line 1 is not", None),
("actioned with a skill: member given no disposition: refused naming it", "family",
[_T.join(["set", "0001-a.md", "status", "actioned"]),
_T.join(["set", "0001-a.md", "resolution", '"a: applied in x.md"'])], False, 1,
"no disposition for skill: member(s) b", None),
("actioned with every member dispositioned (a qualified name by its bare form): written", "family",
[_T.join(["set", "0001-a.md", "status", "actioned"]),
_T.join(["set", "0001-a.md", "resolution", '"a: applied in x.md:4; p:b: excluded, never reads it"'])], False, 0,
"done — 1 file(s) written", {"0001-a.md": 2}),
("a partial close missing a numbered point: refused, and the run traced in checkpoints.log", "family",
[_T.join(["set", "0001-a.md", "status", "actioned"]),
_T.join(["set", "0001-a.md", "resolution", '"a: applied; p:b: carried by #9; (1) landed at x.md:3; (2) not a point"'])],
False, 1, "set-fields point check: 0001-a.md points=3 missing=3 refused", None),
("a partial close accounting for every numbered point: written, traced as passed", "family",
[_T.join(["set", "0001-a.md", "status", "actioned"]),
_T.join(["set", "0001-a.md", "resolution",
'"a: applied; p:b: carried by #9; (1) landed at x.md:3; (2) not a point; (3) carried by #9"'])],
False, 0, "points=3 missing=- passed", {"0001-a.md": 2}),
("--check runs the point check but writes no trace line", "family",
[_T.join(["set", "0001-a.md", "status", "actioned"]),
_T.join(["set", "0001-a.md", "resolution", '"a: applied; p:b: carried by #9; (1) landed at x.md:3"'])],
True, 1, "accounts for no numbered point(s) 2,3 of 3", None),
("a title: over 200 characters is refused naming the length and the limit, nothing written", "plain",
[_T.join(["set", "0001-a.md", "title", '"' + "x" * 201 + '"'])], False, 1,
"0001-a.md: title: is 201 characters, over the 200-character limit", None),
("a 200-character title: of two-byte letters is counted in characters and written", "plain",
[_T.join(["set", "0001-a.md", "title", '"' + "\u00e9" * 200 + '"'])], False, 0,
"done — 1 file(s) written", {"0001-a.md": 1}),
]
def setfields_case(scenario, plan, check):
"""Run set-fields.sh over a fixture log (three entries, .id-floor 5);
return (status, stdout+stderr, {name: text} before, {name: text} after,
floor text)."""
import os
import subprocess
with tempfile.TemporaryDirectory() as tmp:
root = pathlib.Path(tmp) / "work space"
log = root / "skill-observations" / "observation-log"
(log / "archive").mkdir(parents=True)
(log / "archive" / ".id-floor").write_text("5\n", encoding="utf-8")
for i, s in ((1, "a"), (2, "b"), (3, "c")):
extra = ""
if scenario == "dupkey" and i == 2:
extra = "resolved: 2026-01-01\n"
if scenario == "block" and i == 1:
extra = "skill:\n - a\n"
body = f"body {i}"
if scenario == "family" and i == 1: # two members, three numbered points, one after Principle
extra = 'skill: [a, "p:b"]\n'
body = "**Issue:** (1) one\n(2) two\n\n**Suggested improvement:**\n3. three\n\n**Principle:** (4) not a point"
(log / f"{i:04d}-{s}.md").write_text(
f'---\nid: {i}\ntitle: "{s}"\nstatus: open\nresolved:\n{extra}resolution:\n---\n\n{body}\n', encoding="utf-8")
before = {p.name: p.read_text(encoding="utf-8") for p in log.glob("[0-9]*.md")}
(pathlib.Path(tmp) / "plan.tsv").write_text("\n".join(plan) + "\n", encoding="utf-8")
args = ["bash", str(SETFIELDS_SCRIPT)] + (["--check"] if check else []) + [str(root), str(pathlib.Path(tmp) / "plan.tsv")]
r = subprocess.run(args, cwd=tmp, capture_output=True, text=True, encoding="utf-8", errors="replace",
env={k: v for k, v in os.environ.items() if k != "TASK_OBSERVER_WORKSPACE"})
after = {p.name: p.read_text(encoding="utf-8") for p in log.glob("[0-9]*.md")}
floor = (log / "archive" / ".id-floor").read_text(encoding="utf-8").strip()
stray = [p.name for p in log.iterdir() if p.name.startswith(".")]
ck = root / "skill-observations" / "checkpoints.log"
trace = " TRACE " + ck.read_text(encoding="utf-8") if ck.is_file() else ""
return r.returncode, r.stdout + r.stderr + ("".join(f" STRAY {s}" for s in stray)) + trace, before, after, floor
def setfields_ok(scenario, plan, check, want_rc, want_out, want_diff):
rc, out, before, after, floor = setfields_case(scenario, plan, check)
ok = rc == want_rc and want_out in out and "STRAY" not in out
ok = ok and not (check and "TRACE" in out)
if want_diff is None:
ok = ok and before == after and floor == "5"
elif want_diff == "rename":
new = after.get("0006-b.md", "")
old_lines, new_lines = before["0002-b.md"].splitlines(), new.splitlines()
changed = [j for j, (a, b) in enumerate(zip(old_lines, new_lines)) if a != b]
ok = (ok and "0002-b.md" not in after and floor == "6" and "id: 6" in new_lines
and new_lines[-1].startswith("Renumbered from 2 to 6 on ") and len(new_lines) == len(old_lines) + 2
and [old_lines[j] for j in changed] == ["id: 2"])
else:
for name, n in want_diff.items():
a, b = before[name].splitlines(), after[name].splitlines()
ok = ok and len(a) == len(b) and sum(x != y for x, y in zip(a, b)) == n
ok = ok and [l for l in b if l.startswith("id:")] == [l for l in a if l.startswith("id:")]
return ok, f"exit {rc}, out {out.strip()[-200:]!r}, floor {floor!r}"
# scripts/extend-observation.sh, the path for appending an instance to an
# existing entry: (name, scenario, args before the id and root, id, exit
# status, stderr substring, check over ({name: text} before, after, stdout)).
# The fixture log: 0001 open, 0002 actioned, 0003 parked, 0005 with a block
# session_context, archive/0004 actioned; scenario "dup" adds archive/0001.
EXTOBS_SCRIPT = pathlib.Path(__file__).resolve().parent / "extend-observation.sh"
_EXT_BODY = 'Second instance: `$(date)` stays "verbatim".\n'
def _ext_appended(b, a, name, sc):
old, new = b[name].splitlines(), a.get(name, "").splitlines()
changed = [j for j in range(len(old)) if j < len(new) and old[j] != new[j]]
return (len(changed) == 1 and new[changed[0]] == f"session_context: {sc}"
and a[name].endswith("\n\n" + _EXT_BODY) and len(new) == len(old) + 2)
EXTOBS_FIXTURES = [
("an open entry: the instance appended, session_context joined and quoted, nothing else changed", "plain",
["--session", 'review "two"'], "1", 0, "",
lambda b, a, out: _ext_appended(b, a, "0001-a.md", '"first: one; review \\"two\\""')
and out.strip().endswith("/0001-a.md") and sorted(a) == sorted(b)),
("an id no file carries: NO SUCH ENTRY, no file created", "plain", ["--session", "s"], "9", 1,
"NO SUCH ENTRY — id 9", lambda b, a, out: a == b),
("an archived entry: ENTRY CLOSED with its resolution printed, nothing written", "plain",
["--session", "s"], "0004", 1, 'archived, status actioned; nothing written. Its resolution: "landed in x.md"',
lambda b, a, out: a == b),
("an actioned entry still in the active log: ENTRY CLOSED", "plain", ["--session", "s"], "2", 1,
"ENTRY CLOSED — 0002-b.md is status actioned", lambda b, a, out: a == b),
("--reopen on an archived entry: moved back, status open, resolved emptied, the re-open line first", "plain",
["--reopen", "--session", "s"], "4", 0, "",
lambda b, a, out: "archive/0004-d.md" not in a and "status: open\n" in a.get("0004-d.md", "")
and "\nresolved:\n" in a["0004-d.md"] and "\nRe-opened on " in a["0004-d.md"]
and a["0004-d.md"].endswith(_EXT_BODY) and 'resolution: "landed in x.md"' in a["0004-d.md"]),
("a parked entry: appended, status left parked, with a NOTE", "plain", ["--session", "s"], "3", 0,
"is parked", lambda b, a, out: _ext_appended(b, a, "0003-c.md", '"s"') and "status: parked\n" in a["0003-c.md"]),
("a block session_context: refused, nothing written", "plain", ["--session", "s"], "5", 1,
"holds a block value", lambda b, a, out: a == b),
("two files carry the id: DUPLICATE ID, nothing written", "dup", ["--session", "s"], "1", 1,
"DUPLICATE ID — id 1 is carried by 0001-a.md and archive/0001-z.md", lambda b, a, out: a == b),
("a missing body file: refused, nothing written", "nobody", ["--session", "s"], "1", 1,
"missing, unreadable or blank", lambda b, a, out: a == b),
]
def extobs_case(scenario, opts, ident):
"""Run extend-observation.sh over the fixture log; return (status,
stdout, stderr, {name: text} before, after) — archived names carry
their archive/ prefix."""
import os
import subprocess
with tempfile.TemporaryDirectory() as tmp:
root = pathlib.Path(tmp) / "work space"
log = root / "skill-observations" / "observation-log"
(log / "archive").mkdir(parents=True)
for rel, i, st, extra in (("0001-a.md", 1, "open", 'session_context: "first: one"\nresolved:\n'),
("0002-b.md", 2, "actioned", 'session_context: ""\nresolved: 2026-01-01\n'),
("0003-c.md", 3, "parked", "session_context:\nresolved:\n"),
("archive/0004-d.md", 4, "actioned", "session_context: bare\nresolved: 2026-01-01\n"),
("0005-e.md", 5, "open", "session_context:\n - one\nresolved:\n")):
res = 'resolution: "landed in x.md"\n' if st == "actioned" else "resolution:\n"
(log / rel).write_text(f'---\nid: {i}\ntitle: "t{i}"\nstatus: {st}\n{extra}{res}---\n\nbody {i}\n',
encoding="utf-8")
if scenario == "dup":
(log / "archive" / "0001-z.md").write_text("---\nid: 1\nstatus: actioned\n---\n", encoding="utf-8")
snap = lambda: {str(p.relative_to(log)): p.read_text(encoding="utf-8")
for p in list(log.glob("*.md")) + list(log.glob("archive/*.md")) + list(log.glob(".*"))}
before = snap()
args = ["bash", str(EXTOBS_SCRIPT)] + opts
if scenario != "nobody":
(pathlib.Path(tmp) / "inst.md").write_text(_EXT_BODY, encoding="utf-8")
args += ["--body-file", str(pathlib.Path(tmp) / "inst.md"), ident, str(root)]
r = subprocess.run(args, cwd=tmp, capture_output=True, text=True, encoding="utf-8", errors="replace",
env={k: v for k, v in os.environ.items() if k != "TASK_OBSERVER_WORKSPACE"})
return r.returncode, r.stdout, r.stderr, before, snap()
# scripts/stage-patch.sh, the staging command for a non-skill file's patch:
# (name, live text, changed text, --allow-repeat headings, live file suffix,
# exit status, stdout prefix, patch file written?). "EXISTS" as the changed
# text means the patch path already holds a file.
STAGEPATCH_SCRIPT = pathlib.Path(__file__).resolve().parent / "stage-patch.sh"
_SP_LIVE = "# Notes\n\n## Render settings\n\nwidth 80\n\n```sh\n# run it\n```\n"
STAGEPATCH_FIXTURES = [
("a heading the live file already has: HEADING REPEATED with its line, no patch",
_SP_LIVE, _SP_LIVE + "\n## Render settings\n\nwidth 72\n", [], ".md", 1,
"HEADING REPEATED — no patch written", False),
("a new heading only: STAGED", _SP_LIVE, _SP_LIVE + "\n## Fonts\n\nserif\n", [], ".md", 0, "STAGED", True),
("a section moved within the file keeps its count: STAGED",
_SP_LIVE, "# Notes\n\nlead\n\n```sh\n# run it\n```\n\n## Render settings\n\nwidth 80\n", [], ".md", 0,
"STAGED", True),
("a heading-shaped line inside fenced code is not a heading: STAGED",
_SP_LIVE, _SP_LIVE + "\n```sh\n# run it\n```\n", [], ".md", 0, "STAGED", True),
("an intended repeat named with --allow-repeat: STAGED", _SP_LIVE,
_SP_LIVE + "\n## Render settings\n\nagain\n", ["## Render settings"], ".md", 0, "STAGED", True),
("a file that is not Markdown: the check is skipped and said to be", "# a: 1\nb: 2\n", "# a: 1\nb: 3\n# a: 1\n",
[], ".yaml", 0, "STAGED", True),
("an existing patch path is never overwritten: ERROR", _SP_LIVE, "EXISTS", [], ".md", 2, "ERROR", None),
("no change: NO CHANGE, nothing staged", _SP_LIVE, _SP_LIVE, [], ".md", 1, "NO CHANGE", False),
]
def stagepatch_case(live, changed, allow, suffix):
"""Run stage-patch.sh; return (status, stdout, patch text or None)."""
import subprocess
with tempfile.TemporaryDirectory() as tmp:
t = pathlib.Path(tmp) / "a dir"
t.mkdir()
(t / f"live{suffix}").write_text(live, encoding="utf-8")
out = t / "live.patch"
if changed == "EXISTS":
out.write_text("earlier\n", encoding="utf-8")
changed = live + "x\n"
(t / f"changed{suffix}").write_text(changed, encoding="utf-8")
args = ["bash", str(STAGEPATCH_SCRIPT)]
for h in allow:
args += ["--allow-repeat", h]
r = subprocess.run(args + [str(t / f"live{suffix}"), str(t / f"changed{suffix}"), str(out)],
capture_output=True, text=True, encoding="utf-8", errors="replace")
return r.returncode, r.stdout, out.read_text(encoding="utf-8") if out.is_file() else None
def newobs_case(scenario, slug, body):
"""Run the helper over a fixture workspace; return (status, stdout,
stderr, numbered files in the log, floor content or None, created text)."""
import os
import subprocess
with tempfile.TemporaryDirectory() as tmp:
root = pathlib.Path(tmp) / "work space"
log = root / "skill-observations" / "observation-log"
(log / "archive").mkdir(parents=True)
if scenario == "claimed":
(log / "archive" / ".id-claims").mkdir()
(log / "archive" / ".id-claims" / "0001").write_text("", encoding="utf-8")
if scenario in ("dup7", "dup7-moved"):
(log / "0007-a.md").write_text('---\nid: 7\ntitle: "earlier"\n---\n', encoding="utf-8")
later = log / ("0007-b.md" if scenario == "dup7" else ".0007-b.md")
later.write_text('---\nid: 7\ntitle: "later"\n---\n', encoding="utf-8")
if scenario == "resurrect7":
for f in (log / "0007-a.md", log / "archive" / "0007-a.md"):
f.write_text('---\nid: 7\ntitle: "restored"\nstatus: open\n---\n', encoding="utf-8")
if scenario == "hidden":
(log / "other").mkdir()
(log / "other" / "0001-x.md").write_text("---\nid: 1\n---\n", encoding="utf-8")
args = ["bash", str(NEWOBS_SCRIPT)]
if scenario == "nobody":
args += ["--body", str(pathlib.Path(tmp) / "absent.md")]
elif body is not None:
(pathlib.Path(tmp) / "body.md").write_text(body, encoding="utf-8")
args += ["--body", str(pathlib.Path(tmp) / "body.md")]
args += [slug, str(root)]
env = {k: v for k, v in os.environ.items() if k != "TASK_OBSERVER_WORKSPACE"}
r = subprocess.run(args, cwd=tmp, env=env, capture_output=True, text=True,
encoding="utf-8", errors="replace")
files = sorted(p.name for p in log.glob("[0-9]*.md"))
floor = log / "archive" / ".id-floor"
made = pathlib.Path(r.stdout.strip()) if r.stdout.strip() else None # the file this run created
text = made.read_text(encoding="utf-8") if made and made.is_file() else ""
if scenario == "dup7-moved" and not (log / "archive" / ".id-claims" / "0008").is_file():
text = "" # the claim must be the issued number
return (r.returncode, r.stdout, r.stderr, files,
floor.read_text(encoding="utf-8").strip() if floor.is_file() else None, text)
def ref_shape_case(lines, triggers, sidecar):
"""Run check_reference_shape over a one-reference fixture skill: a.md of
`lines` lines declaring `triggers` load triggers (None = no declaration),
beside `sidecar` as references/ceilings.txt (None = not opted in). Returns
the failures."""
with tempfile.TemporaryDirectory() as tmp:
refs = pathlib.Path(tmp) / "fixture-skill" / "references"
refs.mkdir(parents=True)
head = ["# A", ""]
if triggers is not None:
head += ["Load triggers: " + "; ".join(f"episode {i}" for i in range(triggers)), ""]
body = head + ["## Contents", "", "- S", "", "## S"]
body += ["text"] * (lines - len(body))
(refs / "a.md").write_text("\n".join(body) + "\n", encoding="utf-8")
if sidecar is not None:
(refs / REF_CEILINGS_FILE).write_text(sidecar, encoding="utf-8")
fails = []
import contextlib
import io
with contextlib.redirect_stdout(io.StringIO()): # the shape line is not the verdict
check_reference_shape(refs.parent, "Load `references/a.md` (\"S\") when S.\n", fails)
return fails
# (name, lines, declared triggers, sidecar, substring every failure set must
# hold — None = must pass, substring a failure must NOT hold): the growth
# barrier's boundaries, with N = SPLIT_TRIGGER_THRESHOLD and the tolerance.
REF_SHAPE_FIXTURES = [
("no sidecar: never gated, even far over any size and trigger count",
5000, 40, None, None, None),
("no sidecar and no declaration: still not gated", 5000, None, None, None, None),
("under ceiling, inside tolerance", 98, 3, "a.md 100\n", None, None),
("at the tolerance boundary (slack 3) passes", 97, 3, "a.md 100\n", None, None),
("over ceiling, <= N triggers: trim or reasoned raise, never split",
105, SPLIT_TRIGGER_THRESHOLD, "a.md 100\n", "trim it back", "split"),
("reasoned raise clears it (a short reason beside the number)",
105, 3, "a.md 105 one new episode section, single-trigger\n", None, None),
("over ceiling, > N triggers: split indicated",
105, SPLIT_TRIGGER_THRESHOLD + 1, "a.md 100\n", "split it by episode", "trim"),
("a raise on a file with > N triggers fails: the remedy is a split",
105, SPLIT_TRIGGER_THRESHOLD + 1, "a.md 105 more room\n", "not a raise", None),
("shrink beyond tolerance: the ceiling must be lowered",
96, 3, "a.md 100\n", "Lower its line", None),
("a dated line from an older version still parses, the date is ignored",
105, 3, "a.md 105 2026-01-31 one new episode section\n", None, None),
("a dated raise on a file with > N triggers is still a raise: the remedy is a split",
105, SPLIT_TRIGGER_THRESHOLD + 1, "a.md 105 2026-01-31 more room\n", "not a raise", None),
("a line that is not <file.md> <lines> is unreadable", 100, 3, "a.md more room\n",
"unreadable line", None),
("opted in, file without a declaration fails", 100, None, "a.md 100\n",
"declares no load triggers", None),
("opted in, file without a ceiling line fails", 100, 3, "# none yet\n",
"has no ceiling", None),
("over ceiling, > N triggers, split pending: trim or raise, never split",
105, SPLIT_TRIGGER_THRESHOLD + 1, "a.md 100\nsplit_pending: a.md split decided, lands next round\n",
"trim it back", "split it by episode"),
("over ceiling, > N triggers, split pending: the message states the count above N",
105, SPLIT_TRIGGER_THRESHOLD + 1, "a.md 100\nsplit_pending: a.md\n",
f"(> {SPLIT_TRIGGER_THRESHOLD}, split pending)", "(<= "),
("a raise on a file with > N triggers passes while its split is pending",
105, SPLIT_TRIGGER_THRESHOLD + 1,
"a.md 105 more room\nsplit_pending: a.md split decided, lands next round\n", None, None),
("a split_pending line that names no file is unreadable", 100, 3,
"a.md 100\nsplit_pending:\n", "unreadable line", None),
("a split_pending line with no reason is read", 105, SPLIT_TRIGGER_THRESHOLD + 1,
"a.md 105 more room\nsplit_pending: a.md\n", None, None),
("a split_pending line from an older version, dated, still reads", 105, SPLIT_TRIGGER_THRESHOLD + 1,
"a.md 105 more room\nsplit_pending: a.md 2026-01-31 split decided\n", None, None),
("a split_pending line for a file not in references/ fails", 100, 3,
"a.md 100\nsplit_pending: b.md\n", "marks a split pending for b.md", None),
("the marker behind `# ` is read the same way (an older validator reads a comment)",
105, SPLIT_TRIGGER_THRESHOLD + 1,
"a.md 105 more room\n# split_pending: a.md split decided, lands next round\n", None, None),
]
def crosscheck_case(core, triggers):
"""Run check_reference_shape over a one-reference fixture (a.md with
`triggers` declared and 12 sections) against `core`; return the printed
pointer cross-check note for a.md."""
with tempfile.TemporaryDirectory() as tmp:
refs = pathlib.Path(tmp) / "fixture-skill" / "references"
refs.mkdir(parents=True)
secs = [f"S{i}" for i in range(1, 13)]
text = ("# A\n\nLoad triggers: " + "; ".join(f"episode {i}" for i in range(triggers))
+ "\n\n## Contents\n\n" + "\n".join(f"- {s}" for s in secs) + "\n\n"
+ "\n\n".join(f"## {s}\n\ntext" for s in secs) + "\n")
(refs / "a.md").write_text(text, encoding="utf-8")
import contextlib
import io
buf = io.StringIO()
with contextlib.redirect_stdout(buf):
check_reference_shape(refs.parent, core, [])
return next((l for l in buf.getvalue().splitlines()
if l.startswith("note: pointer cross-check — a.md")), "")
def _core(sections_citing, names_per_section=1, lead=False):
"""A core whose first `sections_citing` sections each cite a.md, naming
`names_per_section` of its sections; `lead` puts one pointer before the
first `## ` heading instead of in a section."""
out = ["---", "name: x", 'description: "D."', "---", "# X", ""]
if lead:
out += ['See `references/a.md` ("S1").', ""]
sections_citing -= 1
for i in range(1, 7):
out += [f"## Section {i}", ""]
if i <= sections_citing:
out += [" ".join(f'load `references/a.md` ("S{j + 1}").' for j in range(names_per_section)), ""]
else:
out += ["plain text.", ""]
return "\n".join(out) + "\n"
# (name, core text, declared triggers, must be flagged UNDER-DECLARED)
CROSSCHECK_FIXTURES = [
("cited from four core sections, one trigger declared: under-declared", _core(4), 1, True),
("cited from one core section naming eleven sections, one trigger: the once-per-run shape passes",
_core(1, names_per_section=11), 1, False),
("cited from four sections, two declared: within the slack", _core(4), 2, False),
("cited from five sections, two declared: over the slack", _core(5), 2, True),
("the body before the first heading is one section", _core(3, lead=True), 1, False),
("a pointer before the first heading plus three sections is four", _core(4, lead=True), 1, True),
]
# (name, core text, {file: distinct citing sections})
POINTER_SECTION_FIXTURES = [
("two pointers in one section count once", "# X\n\n## A\n\nsee `references/a.md`; and `references/a.md` (\"S\").\n", {"a.md": 1}),
("pointers in two sections count twice", "# X\n\n## A\n\n`references/a.md`\n\n## B\n\n`references/a.md`\n", {"a.md": 2}),
("the lead before the first heading is a section of its own",
"# X\n\n`references/a.md`\n\n## A\n\n`references/a.md`\n", {"a.md": 2}),
("frontmatter is skipped", "---\nname: x\ndescription: \"see `references/a.md`\"\n---\n# X\n\n## A\n\ntext\n", {}),
]
# (name, core text, {file: section count}, {file: filename-only count})
POINTER_FIXTURES = [
("named form, wrapped heading", 'Load `references/a.md` ("One\n two") now.\n', {"a.md": 1}, {}),
("parenthesised form", 'done (`references/a.md`,\n "One") here.\n', {"a.md": 1}, {}),
("filename-only pointers count once per paragraph",
"See `references/a.md` and `references/a.md`.\n\nAlso `references/a.md`.\n", {}, {"a.md": 2}),
("a backtick between path and heading breaks the pairing",
'See `references/a.md` and `x` ("Not a target").\n', {}, {"a.md": 1}),
]
def selftest():
bad = total = 0
for name, lines, trig, sidecar, want, avoid in REF_SHAPE_FIXTURES:
fails = ref_shape_case(lines, trig, sidecar)
ok = (not fails) if want is None else any(want in f for f in fails)
if avoid is not None:
ok = ok and not any(avoid in f for f in fails)
bad += not ok; total += 1
print(f"{'ok ' if ok else 'FAIL'} reference ceiling: {name}"
+ ("" if ok else f" (failures {fails})"))
for name, staged, live, want, want_orphans in LIVE_SET_FIXTURES:
fails, orphans = live_set_case(staged, live)
ok = (not fails if want is None else any(want in f for f in fails)) and orphans == want_orphans
bad += not ok; total += 1
print(f"{'ok ' if ok else 'FAIL'} {name}" + ("" if ok else f" (failures {fails}, orphans {orphans})"))
for name, args, want_dir, want_opts in GATE_ARGS_FIXTURES:
got = parse_gate_args(args)
ok = isinstance(got, str) if want_dir is None else got == (want_dir, want_opts)
bad += not ok; total += 1
print(f"{'ok ' if ok else 'FAIL'} gate arguments: {name}" + ("" if ok else f" (got {got!r})"))
for name, core, want_named, want_unnamed in POINTER_FIXTURES:
named, unnamed = core_pointers(core)
ok = {f: len(s) for f, s in named.items()} == want_named and unnamed == want_unnamed
bad += not ok; total += 1
print(f"{'ok ' if ok else 'FAIL'} core pointer: {name}"
+ ("" if ok else f" (named {named}, filename-only {unnamed})"))
for name, core, want in POINTER_SECTION_FIXTURES:
got = core_pointer_sections(core)
ok = got == want
bad += not ok; total += 1
print(f"{'ok ' if ok else 'FAIL'} core pointer sections: {name}" + ("" if ok else f" (got {got})"))
for name, core, trig, want_flag in CROSSCHECK_FIXTURES:
note = crosscheck_case(core, trig)
ok = bool(note) and (("UNDER-DECLARED" in note) == want_flag)
bad += not ok; total += 1
print(f"{'ok ' if ok else 'FAIL'} pointer cross-check: {name}" + ("" if ok else f" (note {note!r})"))
for name, short, long, want in POINTER_HEADING_FIXTURES:
ok = heading_matches(short, long) == want
bad += not ok; total += 1
print(f"{'ok ' if ok else 'FAIL'} heading qualifier rule: {name}")
for name, text, want in QUALIFIER_INDEX_FIXTURES:
ok = index_misses(text) == want
bad += not ok; total += 1
print(f"{'ok ' if ok else 'FAIL'} reference index (qualifier rule): {name}"
+ ("" if ok else f" (got {index_misses(text)})"))
for name, text, must_fail in RESIDUE_FIXTURES:
failed = bool(residue_hits(pathlib.Path("fixture.md"), text))
ok = failed == must_fail
bad += not ok; total += 1
print(f"{'ok ' if ok else 'FAIL'} {name}")
for name, text, must_fail in SECOND_FM_FIXTURES:
ok = bool(SECOND_FRONTMATTER_RE.match(text)) == must_fail
bad += not ok; total += 1
print(f"{'ok ' if ok else 'FAIL'} second-frontmatter: {name}")
for value, kebab in FALLBACK_NAME_FIXTURES:
ok = bool(NAME_RE.match(fallback_name(f"name: {value}\n"))) == kebab
bad += not ok; total += 1
print(f"{'ok ' if ok else 'FAIL'} fallback name: {value!r}")
for name, ceiling, released, must_fail in RELEASED_CEILING_FIXTURES:
with tempfile.TemporaryDirectory() as td:
sk = pathlib.Path(td) / "x-y"; (sk / "references").mkdir(parents=True)
(sk / "SKILL.md").write_text(f"---\nname: x-y\ncore_max_lines: {ceiling}\n---\n" + "l\n" * (ceiling - 4), encoding="utf-8")
if released is not None:
(sk / "references" / REF_CEILINGS_FILE).write_text(f"# released core ceiling: {released} (v1.0.0)\n", encoding="utf-8")
fs = []
with _ctx.redirect_stdout(_io.StringIO()):
check_core_size(sk / "SKILL.md", fs)
got = any("released core ceiling" in x for x in fs)
ok = got == must_fail
bad += not ok; total += 1
print(f"{'ok ' if ok else 'FAIL'} released core ceiling: {name}" + ("" if ok else f" (fails {fs})"))
for name, fm, want, note in CORE_CEILING_FIXTURES:
got, notes = core_ceiling_case(fm)
ok = got == want and (note is None or (note in notes if note else notes == ""))
bad += not ok; total += 1
print(f"{'ok ' if ok else 'FAIL'} core ceiling key: {name}" + ("" if ok else f" (got {got}, notes {notes!r})"))
for name, text, fewer in CORE_COUNT_FIXTURES:
got = len(text.splitlines()) - installed_line_count(text)
ok = got == fewer
bad += not ok; total += 1
print(f"{'ok ' if ok else 'FAIL'} core count: {name}" + ("" if ok else f" (got {got} fewer)"))
try:
import yaml # noqa: F401
branches = (True, False)
except ImportError:
branches = (False,)
print("skip compare-frontmatter PyYAML branch: PyYAML not installed")
for use_yaml in branches:
for name, a, b, want_keys, want_body in COMPARE_FM_FIXTURES:
keys, body_equal, _ = compare_frontmatter_texts(a, b, use_yaml)
ok = keys == want_keys and body_equal == want_body
bad += not ok; total += 1
print(f"{'ok ' if ok else 'FAIL'} compare-frontmatter "
f"({'PyYAML' if use_yaml else 'fallback'}): {name}"
+ ("" if ok else f" (keys {keys}, body equal {body_equal})"))
for name, text, want in INDEX_FIXTURES:
ok = index_misses(text) == want
bad += not ok; total += 1
print(f"{'ok ' if ok else 'FAIL'} reference index: {name}")
for name, text, want in DEEP_INDEX_FIXTURES:
got = [h for h in index_misses(text, 4) if h not in index_misses(text)]
ok = got == want
bad += not ok; total += 1
print(f"{'ok ' if ok else 'FAIL'} reference index (#### note): {name}"
+ ("" if ok else f" (got {got})"))
for name, text, want in LOAD_TRIGGER_FIXTURES:
got = declared_load_triggers(text)
ok = got == want
bad += not ok; total += 1
print(f"{'ok ' if ok else 'FAIL'} load triggers line: {name}" + ("" if ok else f" (got {got})"))
for name, section, files, want in MANIFEST_FIXTURES:
got = manifest_misses(section, files)
ok = got == (want[0], want[1])
bad += not ok; total += 1
print(f"{'ok ' if ok else 'FAIL'} bundle manifest: {name}" + ("" if ok else f" (got {got})"))
for name, text, want in ORPHAN_FIXTURES:
got = index_orphans(text)
ok = got == want
bad += not ok; total += 1
print(f"{'ok ' if ok else 'FAIL'} reference index (reverse): {name}"
+ ("" if ok else f" (got {got})"))
for name, text, want in TEMPLATE_FIXTURES:
ok = template_tokens(text) == want
bad += not ok; total += 1
print(f"{'ok ' if ok else 'FAIL'} template token: {name}")
with tempfile.TemporaryDirectory() as td: # a token warns; it never fails the gate
sk = pathlib.Path(td) / "tok"
sk.mkdir()
(sk / "SKILL.md").write_text('---\nname: tok\ndescription: "D."\n---\nawk \'{print $1}\'\n',
encoding="utf-8")
import contextlib
import io
fails, buf = [], io.StringIO()
with contextlib.redirect_stdout(buf):
check_dir(sk, fails)
ok = not fails and "warn: SKILL.md:5: '$1'" in buf.getvalue()
bad += not ok; total += 1
print(f"{'ok ' if ok else 'FAIL'} template token: warns, does not fail the gate"
+ ("" if ok else f" (fails {fails})"))
for name, fm, want in VERSION_READ_FIXTURES:
ok = frontmatter_version(fm) == want
bad += not ok; total += 1
print(f"{'ok ' if ok else 'FAIL'} version read: {name}")
for name, extra, want_fail, want_warn in TOP_KEY_FIXTURES:
with tempfile.TemporaryDirectory() as td:
sk = pathlib.Path(td) / "tk"
sk.mkdir()
(sk / "SKILL.md").write_text('---\nname: tk\ndescription: "D."\n' + extra + "---\nbody\n",
encoding="utf-8")
import contextlib
import io
fails, buf = [], io.StringIO()
with contextlib.redirect_stdout(buf):
check_dir(sk, fails)
keyed = [x for x in fails if "top-level key" in x]
warned = [x for x in buf.getvalue().splitlines() if "top-level key" in x]
ok = ((len(keyed) == 1 and want_fail in keyed[0] and "under `metadata:`" in keyed[0]) if want_fail else not keyed) and \
((len(warned) == 1 and warned[0].startswith(want_warn) and "`metadata.version`" in warned[0])
if want_warn else not warned)
bad += not ok; total += 1
print(f"{'ok ' if ok else 'FAIL'} frontmatter keys: {name}"
+ ("" if ok else f" (fails {fails}, warnings {warned})"))
for name, text, want in COMMAND_PATH_FIXTURES:
ok = command_paths(text) == want
bad += not ok; total += 1
print(f"{'ok ' if ok else 'FAIL'} command path: {name}")
for name, body, want, *staged in CITED_PATH_FIXTURES:
with tempfile.TemporaryDirectory() as td:
sk = pathlib.Path(td) / "cp"
sk.mkdir()
(sk / "SKILL.md").write_text('---\nname: cp\ndescription: "D."\n---\n' + body,
encoding="utf-8")
for entry in (staged[0] if staged else []):
rel, content = entry if isinstance(entry, tuple) else (entry, "x\n")
(sk / rel).parent.mkdir(parents=True, exist_ok=True)
(sk / rel).write_text(content, encoding="utf-8")
import contextlib
import io
fails = []
with contextlib.redirect_stdout(io.StringIO()):
check_dir(sk, fails)
cited = [f for f in fails if f.startswith("cited path ")]
ok = (not fails) if want is None else (len(cited) == 1 and want in cited[0])
bad += not ok; total += 1
print(f"{'ok ' if ok else 'FAIL'} cited path: {name}"
+ ("" if ok else f" (fails {fails})"))
for name, after_pack, must_fail in ROUNDTRIP_FIXTURES:
ok = roundtrip_case(after_pack) == must_fail
bad += not ok; total += 1
print(f"{'ok ' if ok else 'FAIL'} round-trip: {name}")
import shutil
import subprocess
if not shutil.which("bash"):
print("skip scan script: no bash on PATH")
elif not SCAN_SCRIPT.is_file():
bad += 1; total += 1
print(f"FAIL scan script: {SCAN_SCRIPT.name} missing beside this file")
else:
ok = subprocess.run(["bash", "-n", str(SCAN_SCRIPT)]).returncode == 0
bad += not ok; total += 1
print(f"{'ok ' if ok else 'FAIL'} scan script: bash -n passes")
for name, scenario, pass_root, want_rc, want_out, want_ck, absent, *extra in SCAN_FIXTURES:
rc, out, ck, _ = scan_case(scenario, pass_root, extra[0] if extra else None)
ok = rc == want_rc and want_out in out and ck == want_ck and not (absent and absent in out)
bad += not ok; total += 1
print(f"{'ok ' if ok else 'FAIL'} scan script: {name}"
+ ("" if ok else f" (exit {rc}, {ck} checkpoint lines)"))
for name, scenario, prefix in SCAN_REPEAT_FIXTURES:
ok, detail = scan_repeat_ok(scenario, prefix)
bad += not ok; total += 1
print(f"{'ok ' if ok else 'FAIL'} scan script: {name}" + ("" if ok else f" ({detail})"))
for name, fn in (("--entries-to splits the entries off stdout and the end line names the file", scan_entries_ok),
("one line per entry, parked last; the full headers go to last-scan-headers.txt", scan_compact_ok),
("--entries-to onto a non-empty file is refused, nothing written", scan_entries_refused_ok),
("an argument after the root is refused by name, nothing written", scan_trailing_ok),
("--entries-to leaving its file empty beside files: N > 0 is a broken run, exit 3", scan_entries_empty_ok),
("the end line names VERSION, equal to the skill's metadata.version", scan_version_ok),
("a root with no observation log under it is refused by name, nothing written", scan_wrong_root_ok),
("a root named skill-observations/ holding the log scans its parent, with a NOTE", scan_child_root_ok),
("the scan's commands off PATH: SCAN TOOLS MISSING, no checkpoint line", scan_tools_missing_ok),
("forty populated entries print under 30,000 characters", scan_size_ok),
("the end line names the bytes above it; a halted run still prints", scan_bytes_ok),
("an actioned entry lacking a skill: member's disposition is named", scan_disp_ok),
("the entries print before the sibling-log search's listing", scan_order_ok),
("a stalled sibling-log search is cut at its time limit with a NOTE; the scan completes", scan_stall_ok),
("a root whose parent is HOME: the home folder searched 4 levels, Library pruned, said on the line",
scan_home_parent_ok),
("two spellings of one directory are one log in the sibling listing, the root in its pinned spelling",
scan_spellings_ok)):
ok, detail = fn()
bad += not ok; total += 1
print(f"{'ok ' if ok else 'FAIL'} scan script: {name}" + ("" if ok else f" ({detail})"))
for name, scenario, want in SCAN_ANCHOR_FIXTURES:
ok, detail = scan_anchor_ok(scenario, want)
bad += not ok; total += 1
print(f"{'ok ' if ok else 'FAIL'} scan script: {name}" + ("" if ok else f" ({detail})"))
rc, _, _, side = scan_case("broken", True) # the halted run leaves its guard line, not an older finding
ok = rc == 1 and side is not None and side.startswith("SCAN COMMAND BROKEN")
bad += not ok; total += 1
print(f"{'ok ' if ok else 'FAIL'} scan script: a halted run writes its guard line to the sidecar"
+ ("" if ok else f" (sidecar {side!r})"))
for eol in ("\n", "\r\n"): # the name-quoting rewrite keeps the file's line endings
with tempfile.TemporaryDirectory() as td:
p = pathlib.Path(td) / "SKILL.md"
p.write_bytes(eol.join(["---", "name: x-y", "description: d", "---", "body", ""]).encode())
quoted = quote_frontmatter_name(p)
out = p.read_bytes()
ok = quoted and b'name: "x-y"' in out and \
(out.count(b"\r\n") == 5 if eol == "\r\n" else b"\r" not in out)
bad += not ok; total += 1
print(f"{'ok ' if ok else 'FAIL'} name quoting keeps {'CRLF' if eol == chr(13) + chr(10) else 'LF'} endings")
if shutil.which("bash") and LOAD_SCRIPT.is_file():
ok = subprocess.run(["bash", "-n", str(LOAD_SCRIPT)]).returncode == 0
bad += not ok; total += 1
print(f"{'ok ' if ok else 'FAIL'} skill-load script: bash -n passes")
for name, skill, absolute, want_rc, want_out, want_ck, *scenario in LOAD_FIXTURES:
rc, out, ck = load_case(skill, absolute, *scenario)
ok = rc == want_rc and want_out in out and ck == want_ck
bad += not ok; total += 1
print(f"{'ok ' if ok else 'FAIL'} skill-load script: {name}"
+ ("" if ok else f" (exit {rc}, {ck} checkpoint lines, out {out!r})"))
ok, detail = load_query_ok()
bad += not ok; total += 1
print(f"{'ok ' if ok else 'FAIL'} skill-load script: --query-only prints the same lookup and appends nothing"
+ ("" if ok else f" ({detail})"))
ok, detail = tools_missing_ok(LOAD_SCRIPT, False)
bad += not ok; total += 1
print(f"{'ok ' if ok else 'FAIL'} skill-load script: commands off PATH, LOOKUP TOOLS MISSING, nothing written"
+ ("" if ok else f" ({detail})"))
for name, first, reason, want_rc, want_lines in LOAD_CORRECT_FIXTURES:
rc, out, lines = load_correct_case(first, reason)
ok = rc == want_rc and lines == want_lines and (rc != 0 or out == "")
bad += not ok; total += 1
print(f"{'ok ' if ok else 'FAIL'} skill-load script: {name}"
+ ("" if ok else f" (exit {rc}, lines {lines!r}, out {out!r})"))
elif shutil.which("bash"):
bad += 1; total += 1
print(f"FAIL skill-load script: {LOAD_SCRIPT.name} missing beside this file")
if shutil.which("bash") and DIFFSTAGED_SCRIPT.is_file():
ok = subprocess.run(["bash", "-n", str(DIFFSTAGED_SCRIPT)]).returncode == 0
bad += not ok; total += 1
print(f"{'ok ' if ok else 'FAIL'} diff-staged script: bash -n passes")
for name, scenario, want_rc, want in DIFFSTAGED_FIXTURES:
rc, out = diffstaged_case(scenario)
ok = rc == want_rc and out.startswith(want) and out.count("\n") == 1
bad += not ok; total += 1
print(f"{'ok ' if ok else 'FAIL'} diff-staged script: {name}"
+ ("" if ok else f" (exit {rc}, out {out!r})"))
for name, works, want_rc, want, want_err, lacks in DIFFSTAGED_NOPY_FIXTURES:
rc, out, err = diffstaged_nopy_case(works is True, meta=(works == "meta"))
ok = (rc == want_rc and out.startswith(want) and out.count("\n") == 1
and want_err in err and lacks not in out + err)
bad += not ok; total += 1
print(f"{'ok ' if ok else 'FAIL'} diff-staged script: {name}"
+ ("" if ok else f" (exit {rc}, out {out!r}, err {err.strip()!r})"))
elif shutil.which("bash"):
bad += 1; total += 1
print(f"FAIL diff-staged script: {DIFFSTAGED_SCRIPT.name} missing beside this file")
if shutil.which("bash") and NEWOBS_SCRIPT.is_file():
import datetime
ok = subprocess.run(["bash", "-n", str(NEWOBS_SCRIPT)]).returncode == 0
bad += not ok; total += 1
print(f"{'ok ' if ok else 'FAIL'} new-observation script: bash -n passes")
today = datetime.date.today().isoformat()
for name, scenario, slug, body, want_rc, want_out, want_err, want_files, want_floor in NEWOBS_FIXTURES:
rc, out, err, files, floor, text = newobs_case(scenario, slug, body)
ok = (rc == want_rc and want_out in out and want_err in err
and files == want_files and floor == want_floor)
if ok and want_rc == 0 and body is None: # the skeleton: id on disk, status open, title empty,
ok = f"id: {int(pathlib.Path(out.strip()).name[:4])}\n" in text and "status: open\n" in text and 'title: ""\n' in text
# and every field of the core template, in its order
ok = ok and [l.split(":")[0] for l in text.splitlines()[1:-1]] == SKELETON_FIELDS
if ok and want_rc == 0 and body is not None: # the copy: placeholders filled, the span verbatim
ok = ("id: 1\n" in text and f"date: {today}\n" in text and "`$(date)`" in text
and f"on {today} as #1\n" in text and "__ID__" not in text)
bad += not ok; total += 1
print(f"{'ok ' if ok else 'FAIL'} new-observation script: {name}"
+ ("" if ok else f" (exit {rc}, files {files}, floor {floor!r}, err {err.strip()!r})"))
ok, detail = tools_missing_ok(NEWOBS_SCRIPT, True)
bad += not ok; total += 1
print(f"{'ok ' if ok else 'FAIL'} new-observation script: commands off PATH, TOOLS MISSING, no file"
+ ("" if ok else f" ({detail})"))
ok, detail = disp_shared_ok()
bad += not ok; total += 1
print(f"{'ok ' if ok else 'FAIL'} set-fields script: the dispositions program is the scan's, byte for byte"
+ ("" if ok else f" ({detail})"))
ok, detail = sus_shared_ok()
bad += not ok; total += 1
print(f"{'ok ' if ok else 'FAIL'} new-observation script: the suspect-YAML rules are the scan's and set-fields', byte for byte"
+ ("" if ok else f" ({detail})"))
elif shutil.which("bash"):
bad += 1; total += 1
print(f"FAIL new-observation script: {NEWOBS_SCRIPT.name} missing beside this file")
if shutil.which("bash") and SETFIELDS_SCRIPT.is_file():
ok = subprocess.run(["bash", "-n", str(SETFIELDS_SCRIPT)]).returncode == 0
bad += not ok; total += 1
print(f"{'ok ' if ok else 'FAIL'} set-fields script: bash -n passes")
for name, scenario, plan, check, want_rc, want_out, want_diff in SETFIELDS_FIXTURES:
ok, detail = setfields_ok(scenario, plan, check, want_rc, want_out, want_diff)
bad += not ok; total += 1
print(f"{'ok ' if ok else 'FAIL'} set-fields script: {name}" + ("" if ok else f" ({detail})"))
elif shutil.which("bash"):
bad += 1; total += 1
print(f"FAIL set-fields script: {SETFIELDS_SCRIPT.name} missing beside this file")
if shutil.which("bash") and EXTOBS_SCRIPT.is_file():
ok = subprocess.run(["bash", "-n", str(EXTOBS_SCRIPT)]).returncode == 0
bad += not ok; total += 1
print(f"{'ok ' if ok else 'FAIL'} extend-observation script: bash -n passes")
for name, scenario, opts, ident, want_rc, want_err, check in EXTOBS_FIXTURES:
rc, out, err, before, after = extobs_case(scenario, opts, ident)
ok = rc == want_rc and want_err in err and check(before, after, out)
bad += not ok; total += 1
print(f"{'ok ' if ok else 'FAIL'} extend-observation script: {name}"
+ ("" if ok else f" (exit {rc}, err {err.strip()!r}, files {sorted(after)})"))
elif shutil.which("bash"):
bad += 1; total += 1
print(f"FAIL extend-observation script: {EXTOBS_SCRIPT.name} missing beside this file")
if shutil.which("bash") and STAGEPATCH_SCRIPT.is_file():
ok = subprocess.run(["bash", "-n", str(STAGEPATCH_SCRIPT)]).returncode == 0
bad += not ok; total += 1
print(f"{'ok ' if ok else 'FAIL'} stage-patch script: bash -n passes")
for name, live, changed, allow, suffix, want_rc, want_out, written in STAGEPATCH_FIXTURES:
rc, out, patch = stagepatch_case(live, changed, allow, suffix)
ok = rc == want_rc and out.startswith(want_out) and out.count("\n") == 1
if written is None:
ok = ok and patch == "earlier\n"
else:
ok = ok and (patch is not None) == written and (not written or patch.startswith("--- "))
if suffix != ".md":
ok = ok and "not a Markdown file" in out
if "live line 3" not in out and want_rc == 1 and want_out.startswith("HEADING"):
ok = False
bad += not ok; total += 1
print(f"{'ok ' if ok else 'FAIL'} stage-patch script: {name}"
+ ("" if ok else f" (exit {rc}, out {out!r})"))
elif shutil.which("bash"):
bad += 1; total += 1
print(f"FAIL stage-patch script: {STAGEPATCH_SCRIPT.name} missing beside this file")
if shutil.which("bash") and BINCHECK_SCRIPT.is_file():
ok = subprocess.run(["bash", "-n", str(BINCHECK_SCRIPT)]).returncode == 0
bad += not ok; total += 1
print(f"{'ok ' if ok else 'FAIL'} bin-check script: bash -n passes")
for name, scenario, want_rc, want_out, want_err in BINCHECK_FIXTURES:
rc, out, err = bincheck_case(scenario)
ok = rc == want_rc and want_out in out and want_err in err and (want_out or not out.strip())
bad += not ok; total += 1
print(f"{'ok ' if ok else 'FAIL'} bin-check script: {name}"
+ ("" if ok else f" (exit {rc}, out {out!r}, err {err.strip()!r})"))
for name, works, want_rc, want_out, want_err in BINCHECK_PY_FIXTURES:
rc, out, err = bincheck_py_case(works)
ok = rc == want_rc and want_out in out and want_err in err and (want_out or not out.strip())
bad += not ok; total += 1
print(f"{'ok ' if ok else 'FAIL'} bin-check script: {name}"
+ ("" if ok else f" (exit {rc}, out {out!r}, err {err.strip()!r})"))
elif shutil.which("bash"):
bad += 1; total += 1
print(f"FAIL bin-check script: {BINCHECK_SCRIPT.name} missing beside this file")
if MIGRATE_SCRIPT.is_file():
for name, skill_line, ov, want_rc, has, lacks in MIGRATE_FIXTURES:
rc, text = migrate_case(skill_line, ov)
ok = rc == want_rc and (text is None if want_rc else text is not None) \
and (has is None or has in (text or "")) and (lacks is None or lacks not in (text or ""))
bad += not ok; total += 1
print(f"{'ok ' if ok else 'FAIL'} migrate-log: {name}" + ("" if ok else f" (exit {rc})"))
ok, detail = migrate_count_ok()
bad += not ok; total += 1
print(f"{'ok ' if ok else 'FAIL'} migrate-log: the conformance count equals the written files (one siblings_checked empty)"
+ ("" if ok else f" ({detail})"))
else:
bad += 1; total += 1
print(f"FAIL migrate-log: {MIGRATE_SCRIPT.name} missing beside this file")
print(f"selftest: {total - bad}/{total} passed")
return 1 if bad else 0
def check_repo_versions(repo_dir, fails):
"""Every manifest in the repo carries the same version as the skill's own.
`.claude-plugin/plugin.json` is canonical — it is the one the installer
reads, and it is the one that ships inside the skill bundle. Every other
site is a copy, and a copy that drifts is worse than no copy: the
installer's update check is keyed on the version, so a manifest left at
the old number means `/plugin update` reports "already at the latest
version" while serving stale files.
Deliberately NOT a site: `marketplace.json` has no `version` field. The
plugin's own manifest wins where both are set, so leaving it out removes
a copy rather than synchronising one.
plugin.json also carries a `description` (and `keywords`) written for
discovery, mirrored in the marketplace entry, because that entry is what a
browser sees before install. It is deliberately not the SKILL.md
description: that one is the invocation trigger, read by the loader.
"""
import json
repo_dir = pathlib.Path(repo_dir)
canonical_path = repo_dir / ".claude-plugin" / "plugin.json"
if not canonical_path.is_file():
fails.append("repo: .claude-plugin/plugin.json missing (the canonical version site)")
return
try:
canonical = str(json.loads(canonical_path.read_text(encoding="utf-8")).get("version", "")).strip()
except Exception as e:
fails.append(f"repo: .claude-plugin/plugin.json does not parse: {e}")
return
if not SEMVER_RE.match(canonical):
fails.append(f"repo: canonical version is not semver: {canonical!r}")
return
name = str(json.loads(canonical_path.read_text(encoding="utf-8")).get("name") or "").strip()
if not NAME_RE.match(name):
fails.append(f"repo: .claude-plugin/plugin.json `name` not kebab-case: {name!r}")
desc = str(json.loads(canonical_path.read_text(encoding="utf-8")).get("description") or "").strip()
if not desc:
fails.append(
"repo: .claude-plugin/plugin.json has no `description`. Add one written for "
"discovery: `/plugin` search, the pre-install listing and plugin directories "
"read it. It is not compared with the SKILL.md description, which is the "
"invocation trigger and has a different reader; re-read both at every release.")
print(f"repo: canonical version {canonical}")
# The skill's own frontmatter carries the version too, so a session can
# name what it loaded without the repo-only manifest (which never ships
# inside a bundle). It is a copy of the canonical number like the others.
skill_md = repo_dir / "SKILL.md"
if not skill_md.is_file(): # a repo that keeps the skill under skills/<name>/
found = sorted((repo_dir / "skills").glob("*/SKILL.md")) if (repo_dir / "skills").is_dir() else []
if found:
skill_md = found[0]
if skill_md.is_file():
fm = frontmatter(skill_md.read_text(encoding="utf-8")) or ""
fv = frontmatter_version(fm)
if fv is None:
fails.append("repo: SKILL.md frontmatter has no `metadata.version` (or top-level `version:`); it must equal the canonical version")
elif fv != canonical:
fails.append(f"repo: SKILL.md frontmatter version {fv!r} != canonical {canonical!r}")
mp = repo_dir / ".claude-plugin" / "marketplace.json"
if mp.is_file():
try:
data = json.loads(mp.read_text(encoding="utf-8"))
except Exception as e:
fails.append(f"repo: .claude-plugin/marketplace.json does not parse: {e}")
data = {}
stray = [k for k in ("version",) if k in data]
stray += [f"plugins[{i}].version" for i, e in enumerate(data.get("plugins", []))
if isinstance(e, dict) and "version" in e]
if stray:
fails.append(
f"repo: marketplace.json carries a version ({', '.join(stray)}). "
f"Remove it — plugin.json wins where both are set, so this is a "
f"copy to keep in sync for no benefit.")
# A marketplace entry with a non-relative source is all a browser sees
# before install, so it mirrors plugin.json's description and keywords.
pj = json.loads(canonical_path.read_text(encoding="utf-8"))
for i, e in enumerate(data.get("plugins", [])):
if not isinstance(e, dict) or e.get("name") != pj.get("name"):
continue
if str(e.get("description") or "").strip() != desc:
fails.append(f"repo: marketplace.json plugins[{i}].description differs from plugin.json's")
if e.get("keywords", []) != pj.get("keywords", []):
fails.append(f"repo: marketplace.json plugins[{i}].keywords differ from plugin.json's")
LIST_ITEM_RE = re.compile(r"^(\s*)([-*+]|\d+[.)])\s+\S")
def check_markdown_shape(repo_dir, fails):
"""A stray blank line inside a tight list splits it in two when rendered.
The skill checks never read repo-root prose, the confidentiality scan is
a term search, and a diff review reads added lines — so an entry inserted
into a README list by string replacement, which pushed the list's closing
blank into the middle of it, passed all three and was caught by a human
reading line numbers.
The predicate: a blank line whose previous and next non-empty lines are
list items at the same indent and of the same kind (bullet or numbered),
where the list is otherwise TIGHT — one of those two items sits directly
against another item with no blank between. Measured on seven repo roots
before the tightness clause: 9 hits, 0 defects, all one deliberately
loose list (every item blank-separated); with it: 0 hits, and the
fixture's known defect still reported. Fenced blocks become opaque
separator lines so code never reads as a list, and a run of blanks
reports once, at its first line.
"""
def kind(m):
return (m.group(1), m.group(2)[0].isdigit()) if m else None
repo_dir = pathlib.Path(repo_dir)
for p in sorted(repo_dir.glob("*.md")):
body = p.read_text(encoding="utf-8", errors="replace")
prose = blank_fenced_code(body, fill=lambda h: re.sub(r"[^\n]+", "~", h))
lines = prose.splitlines()
items = [kind(LIST_ITEM_RE.match(l)) for l in lines]
for i, line in enumerate(lines):
if line.strip() or (i and not lines[i - 1].strip()):
continue
prev = next((j for j in range(i - 1, -1, -1) if lines[j].strip()), None)
nxt = next((j for j in range(i + 1, len(lines)) if lines[j].strip()), None)
if prev is None or nxt is None or not items[prev] or items[prev] != items[nxt]:
continue
tight = (prev > 0 and items[prev - 1] == items[prev]) or \
(nxt + 1 < len(lines) and items[nxt + 1] == items[nxt])
if tight:
fails.append(f"{p.name}:{i + 1}: blank line splits a list in two "
f"(same-kind items at the same indent on both sides)")
def quote_frontmatter_name(skill_md):
"""Rewrite an unquoted frontmatter `name: x` to `name: "x"`, in place.
Provenance: the skill installer writes `name:` back quoted on some installs
and unquoted on others, with no visible pattern, but has never been seen
REMOVING quotes that were present. Emitting the quoted form here therefore
makes most installed copies byte-identical to the staged one, and every
installed-vs-staged comparison (the reconciliation gate, keep-two) stops
reporting a one-line diff that reviewers learn to wave through. Those
comparisons still normalise the line as the backstop. Runs only on the
pack path, after every check passed, so the value is known kebab-case.
"""
raw = skill_md.read_bytes().decode("utf-8")
crlf = "\r\n" in raw
text = raw.replace("\r\n", "\n")
m = re.match(r"^---\n(.*?)\n---\n", text, re.S)
if not m:
return False
nm = re.search(r"(?m)^name:[ \t]*([^\s\"'][^\n]*?)[ \t]*$", m.group(1))
if not nm or not NAME_RE.match(nm.group(1)):
return False # already quoted, absent, or carrying a comment: leave it
start = m.start(1) + nm.start()
end = m.start(1) + nm.end()
old = text[start:end]
new = f'name: "{nm.group(1)}"'
out = text[:start] + new + text[end:]
skill_md.write_bytes((out.replace("\n", "\r\n") if crlf else out).encode("utf-8"))
print(f"pack: quoted the frontmatter name in {skill_md} ({old!r} -> {new!r}); "
f"the packed copy carries the quoted form")
return True
def is_build_junk(path, root):
rel = path.relative_to(root)
return (any(part in BUILD_JUNK or part in VCS_DIRS or part.startswith(".~lock")
for part in rel.parts)
or path.suffix == ".pyc")
def packable_files(src):
"""The files a bundle carries: every regular file but build artefacts.
pack() and verify_roundtrip() share this, so they cannot disagree about
what a member is."""
return sorted(p for p in src.rglob("*") if p.is_file() and not is_build_junk(p, src))
def member_name(src, f):
return f"{src.name}/{f.relative_to(src).as_posix()}"
def pack(src, out):
"""Always writes POSIX separators, on any platform.
Returns {member: bytes} — what the packer meant to write — so the caller
can verify the bundle against it. The source is resolved first: the
member prefix is the directory's name, and Path('.').name is ''.
"""
src = pathlib.Path(src).resolve()
written = {}
with zipfile.ZipFile(out, "w", zipfile.ZIP_DEFLATED) as z:
for f in packable_files(src):
arc = member_name(src, f)
assert "\\" not in arc, arc
data = f.read_bytes()
z.writestr(zipfile.ZipInfo.from_file(f, arcname=arc), data,
compress_type=zipfile.ZIP_DEFLATED)
written[arc] = data
return written
def verify_roundtrip(bundle, src, written, fails):
"""The bundle is the deliverable; the directory is what the next review
diffs. An edit to the directory after packing leaves the two different,
the user installs the bundle, and a later comparison of the directory
against live reads the missing content as "not installed". So: the
members must be exactly the directory's packable files, each equal byte
for byte to what pack() wrote (`written`; None skips that half) and to
the file on disk now. Returns True when the round trip holds."""
src = pathlib.Path(src).resolve()
with zipfile.ZipFile(bundle) as z:
names = z.namelist()
members = {n: z.read(n) for n in names}
expected = {member_name(src, f): f for f in packable_files(src)}
problems = []
if len(names) != len(members):
problems.append(f"{len(names) - len(members)} duplicate member name(s)")
problems += [f"missing from the bundle: {a}" for a in sorted(set(expected) - set(members))]
problems += [f"in the bundle, not in the directory: {a}" for a in sorted(set(members) - set(expected))]
for arc in sorted(set(expected) & set(members)):
if written is not None and members[arc] != written.get(arc):
problems.append(f"member differs from what the packer wrote: {arc}")
elif members[arc] != expected[arc].read_bytes():
problems.append(f"directory file differs from the packed member: {arc}")
for p in problems:
fails.append(f"bundle round-trip: {p} — the bundle does not carry the staged "
f"directory; finish every edit, then re-pack (packing is the last write)")
return not problems
def check_bundle(path, fails):
"""Central directory as raw bytes: a convenience reader (zipfile.namelist)
rewrites 0x5C to '/' and would report a malformed archive as clean."""
data, i, n_members = pathlib.Path(path).read_bytes(), 0, 0
while True:
i = data.find(b"PK\x01\x02", i)
if i < 0:
break
n, m, k = (struct.unpack_from("<H", data, i + o)[0] for o in (28, 30, 32))
name = data[i + 46:i + 46 + n]
n_members += 1
if b"\x5c" in name:
fails.append(f"bundle: backslash in member path {name!r} (installer rejects it)")
if re.search(rb"(^|/)\.(git|hg|svn)(/|$)", name):
fails.append(f"bundle: contains version-control metadata "
f"({name.decode(errors='replace')})")
# The uploader rejects a skill bundle carrying a plugin manifest. The
# release workflow happens to copy three paths by name rather than the
# whole tree, so it never picked this up — an accident, not a design.
# Assert it here so the property holds however the bundle is built.
if b".claude-plugin/" in name:
fails.append(
f"bundle: contains a plugin manifest ({name.decode(errors='replace')}) — "
f"the uploader rejects a skill bundle that carries one")
i += 46 + n + m + k
if n_members == 0:
fails.append("bundle: no members found")
GATE_VALUE_OPTS = ("--live", "--bundle", "--pack", "--repo")
def parse_gate_args(args):
"""The gate run's arguments, in any order: each value option takes the
next argument and the one argument left over is the skill directory.
Returns (skill_dir, {option: value}), or a usage error as a string, so a
misplaced option is refused rather than read as the directory."""
opts, pos, i = {}, [], 0
while i < len(args):
a = args[i]
if a in GATE_VALUE_OPTS:
if i + 1 >= len(args) or args[i + 1].startswith("--"):
return f"{a} needs a value"
opts[a] = args[i + 1]; i += 2
continue
if a.startswith("--"):
return f"unknown option {a}"
pos.append(a); i += 1
if len(pos) != 1:
return f"expected one skill directory, got {len(pos)}: {pos}"
return pos[0], opts
# parse_gate_args: (name, arguments, skill dir or None for a usage error,
# options expected).
GATE_ARGS_FIXTURES = [
("--live after the directory", ["sk", "--live", "lv"], "sk", {"--live": "lv"}),
("--live before the directory", ["--live", "lv", "sk"], "sk", {"--live": "lv"}),
("options on both sides of the directory", ["--live", "lv", "sk", "--pack", "o.skill"], "sk",
{"--live": "lv", "--pack": "o.skill"}),
("--live without its value is a usage error", ["sk", "--live"], None, None),
("an unknown option is a usage error", ["sk", "--lvie", "lv"], None, None),
("two directories are a usage error", ["sk", "lv"], None, None),
]
def main(argv):
# A console or pipe whose code page cannot encode a character this script
# prints (U+2014 under cp949 or cp932) would raise UnicodeEncodeError and
# exit 1 with no verdict, the code a failed gate uses. Replace instead.
for stream in (sys.stdout, sys.stderr):
if hasattr(stream, "reconfigure"):
try:
stream.reconfigure(errors="replace")
except (ValueError, AttributeError):
pass
if len(argv) < 2:
print(__doc__); return 2
if argv[1] in ("--help", "-h"):
print(__doc__); return 0
if argv[1] == "--selftest":
return selftest()
if argv[1] == "--compare-frontmatter":
if len(argv) != 4:
print("usage: --compare-frontmatter <SKILL.md A> <SKILL.md B>"); return 2
return compare_frontmatter_main(argv[2], argv[3])
if "--repo-only" in argv:
fails = []
repo = argv[argv.index("--repo-only") + 1]
check_repo_versions(repo, fails)
check_markdown_shape(repo, fails)
if fails:
print("FAIL:")
for f in fails:
print(" -", f)
return 1
print("OK: repo manifest checks passed")
return 0
parsed = parse_gate_args(argv[1:])
if isinstance(parsed, str):
print(f"usage error: {parsed}\n"); print(__doc__); return 2
skill_dir, opts = parsed
bundle, pack_to = opts.get("--bundle"), opts.get("--pack")
repo, live = opts.get("--repo"), opts.get("--live")
fails = []
check_dir(skill_dir, fails)
if live:
check_live_set(skill_dir, live, fails)
if repo:
check_repo_versions(repo, fails)
if pack_to and not fails:
quote_frontmatter_name(pathlib.Path(skill_dir).resolve() / "SKILL.md")
written = pack(skill_dir, pack_to); bundle = pack_to
print(f"packed {pack_to}")
if verify_roundtrip(pack_to, skill_dir, written, fails):
print(f"pack: round trip OK — {len(written)} members equal the staged "
f"directory byte for byte")
if bundle:
check_bundle(bundle, fails)
if fails:
print("FAIL:")
for f in fails:
print(" -", f)
return 1
print("OK: all gate checks passed")
return 0
if __name__ == "__main__":
sys.exit(main(sys.argv))
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 |