@appchy/jarvis 0.1.36 → 0.1.39

package/harness/harness/config.py

@@ -0,0 +1,1482 @@
+"""One canonical config — shipped defaults merged under the repo's committed
+`.claude/work.config.json`.
+
+**A committed file is the only path, not the preferred one.** Claude Code has
+*deliberately* ignored `pluginConfigs` in a project's `.claude/settings.json` since
+v2.1.207, because a cloned repo could otherwise inject values into hook commands
+and MCP configs. That closes the option that would have been nicer and makes this
+schema a security surface in its own right: a value here that reaches a shell
+command is the same injection wearing different clothes.
+
+So `verify.*` — the only values the harness ever suggests running — are validated
+as plain command strings and are never interpolated into a shell by this module.
+They are printed for a human or a session to run, never executed here.
+
+`apply()` is the seam that makes the config real. Everything downstream reads a
+module attribute rather than re-reading the file, and `apply()` is what sets those
+attributes — once, before anything parses.
+"""
+import json
+import os
+import re
+from pathlib import Path
+
+from .tree import PAYLOAD_DIR, cli
+
+#: What a repo gets with no config file at all. A fresh install must WORK, so every
+#: default is a usable answer rather than a placeholder: no graph engine, the
+#: shipped ledger prefix, the nine domains in reading order.
+DEFAULTS = {
+    "ids": {
+        # The prefix this repo's durable rules carry — `D`, `G`, `ADR`, whatever.
+        "prefix": "D",
+        # Extra prefixes recognised on READ but never generated. A migration window
+        # stays readable without the lint going silent.
+        "recognised": [],
+        # Sibling repos whose ledger ids may legally appear here. Empty by default:
+        # a fresh repo has no siblings, and shipping somebody else's repo names as
+        # a default would silently excuse a real dangling citation in every
+        # consumer.
+        "foreign": [],
+        # Read `D12` as well as `D-12`. Off by default: a short prefix collides
+        # with ordinary data — `priority: P0` was read as a citation to `P-0`.
+        "undashed": False,
+    },
+    "domains": {
+        # Reading order of the org-domain map, not alphabetical: what it does → how
+        # it's built → how it looks → how we know it's good → what keeps it safe →
+        # how we run it → how users get unblocked → how we reach and earn → what
+        # binds us. A domain not on the list still scans; it just sorts last.
+        "order": ["product", "architecture", "design", "quality", "security",
+                  "operations", "support", "commercial", "legal"],
+    },
+    "spine": {
+        # The conventions a plan must fit, read before planning. Repo-relative.
+        "standards": None,
+        "conventions": [],
+    },
+    "plans": {
+        # Where an approved plan file lives, if this repo keeps them. `jarvis work plan`
+        # records a POINTER into it, never the body.
+        #
+        # Null by default, and null is a full mode rather than a missing setting:
+        # one consumer keeps `work/plans/` as an archival snapshot, another deleted
+        # the directory outright on the grounds that a design reachable from a side
+        # directory is a second home for it. Neither is more general than the other,
+        # so the harness ships neither — null means `plan` requires an explicit
+        # `--file`, and a repo that wants the default names its own directory.
+        # (Founder call, 2026-08-02.)
+        "dir": None,
+    },
+    "product": {
+        # `flat` — a feature is `product/<feature>.md` and its bare name is its whole
+        # address. The only shape the harness implements today; the key exists so a
+        # repo that grows an app tier has somewhere to say so rather than forking.
+        "tiers": "flat",
+    },
+    # How this repo's guidance is composed. The harness ships an ENGINE (the tree,
+    # the ids, the buckets, the delivery gate — what the harness actually enforces)
+    # and, separately, a PRESET: one organisation's methodology written on top of it.
+    #
+    # The split exists because they are different KINDS of fact. Contradict the
+    # engine and the tool refuses you; contradict the preset and you have simply
+    # chosen to work differently, which is not an error. Shipping them fused made
+    # every consumer inherit one org's opinions as though they were mechanics —
+    # the same defect as the tag vocabulary above, one layer up.
+    #
+    # This is the shareable-config pattern (eslint's engine vs `eslint-config-*`):
+    # the engine never enumerates its consumers, and whoever holds an opinion
+    # publishes it themselves.
+    "instructions": {
+        # A shipped preset by name, a repo-relative path to your own
+        # (`.claude/presets/ours.md`), or None for the bare engine.
+        #
+        # NONE BY DEFAULT. It shipped naming this author's own preset, which meant
+        # a repo that installed the harness and said nothing inherited one
+        # organisation's methodology as though it came with the mechanics. Naming
+        # it out loud in every session's first line made that honest but did not
+        # make it chosen. A preset is somebody's opinion, and whose opinion runs in
+        # a repo is that repo's call — so the engine ships and the methodology is
+        # one key away. (Founder call, 2026-08-21, applying the same rule as
+        # `session.tool` and `hygiene.*`: where nothing is defined and there is no
+        # honest default, do nothing rather than guess.)
+        "preset": None,
+        # Repo-relative files layered ON TOP, in order. Later wins on conflict:
+        # engine < preset < extend[0] < extend[1] … Layering rather than named
+        # section overrides, so the harness owes no stable slug API to anybody —
+        # rename a section here and no consumer breaks.
+        "extend": [],
+        # What a session runs to LOAD this repo's method — the line every kickoff
+        # prompt opens with, because a handed-over prompt that does not load the
+        # harness gets a session working without it.
+        #
+        # NONE BY DEFAULT, and the default is the whole reason this is config. It
+        # used to be derived from the payload's own location: the harness lived
+        # inside a Claude Code plugin, so it could read that plugin's manifest and
+        # answer `/<plugin>:<skill>`. The payload ships inside the CLI now and can
+        # see no manifest, and a guess here is worse than silence — a prompt naming
+        # a command that resolves for nobody is the one line whose entire job is
+        # loading the harness. A repo that has a method names how to load it;
+        # every other consumer gets a prompt with no such line.
+        "skill": None,
+    },
+    # Area tags a task's `tags:` field may carry, for grouping the board by
+    # capability or market. EMPTY BY DEFAULT, and empty means "no vocabulary
+    # configured" — any tag is accepted.
+    #
+    # It is config rather than a shipped tuple because an area vocabulary is the
+    # most repo-specific thing a task carries: one consumer groups by engine and
+    # game, another by service. The tuple that used to live in `tree.py` shipped
+    # one consumer's product names to every other repo AND refused their own, which
+    # is a default doing real damage rather than merely being wrong.
+    #
+    # A repo that wants typos caught names its list; then the vocabulary is closed
+    # and an unknown tag is refused against it. Compare `code:`, whose vocabulary is
+    # DERIVED from the systems in `work/architecture/*.md` — a fact that can be
+    # derived is never written, and this one cannot be.
+    "tags": {
+        "allowed": [],
+    },
+    "research": {
+        # The subagent that runs external research for this repo — a Codex agent, a
+        # Claude one, or anything else the session can address. None means none is
+        # configured.
+        #
+        # It lives HERE rather than in the skill because which model researches is
+        # a repo's own preference, and a vendor named in shared guidance ships that
+        # preference to every repo that loads the plugin — the same reason `verify`
+        # names no test command. What does NOT vary is the procedure and its output
+        # contract: verbatim `sources/`, raw findings, a take filed under the
+        # researcher's own name, and Claude's synthesis on top.
+        #
+        # A Claude agent is a legal value, with one trade stated openly in the
+        # procedure: it is not an independent read, so its take and Claude's
+        # synthesis agree with each other for free.
+        #
+        # None is fully supported. The session picks a researcher, follows the same
+        # contract, and SAYS which one it used, so no finding is ever traceable to
+        # an unnamed reader.
+        "agent": None,
+    },
+    # Commands run to verify work — by `jarvis work verify`, and by the completion gate
+    # that will not let a task finish without a passing record. Free-form because
+    # toolchains differ.
+    #
+    # These now reach EXECUTION, which is why `_validate` below is stricter than it
+    # looks: the value is split with `shlex` and run with `shell=False`, never
+    # interpolated. A repo may run anything it likes; what it may not do is get a
+    # `;` to mean `;`.
+    "verify": {},
+    "autonomy": {
+        # The highest `tier:` an unattended run acts on ALONE. Default 2 — a
+        # scheduled shift does ordinary work and stops at the irreversible.
+        #
+        # 3 means "decide everything, including money, secrets, personal data and
+        # the law". That is a repo's call to make explicitly, and never a shipped
+        # default: a harness that ships with no ceiling is a harness whose safety
+        # depends on nobody having configured it.
+        "ceiling": 2,
+        # How long an instance's claim on a task is good for. Long enough that real
+        # work finishes inside it; short enough that a crashed shift's task is
+        # takeable the same day.
+        "lease_minutes": 240,
+    },
+    "graph": {
+        # The MCP server serving this repo's governance↔code graph, or null. Null is
+        # a fully supported mode: the planning loop degrades to grep-wide and SAYS
+        # SO. It never implies a complete map it did not get.
+        "mcp": None,
+    },
+    # Starting the NEXT session — the wrap's last act, where a repo has something
+    # that can start one.
+    #
+    # A SEPARATE key from `graph.mcp` even where the same server answers both, and
+    # that is the point: serving a graph and starting a session are different
+    # capabilities, and a repo can have either without the other. Riding on the
+    # graph's key would mean a repo that installed a map silently gained the power
+    # to spawn sessions.
+    "session": {
+        # The MCP server whose `start` tool opens a session in this repo, or null.
+        # Null is the default and a supported mode: the wrap prints the kickoff
+        # prompt for a person to carry across, which is what it always did.
+        "mcp": None,
+        # The tool on that server. NO DEFAULT, and that is the point: the harness
+        # ships no knowledge of any particular server, and a default here would be
+        # one vendor's tool name compiled into a repo-agnostic payload — shipped
+        # to every consumer as though it were a fact about how sessions start.
+        # Naming a server therefore obliges you to name its tool; the alternative
+        # is the harness guessing, and a wrong guess is a tool call that resolves
+        # to nothing in the last minute of somebody's session.
+        "tool": None,
+    },
+    # The hook points this plugin OWNS, and what a repo may do to each.
+    #
+    # The declaration in `hooks/hooks.json` is the plugin's and a consumer cannot
+    # change it — nor should it have to. What a consumer needs is to change what is
+    # SAID at those points, which is this: name commands, the harness runs them,
+    # and their lines are folded into its own message.
+    #
+    # Extend, replace and off are ONE mechanic. `enabled: false` silences the
+    # harness's own lines and `extend` adds the repo's, so together they replace,
+    # `extend` alone adds, and `enabled: false` alone switches the point off. A
+    # third `replace:` key would be another spelling of the same two facts.
+    #
+    # Keyed by Claude Code's OWN event names rather than by what the harness happens
+    # to do at each one. An installer wiring "the SessionStart hook" then writes the
+    # key it already has a name for, and renaming the harness's behaviour later
+    # breaks nobody's config.
+    "hooks": {
+        # The standing obligations a fresh session is given.
+        "session_start": {"enabled": True, "extend": []},
+        # The end-of-turn wrap reminder. Note this is the HOOK; `wrap.at_percent`
+        # is when it fires, and the two are separate because a repo can want the
+        # threshold and not the harness's wording, or the reverse.
+        "stop": {"enabled": True, "extend": []},
+        # What arrives when a session is about to write a file: the judgements no
+        # gate can catch, and which part of the code it has just walked into. A rule
+        # read at the top of a session is a rule forgotten by the time it bites.
+        "pre_tool_use": {"enabled": True, "extend": []},
+    },
+    # Whether a board write lands in git, and what it carries when it does.
+    #
+    # OFF BY DEFAULT, for the same reason the wrap hook is: this harness is shared,
+    # and a consumer that never asked for it must not suddenly start committing on
+    # its own. A repo that wants the guarantee — that a work item cannot exist
+    # outside git, which is a failure that has already cost real work — says so
+    # here, and everything below switches on together.
+    "git": {
+        # Commit every board write, the moment it happens. No debounce and no
+        # window: the window is the bug. With this on, the commit trailers ARE the
+        # activity record and no `.events.jsonl` is written.
+        "commit": False,
+        # …and pull before, push after. Needs `commit`, because a push with nothing
+        # committed has nothing to send. Off separately so a repo with no shared
+        # origin still gets the half that makes a write unloseable.
+        "push": False,
+        "remote": "origin",
+        # What a board write commits. Everything under `work/` by default; a repo
+        # that keeps its tree elsewhere, or wants a narrower slice, names its own.
+        # Paths are repo-relative and reach a subprocess argv, so `_validate`
+        # refuses anything that could point outside the repo.
+        "paths": ["work"],
+    },
+    "coverage": {
+        # Where runners drop their shards. Gitignored on purpose — evidence is a
+        # fresh run, not a file somebody checked in.
+        "shard": ".work/coverage",
+    },
+    # The passes a session runs at a checkpoint and before completing — a bug pass
+    # and a quality pass, named by the repo.
+    #
+    # BOTH NULL, and null means the step does not happen. The shipped defaults used
+    # to name two commands, which was wrong twice over: nothing in the harness read
+    # the keys, so a repo that set its own was silently ignored, while the prose
+    # named those two commands to every consumer regardless of what it had. A
+    # default that no code reads is not a default, it is a claim — and a harness
+    # that tells a session to run a command the repo never named is guessing about
+    # somebody else's toolchain, which is the same mistake `verify.*` exists to
+    # avoid.
+    "hygiene": {
+        "review": None,
+        "simplify": None,
+    },
+    # When to finish a session cleanly, before the context window runs out.
+    #
+    # OFF by default, and that is deliberate rather than timid. The `Stop` hook that
+    # implements this speaks up at the end of a turn, and a hook that interrupts
+    # somebody's session is theirs to switch on — the same reasoning that keeps
+    # `hooks/guard.py` inert and unregistered. A repo that wants it names a
+    # percentage; every other consumer sees no change at all.
+    "wrap": {
+        # Share of the context window past which the session is reminded to wrap up:
+        # write the handoff, bring the task and epic docs current, move statuses, and
+        # leave the next session a kickoff prompt. Null is off.
+        "at_percent": None,
+        # The window that percentage is measured against. NO DEFAULT: a hook cannot
+        # ask Claude Code how large the context is, so any number here is a guess
+        # about somebody else's session — and the guess is what breaks it. 200000
+        # nagged a long-context consumer from its first turn; 1000000, which
+        # replaced it, would let a standard 200k session reach 100% having been
+        # told it was at 20%. Both are silent, and both make the reminder useless
+        # in exactly the repos that asked for it. So `at_percent` requires this,
+        # and a repo states the window it actually runs. Usage itself is never
+        # estimated — it is read from the API's own `usage` record.
+        "context_tokens": None,
+        # What to run to wrap up, named in the reminder. Null and the reminder says
+        # to wrap without naming a command — same reasoning as `instructions.skill`:
+        # the harness no longer sits inside the thing that owns slash commands, so
+        # it cannot derive one, and naming a command a repo does not have sends the
+        # reader somewhere that does not exist.
+        "command": None,
+    },
+    # Extra generated/vendored directories to skip, beyond the built-in rule (any
+    # dot-directory except `.claude`, plus the standard build dirs).
+    "skip_dirs": [],
+}
+
+CONFIG_PATH = Path(".claude") / "work.config.json"
+
+
+def payload_root() -> Path:
+    """The shipped payload — this file's own directory tree, and nothing else.
+
+    It used to consult `CLAUDE_PLUGIN_ROOT` first, because the payload was a Claude
+    Code plugin and an installed one lives in a version-hash directory. It ships
+    inside the CLI now, so the modules and the assets travel together and the
+    location is a fact about this file rather than about how it was reached.
+    """
+    return PAYLOAD_DIR
+
+
+def preset_dir() -> Path:
+    """Where shipped presets live."""
+    return payload_root() / "presets"
+
+
+def resolve_instructions(cfg: dict, repo: Path) -> dict:
+    """What this repo's guidance actually is, resolved to files on disk.
+
+    Returns `{"preset": (label, path|None), "extend": [(label, path|None), …]}` —
+    a path of None means the file is MISSING, reported rather than skipped. A
+    preset that silently fails to load is the worst outcome available: the session
+    proceeds on the bare engine, behaves unlike every other session in the repo,
+    and nothing anywhere says why.
+    """
+    out = {"preset": None, "extend": []}
+    name = cfg["instructions"]["preset"]
+    if name:
+        if "/" in name or name.endswith(".md"):
+            # A repo-relative path — the repo's own preset, versioned with the repo.
+            out["preset"] = (name, _existing(Path(repo) / name))
+        else:
+            # A shipped preset, by name.
+            out["preset"] = (name, _existing(preset_dir() / name / "PRESET.md"))
+    for rel in cfg["instructions"]["extend"]:
+        out["extend"].append((rel, _existing(Path(repo) / rel)))
+    return out
+
+
+def _existing(p: Path):
+    return p if p.is_file() else None
+
+
+class ConfigError(Exception):
+    """A config that cannot be trusted. Raised rather than warned: a silently
+    half-applied config is worse than none, because every downstream check then
+    reports against a model the repo did not choose."""
+
+
+#: Config sections whose KEYS are the repo's to invent — a command name under
+#: `verify` is data, not schema. Everything else is closed, so a typo raises
+#: instead of silently doing nothing.
+_OPEN_MAPS = {"verify"}
+
+
+def _merge(base: dict, over: dict, path: str = "") -> dict:
+    """Two levels deep, which is the whole schema. A dict merges key-by-key; any
+    other value REPLACES. A list is a value — a repo setting `domains.order` means
+    that order, not that order appended to the default."""
+    if path in _OPEN_MAPS:
+        return dict(over)
+    out = dict(base)
+    for k, v in over.items():
+        where = f"{path}.{k}" if path else k
+        if k not in base:
+            raise ConfigError(f"unknown config key '{where}'")
+        if isinstance(base[k], dict) and isinstance(v, dict):
+            out[k] = _merge(base[k], v, where)
+        elif isinstance(base[k], dict) != isinstance(v, dict):
+            raise ConfigError(f"config key '{where}' expects "
+                              f"{'an object' if isinstance(base[k], dict) else 'a value'}")
+        else:
+            out[k] = v
+    return out
+
+
+def _validate(cfg: dict) -> None:
+    ids = cfg["ids"]
+    if not isinstance(ids["prefix"], str) or not ids["prefix"].strip():
+        raise ConfigError("ids.prefix must be a non-empty string, e.g. \"D\"")
+    if not ids["prefix"].strip("-").isalnum():
+        raise ConfigError(f"ids.prefix {ids['prefix']!r} must be alphanumeric — it is "
+                          f"compiled into a regex, so punctuation would change what "
+                          f"counts as an id")
+    for key in ("recognised", "foreign"):
+        if not isinstance(ids[key], list) or any(not isinstance(x, str) for x in ids[key]):
+            raise ConfigError(f"ids.{key} must be a list of strings")
+    if not isinstance(cfg["domains"]["order"], list):
+        raise ConfigError("domains.order must be a list of domain names")
+    # Checked because the failure it prevents is INVISIBLE. `session_pointers` joins
+    # these into one line, so a list where a string belongs raises inside the
+    # SessionStart hook — and that hook exits 0 on every failure path by design, so
+    # the repo simply stops receiving its standing obligations and nothing says so.
+    # One consumer ran that way with `standards: ["STANDARDS.md"]` while `doctor`
+    # reported the config valid.
+    standards = cfg["spine"]["standards"]
+    if standards is not None and not isinstance(standards, str):
+        raise ConfigError(f"spine.standards must be a single path or null, not "
+                          f"{type(standards).__name__} — put additional documents in "
+                          f"spine.conventions, which is the list")
+    conventions = cfg["spine"]["conventions"]
+    if not isinstance(conventions, list) or any(not isinstance(c, str) for c in conventions):
+        raise ConfigError("spine.conventions must be a list of repo-relative paths")
+    plans_dir = cfg["plans"]["dir"]
+    if plans_dir is not None and (not isinstance(plans_dir, str) or not plans_dir.strip()):
+        raise ConfigError("plans.dir must be a repo-relative directory or null")
+    if cfg["product"]["tiers"] != "flat":
+        raise ConfigError(f"product.tiers {cfg['product']['tiers']!r} is not supported — "
+                          f"'flat' is the only shape the harness implements")
+    inst = cfg["instructions"]
+    preset = inst["preset"]
+    if preset is not None and (not isinstance(preset, str) or not preset.strip()):
+        raise ConfigError("instructions.preset must be a shipped preset name, a "
+                          "repo-relative path to one, or null for the bare engine")
+    if not isinstance(inst["extend"], list) or any(
+            not isinstance(x, str) or not x.strip() for x in inst["extend"]):
+        raise ConfigError("instructions.extend must be a list of repo-relative "
+                          "paths, layered in order (later wins)")
+    skill = inst["skill"]
+    if skill is not None and (not isinstance(skill, str) or not skill.strip()):
+        raise ConfigError("instructions.skill must be the command that loads this "
+                          "repo's method into a session, or null for a kickoff "
+                          "prompt that names none")
+    allowed = cfg["tags"]["allowed"]
+    if not isinstance(allowed, list) or any(not isinstance(t, str) or not t.strip()
+                                            for t in allowed):
+        raise ConfigError("tags.allowed must be a list of non-empty tag names, or [] "
+                          "to accept any tag")
+    agent = cfg["research"]["agent"]
+    if agent is not None and (not isinstance(agent, str) or not agent.strip()):
+        raise ConfigError("research.agent must be a subagent name or null")
+    for name, cmd in cfg["verify"].items():
+        if not isinstance(cmd, str):
+            raise ConfigError(f"verify.{name} must be a command string")
+        # These are EXECUTED now, so a value that only makes sense to a shell is a
+        # value that will not do what its author expects. Refusing at load is the
+        # honest moment to say so — the alternative is a gate that reports PASS
+        # because `&&` was passed to the first binary as an argument.
+        for meta in ("&&", "||", ";", "|", ">", "<", "$(", "`"):
+            if meta in cmd:
+                raise ConfigError(
+                    f"verify.{name} contains {meta!r} — verify commands are run "
+                    f"without a shell (shell=False), so shell operators would be "
+                    f"passed as literal arguments. Put the composition in a script "
+                    f"and call that.")
+    ceiling = cfg["autonomy"]["ceiling"]
+    if not isinstance(ceiling, int) or isinstance(ceiling, bool) or not 0 <= ceiling <= 3:
+        raise ConfigError("autonomy.ceiling must be an integer 0–3 (the highest "
+                          "task tier an unattended run may act on alone)")
+    lease = cfg["autonomy"]["lease_minutes"]
+    if not isinstance(lease, int) or isinstance(lease, bool) or lease < 1:
+        raise ConfigError("autonomy.lease_minutes must be a positive integer")
+    mcp = cfg["graph"]["mcp"]
+    if mcp is not None and not isinstance(mcp, str):
+        raise ConfigError("graph.mcp must be a server name or null")
+    starter = cfg["session"]["mcp"]
+    if starter is not None and (not isinstance(starter, str) or not starter.strip()):
+        raise ConfigError("session.mcp must be the name of an MCP server that can "
+                          "start a session in this repo, or null")
+    tool = cfg["session"]["tool"]
+    if starter and not tool:
+        raise ConfigError(
+            f"session.mcp names {starter!r} but session.tool is unset — naming a "
+            f"server does not name its tool, and the harness ships no default for "
+            f"it. Set both together: jarvis work config set session "
+            f"'{{\"mcp\": \"{starter}\", \"tool\": \"<the tool>\"}}' --json")
+    if tool is not None and (not isinstance(tool, str) or not tool.strip()):
+        raise ConfigError("session.tool must be the name of the tool that starts a "
+                          "session on session.mcp, or null — an empty string is "
+                          "neither a name nor an absence")
+    # Both halves reach the model as one `mcp__<server>__<tool>` name it is told to
+    # call. A server or tool name is an identifier, so anything that is not one is
+    # refused HERE — where it is one message — rather than becoming a tool call
+    # that fails in the last minute of somebody's session.
+    for key, value in (("mcp", starter), ("tool", tool)):
+        if value is not None and not re.fullmatch(r"[A-Za-z0-9_-]+", str(value)):
+            raise ConfigError(f"session.{key} must be a plain name "
+                              f"([A-Za-z0-9_-]), got {value!r} — it is composed "
+                              f"into the tool name `mcp__<server>__<tool>`")
+    for point, spec in cfg["hooks"].items():
+        if not isinstance(spec, dict) or set(spec) - {"enabled", "extend"}:
+            raise ConfigError(f"hooks.{point} takes `enabled` and `extend` only")
+        if not isinstance(spec.get("enabled", True), bool):
+            raise ConfigError(f"hooks.{point}.enabled must be true or false")
+        cmds = spec.get("extend", [])
+        if not isinstance(cmds, list):
+            raise ConfigError(f"hooks.{point}.extend must be a list of commands the "
+                              f"harness runs and folds into this hook's output")
+        for cmd in cmds:
+            if not isinstance(cmd, str) or not cmd.strip():
+                raise ConfigError(f"hooks.{point}.extend entries must be command "
+                                  f"strings")
+            # Executed, and from a hook — so the same rule `verify.*` lives under,
+            # for the same reason. A repo may run anything; what it may not do is
+            # get a `;` to mean `;`.
+            for meta in ("&&", "||", ";", "|", ">", "<", "$(", "`"):
+                if meta in cmd:
+                    raise ConfigError(
+                        f"hooks.{point}.extend entry contains {meta!r} — extensions "
+                        f"are run without a shell (shell=False), so shell operators "
+                        f"would be passed as literal arguments. Put the composition "
+                        f"in a script and name that.")
+    skip = cfg["skip_dirs"]
+    # A STRING here is the whole bug: `set("node_modules")` is a set of eleven
+    # letters, so every scan then skips any directory called `n`, `o`, `d`… The
+    # config loads clean, nothing warns, and `align`, `doctor` and the registry
+    # quietly stop seeing most of the tree.
+    if not isinstance(skip, list) or any(
+            not isinstance(d, str) or not d.strip() or "/" in d for d in skip):
+        raise ConfigError("skip_dirs must be a list of directory NAMES, e.g. "
+                          '["node_modules", "dist"] — not a string, and not a path')
+
+    g = cfg["git"]
+    for key in ("commit", "push"):
+        if not isinstance(g[key], bool):
+            raise ConfigError(f"git.{key} must be true or false")
+    if g["push"] and not g["commit"]:
+        raise ConfigError("git.push needs git.commit — a push with nothing committed "
+                          "has nothing to send")
+    if not isinstance(g["remote"], str) or not g["remote"].strip():
+        raise ConfigError("git.remote must be the name of a remote, e.g. \"origin\"")
+    paths = g["paths"]
+    if not isinstance(paths, list) or not paths or any(
+            not isinstance(p, str) or not p.strip() for p in paths):
+        raise ConfigError("git.paths must be a non-empty list of repo-relative paths "
+                          "whose changes a board write commits")
+    for p in paths:
+        # These become pathspecs on a `git commit`, so a path that escapes the repo
+        # would commit files nobody asked about. Refused at load, where it is one
+        # message, rather than at the commit, where it is a surprise in somebody's
+        # history.
+        if Path(p).is_absolute() or ".." in Path(p).parts:
+            raise ConfigError(f"git.paths entry {p!r} must be repo-relative and stay "
+                              f"inside the repo")
+    at = cfg["wrap"]["at_percent"]
+    # 100 is refused along with 0: a reminder that arrives once the window is
+    # already full has nowhere to write the handoff it is asking for.
+    if at is not None and (not isinstance(at, int) or isinstance(at, bool)
+                           or not 1 <= at <= 99):
+        raise ConfigError("wrap.at_percent must be an integer 1–99 (the share of the "
+                          "context window past which a session is reminded to wrap "
+                          "up), or null to switch the reminder off")
+    window = cfg["wrap"]["context_tokens"]
+    if at and window is None:
+        raise ConfigError("wrap.at_percent is set but wrap.context_tokens is not — "
+                          "a percentage needs the window it is a percentage OF, and "
+                          "the harness cannot ask Claude Code how large yours is. "
+                          "State the window you actually run: 200000 for a standard "
+                          "session, 1000000 for a long-context one.")
+    if window is not None and (not isinstance(window, int) or isinstance(window, bool)
+                               or window < 1):
+        raise ConfigError("wrap.context_tokens must be a positive integer — the "
+                          "window wrap.at_percent is measured against")
+    for key in ("review", "simplify"):
+        pass_cmd = cfg["hygiene"][key]
+        if pass_cmd is not None and (not isinstance(pass_cmd, str)
+                                     or not pass_cmd.strip()):
+            raise ConfigError(f"hygiene.{key} must be the command this repo runs for "
+                              f"that pass, or null to skip it")
+    wrap_cmd = cfg["wrap"]["command"]
+    if wrap_cmd is not None and (not isinstance(wrap_cmd, str) or not wrap_cmd.strip()):
+        raise ConfigError("wrap.command must be the command this repo runs to wrap a "
+                          "session up, or null to remind without naming one")
+
+
+def load(repo: Path) -> dict:
+    """The merged config for a repo. Missing file → the defaults, which is a
+    working configuration and not an error: a fresh install must run."""
+    p = Path(repo) / CONFIG_PATH
+    if not p.is_file():
+        return dict(DEFAULTS)
+    try:
+        raw = json.loads(p.read_text())
+    except json.JSONDecodeError as e:
+        raise ConfigError(f"{CONFIG_PATH} is not valid JSON: {e}") from None
+    if not isinstance(raw, dict):
+        raise ConfigError(f"{CONFIG_PATH} must contain a JSON object")
+    raw.pop("$schema", None)
+    cfg = _merge(DEFAULTS, raw)
+    _validate(cfg)
+    return cfg
+
+
+def apply(cfg: dict) -> None:
+    """Bind the config into the modules that read it.
+
+    Imported HERE rather than at module scope: `ids` must be reconfigured before
+    anything builds a pattern from it, and a top-level import would create a cycle
+    through `registry` → `ids`.
+    """
+    from . import (align, autonomy, coverage, gate, git, ids, kickoff, lint, registry,
+                   shift, task, tree)
+    ids.configure(cfg["ids"]["prefix"], tuple(cfg["ids"]["recognised"]),
+                  bool(cfg["ids"]["undashed"]))
+    git.GIT = dict(cfg["git"])
+    lint.GRAPH_MCP = cfg["graph"]["mcp"]
+    kickoff.GRAPH_MCP = cfg["graph"]["mcp"]
+    kickoff.SESSION_MCP = cfg["session"]["mcp"]
+    kickoff.SESSION_TOOL = cfg["session"]["tool"]
+    # The same list `session_pointers` prints as the hard pre-step, composed the
+    # same way — a plan is held against a repo's standards whether the session was
+    # started by a person or by the last one.
+    kickoff.SKILL = cfg["instructions"]["skill"]
+    kickoff.SPINE = [s for s in ([cfg["spine"]["standards"]] if cfg["spine"]["standards"]
+                                 else []) + list(cfg["spine"]["conventions"]) if s]
+    align.FOREIGN_REPOS = tuple(cfg["ids"]["foreign"])
+    registry.DOMAIN_ORDER = tuple(cfg["domains"]["order"])
+    # From the SHIPPED set each time, never from whatever the last `apply` left
+    # behind. Unioning into the live value made a second call in one process keep the
+    # first config's additions — so a repo's skip list leaked into the next repo's,
+    # and the ~20 tests that reset with `apply(DEFAULTS)` were resetting nothing.
+    tree.SKIP_DIRS = tree.SHIPPED_SKIP_DIRS | set(cfg["skip_dirs"])
+    tree.TASK_TAGS_OK = tuple(cfg["tags"]["allowed"])
+    coverage.VERIFY = dict(cfg["verify"])
+    gate.VERIFY = dict(cfg["verify"])
+    task.PLANS_DIR = cfg["plans"]["dir"]
+    autonomy.CEILING = cfg["autonomy"]["ceiling"]
+    shift.LEASE_MINUTES = cfg["autonomy"]["lease_minutes"]
+    # `shift` reads the ceiling it was imported with, so bind it there too — a
+    # module-level `from … import CEILING` captures the value, not the name.
+    shift.CEILING = cfg["autonomy"]["ceiling"]
+
+
+def resolve(repo: Path) -> dict:
+    """`load` + `apply` — the one call an entry point makes."""
+    cfg = load(repo)
+    apply(cfg)
+    return cfg
+
+
+#: A rule heading in somebody's standards file. The separator VARIES by repo and the
+#: id may carry a letter suffix — measured across five consuming repos on 2026-09-04:
+#: `## S-1. Function signatures`, `## S-1 · Function signatures`, `### S-2a. …`. A
+#: heading with no id is skipped rather than listed, because the id is the whole
+#: point: it is what a session cites and what `where` resolves.
+_STANDARD = re.compile(r"^#{2,4}\s+([A-Za-z]{1,3}-\d+[a-z]?)\s*[.·:]?\s+(.+?)\s*$",
+                       re.MULTILINE)
+
+
+def standards_index(cfg: dict, repo) -> list:
+    """`[(id, title)]` for the rules in THIS repo's own standards file.
+
+    Names only, never bodies. The full file is 74,000 bytes in this repo and 21,000
+    in the smallest consumer, and injecting it would cost ~18,000 tokens of every
+    session — which is not the fix for rules being skipped, it is the same problem
+    with a bigger wall in front of it. The names cost 61 to 229 tokens across the
+    five repos measured, and they buy the thing a bare pointer never did: a session
+    about to name a file has already been told a file-naming rule exists and what to
+    call it, so it can go and read that ONE rule.
+
+    Read from `spine.standards`, so what a session is told is the standards of the
+    repo it is standing in. A shipped harness has no business knowing what any
+    particular repo's rules are called.
+    """
+    name = cfg["spine"]["standards"]
+    if not name or repo is None:
+        return []
+    md = Path(repo) / name
+    try:
+        return _STANDARD.findall(md.read_text())
+    except OSError:
+        # A configured pointer to a file that is not there is worth saying out loud,
+        # and the caller says it — but never by failing the hook that says it.
+        return []
+#: Width a listed line wraps at. By WIDTH rather than by count, because rule titles
+#: vary from three words to fifteen and a fixed count produced lines four times
+#: longer than each other.
+_WRAP_AT = 96
+
+#: A rule whose title opens this way is HISTORY, and injecting it as a live decision
+#: is worse than omitting it — a session told `J-14` governs the thing it is about to
+#: build goes and honours a rule the repo retired.
+_PAST = re.compile(r"^\s*(RETIRED|SUPERSEDED|WITHDRAWN)\b", re.IGNORECASE)
+
+
+def _listing(head: str, items: list) -> str:
+    lines, row = [], ""
+    for item in items:
+        if row and len(row) + len(item) + 3 > _WRAP_AT:
+            lines.append(row)
+            row = ""
+        row = f"{row} · {item}" if row else item
+    if row:
+        lines.append(row)
+    return head + "\n" + "\n".join("      " + line for line in lines)
+
+
+def _method(cfg: dict, repo) -> list:
+    """The configured instruction layers, in full and in order.
+
+    Injected rather than pointed at. It was a Claude Code skill a session was told
+    to LOAD, which is an affordance one vendor's agent has and nobody else does —
+    and a session that skipped the line worked the board without the method at all.
+    A hook is the one surface a session cannot decline, so what has to be read
+    arrives there.
+
+    Order is engine < preset < extend[0] < extend[1] …, and later wins, so a repo
+    contradicting a shipped line is read as the answer rather than as a second
+    opinion. A layer that is MISSING is reported by the caller and skipped here —
+    never silently dropped, because a session behaving unlike every other session in
+    the repo with nothing saying why is the worst outcome available.
+    """
+    if repo is None:
+        return []
+    res = resolve_instructions(cfg, repo)
+    layered = ([res["preset"]] if res["preset"] else []) + list(res["extend"])
+    out = []
+    for label, path in layered:
+        if path is None:
+            continue
+        try:
+            body = _injectable(path)
+        except OSError:
+            continue
+        out.append(f"--- {label} — follow this; it is how work is done here ---\n"
+                   + body)
+    return out
+
+
+def _method_pointer(cfg: dict, repo) -> list:
+    """One line naming the method, in place of the method itself.
+
+    **The body used to be injected here and it was 86% of the block.** Measured in this
+    repo: 51,365 bytes at session start, of which the `appchy` preset was 44,368 —
+    ~11,000 tokens in front of every session, in every repo, whether or not that session
+    ever planned anything. The derived facts around it, which is what the injection call
+    was actually about, are ~670.
+
+    So the names, the ids and the obligations still arrive unasked; the prose is fetched.
+    The line has to read as an INSTRUCTION rather than a mention, because a session that
+    treats it as a footnote works without the method — which is the failure the
+    injection was chosen to prevent, and the reason the wording here is not decoration.
+    """
+    if repo is None:
+        return []
+    res = resolve_instructions(cfg, repo)
+    layered = ([res["preset"]] if res["preset"] else []) + list(res["extend"])
+    named = [label for label, path in layered if path is not None]
+    if not named:
+        return []
+    return [f"the method — how work is actually done here, and NOT optional: "
+            f"{' + '.join(f'`{n}`' for n in named)}. You have not read it. Get it with "
+            f"`{cli()} method` (or the `work_start` tool with `method: true`) BEFORE "
+            f"planning or editing anything."]
+
+
+#: A markdown link's target — the `x` of `[text](x)`.
+_LINK = re.compile(r"(?<=\]\()([^)\s]+)(?=\))")
+
+#: A leading YAML frontmatter block, and nothing else: it has to start the file.
+_FRONTMATTER = re.compile(r"\A---[ \t]*\r?\n.*?\r?\n---[ \t]*\r?\n", re.DOTALL)
+
+
+def _injectable(path) -> str:
+    """One instruction layer, as a session can actually ACT on it.
+
+    Two things a file cannot say about itself, both of which stop being harmless the
+    moment it is injected rather than opened.
+
+    Its frontmatter is metadata for whatever loads the file, and reads as an
+    instruction once it is pasted into a session — this preset announced itself as a
+    Claude Code skill, in the words "should be used when the user wants to", to
+    sessions that had already been handed it and could not have loaded it if they
+    tried.
+
+    And its links are relative to the file, which lives inside an installed package.
+    `references/graph.md` resolves to nothing from the repo a session is standing in,
+    so every document the method sends a reader to was one they could not open. Only
+    a target that actually EXISTS beside the layer is rewritten, so a link to
+    something in the reader's own repo is left to resolve there as it always did.
+
+    Done on the way through rather than to the file, so the layer stays a document
+    somebody can read, edit and diff on its own terms.
+    """
+    body = _FRONTMATTER.sub("", path.read_text(), count=1)
+
+    def beside(match):
+        target = path.parent / match.group(0)
+        return str(target.resolve()) if target.is_file() else match.group(0)
+
+    return _LINK.sub(beside, body).strip()
+def _what_this_repo_has_decided(cfg: dict, repo) -> list:
+    """The house rules, the durable decisions and what each release is for — by NAME.
+
+    All three are derived from the repo being stood in, never from anything the
+    harness ships. A shipped harness has no business knowing what any particular
+    repo's rules are called, and a line that names somebody else's rules is worse
+    than no line at all.
+    """
+    if repo is None:
+        return []
+    from . import ids, model, registry
+    root = Path(repo) / "work"
+    out = []
+
+    named = standards_index(cfg, repo)
+    if named:
+        out.append(_listing(
+            f"this repo's own standards — the id is how you cite one, and you READ "
+            f"the rule before writing code it governs ({cfg['spine']['standards']}):",
+            [f"{i} {t}" for i, t in named]))
+
+    if root.is_dir():
+        try:
+            rules = registry.hosted_rules(root)
+        except OSError:
+            rules = []
+        live = sorted(((i, ti) for _, i, ti in rules if not _PAST.match(ti)),
+                      key=lambda r: ids.sort_key(r[0]))
+        if live:
+            out.append(_listing(
+                f"decisions this repo has ALREADY taken — `{cli()} where <id>` opens "
+                f"one in full. Contradicting one is a thing you say out loud and get "
+                f"agreed, never a thing a plan does quietly:",
+                [f"{i} {ti}" for i, ti in live]))
+
+        try:
+            versions = model.scan(root)["versions"]
+        except (OSError, KeyError):
+            versions = []
+        cuts = [f"{v.name} ({v.status()}) — {v.outcome}" for v in versions if v.outcome]
+        if cuts:
+            # The releases, from `version.md`'s own `outcome:` rather than from
+            # ROADMAP.md — a ninth of the tokens, and it cannot go stale, because
+            # `version.md` OWNS what a cut delivers and the roadmap only orders them.
+            out.append("what the releases are for, so a plan does not win this week "
+                       "and cost the next one:\n      " + "\n      ".join(cuts))
+    return out
+#: What the block is, said once, above every line of it. It names no repo and makes
+#: no claim a config could contradict — which is what lets it be the same sentence
+#: wherever the block is served.
+HEADING = "work harness — standing obligations for this repo:"
+
+
+def session_pointers(cfg: dict, repo=None) -> list:
+    """The lines a `SessionStart` hook injects — **every one of them derived from
+    the config**, never authored prose about some particular repo.
+
+    A hook is the one surface a session cannot choose not to read, so what it says
+    has to be true in the repo it fires in. The shipped harness knows nothing about
+    which files hold a repo's standards, whether a graph engine is installed, or
+    what its verify commands are called — so the hook states what config says and
+    nothing more. Where a key is unset it says *that*, because "no standards
+    configured" is an actionable fact and an invented pointer is a lie the next
+    session acts on.
+    """
+    # Named through `cli()`, because this is the one message every session reads and
+    # a machine without the plugin has no `work` on its PATH at all — only the CLI
+    # the payload ships inside. Naming a command the reader cannot run, in the block
+    # that tells them how to work here, is the paper cut that costs every session.
+    out = [f"the board: tasks live under `work/` — `{cli()} list` shows what is "
+           f"moving, `{cli()} where <id>` resolves any rule id to its home."]
+
+    # The guidance stack, ANNOUNCED. What ships is an engine plus somebody's
+    # methodology, and a session that cannot tell which is which will cite the
+    # preset's reasoning as though the tool enforced it. Saying it also makes an
+    # override visible: a repo working differently is a choice somebody made, not a
+    # drift nobody noticed — this harness bans repo names from the payload for the
+    # same reason, and an unannounced preset is that fork wearing a config key.
+    if repo is not None:
+        res = resolve_instructions(cfg, repo)
+        layers, missing = [], []
+        if res["preset"]:
+            label, path = res["preset"]
+            layers.append(f"preset `{label}`")
+            if path is None:
+                missing.append(label)
+        for label, path in res["extend"]:
+            layers.append(f"`{label}`")
+            if path is None:
+                missing.append(label)
+        if layers:
+            # ANNOUNCED here, and FETCHED below. Which layers are in force is a fact
+            # a session cannot discover and costs a line; their bodies are ~11,000
+            # tokens and are asked for. The instruction to go and read them is the
+            # next line, worded as one — a session that reads it as a footnote works
+            # the board without the method, which is the whole risk of this shape.
+            out.append("guidance: engine + " + " + ".join(layers) +
+                       " — later layers win, and the engine alone is mechanics, "
+                       "not method.")
+        else:
+            # No layers is a real state and must read as one: the engine enforces
+            # the tree, and nobody has said how this repo works on top of it.
+            out.append(f"guidance: the bare engine — no method is configured for "
+                       f"this repo. Set `instructions.preset` in "
+                       f".claude/work.config.json, or work from `{cli()} --help` and "
+                       f"accept that the conventions here are undocumented.")
+        if missing:
+            out.append("instructions MISSING and therefore not applied: " +
+                       ", ".join(f"`{m}`" for m in missing) +
+                       " — say so rather than proceeding as if this repo had none.")
+
+    spine = [s for s in ([cfg["spine"]["standards"]] if cfg["spine"]["standards"] else [])
+             + list(cfg["spine"]["conventions"]) if s]
+    if spine:
+        out.append("read before planning (hard pre-step): " + " · ".join(spine))
+    else:
+        out.append("read before planning: no `spine.standards`/`spine.conventions` "
+                   "configured — set them in .claude/work.config.json so plans are "
+                   "held to this repo's conventions.")
+
+    # The NAMES of what this repo has already decided — its house rules, its durable
+    # decisions, and what each release is for. Names and ids only, never bodies: the
+    # standards file alone is ~18,000 tokens here, and a wall of text at the top of a
+    # session is how a rule gets skipped rather than how it gets read.
+    #
+    # What the names buy is the thing a bare pointer never did. A session about to
+    # name a file has already been told a file-naming rule exists and what it is
+    # called, so it can go and read that ONE rule; a session that was only told
+    # "read STANDARDS.md" does not know there is anything in there about naming.
+    out += _what_this_repo_has_decided(cfg, repo)
+    out += _method_pointer(cfg, repo)
+
+    mcp = cfg["graph"]["mcp"]
+    if mcp:
+        out.append(f"blast radius: map through the `{mcp}` graph before proposing a "
+                   f"non-trivial plan.")
+    else:
+        out.append("blast radius: no graph engine configured (`graph.mcp` is null) — "
+                   "the sweep is grep-wide, and the plan must SAY so rather than "
+                   "imply a complete map.")
+
+    # Named only where a repo named them. A session told to run a pass this repo
+    # never configured goes looking for a command that may not exist — and the
+    # harness has no business knowing which one it would be.
+    passes = [f"`{cfg['hygiene'][k]}`" for k in ("review", "simplify")
+              if cfg["hygiene"][k]]
+    if passes:
+        out.append("hygiene passes configured here: " + " and ".join(passes) +
+                   " — run them at a checkpoint and before completing.")
+
+    if cfg["verify"]:
+        # Names only. The commands themselves are printed by `coverage`, which is
+        # where a session goes to run them; repeating them here would be a second
+        # copy to drift, and this line only has to say what exists.
+        out.append("verify commands available: " + ", ".join(sorted(cfg["verify"])))
+
+    # Status is the bucket, so a task only says what is true if somebody MOVES it —
+    # and the move is the step a session skips, because the code already works and
+    # the board is not where the work feels like it lives. Saying it here costs one
+    # line and removes the sentence a founder otherwise types every session.
+    out.append(f"status is a move, not a note: `{cli()} move <task> in-progress` when "
+               f"you pick it up, `complete` when it lands. The bucket IS the status — "
+               f"nothing else records it.")
+
+    at = cfg["wrap"]["at_percent"]
+    if at:
+        # Phrased as "you will be TOLD" rather than "wrap up past N%", and the
+        # difference is the whole point. A session cannot measure its own context —
+        # it has no reading to compare against a threshold — so an instruction to act
+        # at N% asks for a judgement it can only guess at, and the guess runs early
+        # because a model that has been working a while feels full long before it is.
+        # Stating the number without the means to read it produced exactly that: a
+        # wrap-up at perhaps a quarter of the window, session after session. The hook
+        # holds the only real reading, so it holds the decision.
+        out.append(f"wrapping up: a hook measures the context and will TELL you when "
+                   f"to wrap up (at {at}%). Never judge the level yourself and never "
+                   f"wrap up early — you cannot see the reading, and the guess is "
+                   f"always high. Until it fires or the user asks, keep working"
+                   + (f"; then run `{cfg['wrap']['command']}`." if cfg["wrap"]["command"]
+                      else "."))
+    return out
+
+
+def cmd_context(cfg: dict, args=None, repo=None) -> int:
+    """Print the SessionStart block. Separate from `config` on purpose: `config` is
+    the machine view (one JSON object, the whole merged model) and this is the
+    human/session view (a handful of obligations). One is parsed, the other read.
+
+    `hooks.session_start` decides whose lines these are: the harness's, the repo's,
+    or both. The repo's come LAST — later layers win here exactly as they do in the
+    instruction stack, so an extension can contradict a shipped line and be read as
+    the answer rather than as a second opinion.
+
+    The heading is printed HERE and not by whoever runs this. Several doors serve
+    the same block now — a hook, a tool — and a sentence each of them types itself
+    is a sentence they can disagree about. Nothing left of a door but stdout.
+
+    Nothing at all when there is nothing to say: a repo that switched the block off
+    gets silence, not a heading over an empty list."""
+    from . import extend
+    spec = cfg["hooks"]["session_start"]
+    lines = session_pointers(cfg, repo) if spec.get("enabled", True) else []
+    lines += extend.run(spec.get("extend"), repo if repo is not None else Path.cwd())
+    if not lines:
+        return 0
+    print(HEADING)
+    for line in lines:
+        print(f"  {line}")
+    return 0
+
+
+def cmd_method(cfg: dict, args=None, repo=None) -> int:
+    """Print the configured instruction layers in full — the method, on request.
+
+    It is the same bytes `session_pointers` used to inject, from the same reader, so
+    there is one account of how work is done here and no way for a session to have read
+    a different one. What changed is only WHEN it arrives.
+    """
+    repo = Path(repo) if repo is not None else Path.cwd()
+    body = _method(cfg, repo)
+    if not body:
+        # Said rather than answered empty: a session that asked how work is done here
+        # and got silence concludes there is nothing to know, and proceeds.
+        print("no method is configured for this repo — set `instructions.preset` in "
+              ".claude/work.config.json, or work from `" + cli() + " --help` and accept "
+              "that the conventions here are undocumented.")
+        return 0
+    for layer in body:
+        print(layer)
+    return 0
+
+
+#: What the method wraps around the judgements that no gate can catch. A fence rather
+#: than a heading: a heading is prose somebody will reword, and the block would empty
+#: itself silently the day they did. A test asserts both markers are still there.
+APPLIES_FENCE = ("<!-- applies:begin -->", "<!-- applies:end -->")
+
+
+def _fenced(text: str) -> str:
+    """What sits between the fence markers, or nothing at all."""
+    start = text.find(APPLIES_FENCE[0])
+    if start < 0:
+        return ""
+    end = text.find(APPLIES_FENCE[1], start)
+    if end < 0:
+        return ""
+    return text[start + len(APPLIES_FENCE[0]):end].strip()
+
+
+def _judgement(cfg: dict, repo) -> str:
+    """The method's own fenced section — the rules a machine cannot check for you.
+
+    Read out of the SAME layers `method` serves, so there is one statement of these
+    and no way for a session to be handed a version of them the method contradicts.
+    Later layers win, exactly as they do everywhere else in the instruction stack: a
+    repo that fences its own block is answered with that one rather than with both.
+    """
+    found = ""
+    for layer in _method(cfg, repo):
+        block = _fenced(layer)
+        if block:
+            found = block
+    return found
+
+
+def _session_state(cfg: dict, repo) -> Path:
+    """Where per-machine, per-session markers live — beside the coverage shard, which
+    is already the gitignored root for facts that are about this checkout and not
+    about the repo. One reader, because the hook that replays these has the default
+    baked in and a second answer here would silently stop matching it."""
+    return repo / Path(cfg["coverage"]["shard"]).parent
+def _remember_systems(cfg: dict, repo, session, systems, off=False) -> None:
+    """Leave this repo's file-to-system declarations where the caller can replay them.
+
+    The hook that asks this question fires before EVERY tool call, and asking here
+    costs a Python start — measured at a quarter-second, which is not a price to pay
+    on every edit for an answer that is almost always "nothing". So the declarations
+    are written down once and the caller matches against them itself, spending a
+    process only when it finds something unclaimed.
+
+    Per session, so a run that starts after the declarations changed reads the new
+    ones. Best-effort: a caller that cannot find this file simply asks again, which
+    is slower and never wrong.
+    """
+    target = _session_state(cfg, repo) / "applies" / "map" / f"{session}.json"
+    try:
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_text(json.dumps({
+            "systems": [{"name": name, "paths": paths} for name, paths in systems],
+            # Said out loud rather than faked with a spent claim: a repo that switched
+            # this off must stop being asked, and it must not have to be lied to about
+            # having already been told in order to get there.
+            **({"off": True} if off else {}),
+        }))
+    except OSError:
+        pass
+
+
+def cmd_applies(cfg: dict, args=None, repo=None) -> int:
+    """What a session has to be told, now that it is about to write a particular file.
+
+    **The measurement is the caller's and the judgement is this command's**, the same
+    split the wrap reminder uses and for the same reason: which file and which session
+    is a thing only the client knows, while the once-rule, the wording and whatever the
+    repo adds are the same whoever is asking.
+
+    Two things, each claimed at most once. The METHOD's judgements, on the first write
+    of a session — the plan-first, ask-don't-settle, park-the-question rules that no
+    gate detects and that stopped arriving when the method stopped being injected. And
+    the AREA, the first time a session writes under one — which system's rules it has
+    just walked into, by the globs that system declares about itself.
+
+    Prints the block or nothing at all. Silent without a session, because a claim that
+    cannot be proven once is a claim that fires every turn and gets switched off; silent
+    for a file under no system, and for a repo whose systems declare no paths, because
+    naming the wrong rules is worse than naming none.
+    """
+    from . import extend, ids
+    from .registry import scan_systems, system_for_path, system_paths
+
+    args = args or {}
+    spec = cfg["hooks"]["pre_tool_use"]
+    session = args.get("session")
+    if not session:
+        return 0
+    repo = Path(repo) if repo is not None else Path.cwd()
+    root = repo / "work"
+
+    # Read once and handed to both questions below. Each helper can find the tree
+    # for itself, and letting them would re-parse every architecture doc twice per
+    # fire on the one path this whole design is trying to keep cheap.
+    on = spec.get("enabled", True)
+    systems = scan_systems(root) if (root / "architecture").is_dir() else []
+    # Written on EVERY run, including the run that finds nothing to say and the run
+    # that is switched off. The caller decides whether to ask by reading this file, so
+    # a repo that never produced one would be asked on every write forever — the exact
+    # cost it exists to avoid, in the repos least likely to notice it.
+    _remember_systems(cfg, repo, session, system_paths(root, systems), off=not on)
+
+    # An extension still runs with the shipped half off: off, extend and replace are
+    # one mechanic here as they are on every other hook, so a repo that switched the
+    # shipped wording off and supplied its own gets its own.
+    out = []
+    if on:
+        if _first_time(cfg, repo, session, "applies/method"):
+            body = _judgement(cfg, repo)
+            if body:
+                out.append(body)
+
+        system = (system_for_path(root, (args.get("file") or "").strip(), systems)
+                  if systems else None)
+        # History is filtered out by the same reader the session block uses. A session
+        # told a retired rule governs what it is about to build goes and honours it,
+        # which is worse than being told nothing at all.
+        live = sorted(
+            (i for i in (system.rules if system else {})
+             if not _PAST.match(system.titles.get(i, ""))),
+            key=ids.sort_key)
+        if live and _first_time(cfg, repo, session, f"applies/system/{system.name}"):
+            out.append(
+                f"You are editing `{system.name}` — {len(live)} rule(s) govern "
+                f"this part of the code: {', '.join(live)}. Read the one your change "
+                f"touches before you write it; a title is not the rule.")
+
+    out += extend.run(spec.get("extend"), repo)
+    if not out:
+        return 0
+    print("\n\n".join(out))
+    return 0
+
+
+def cmd_remind(cfg: dict, args=None, repo=None) -> int:
+    """Say whether a session this full should be wrapping up, and what that means here.
+
+    **It is handed a MEASUREMENT, never a transcript.** How many tokens a session is
+    holding is a thing only its client can answer, and every client answers it its own
+    way — so measuring is the client's half and it stays there. What is left is the
+    part that is the same for all of them: the threshold, the window, the wording, the
+    once-per-session rule, and whatever this repo adds. A harness command that took one
+    vendor's log file would be a harness that only works for that vendor.
+
+    Prints one JSON object, or nothing at all. A caller wraps `headline` and `note` in
+    whatever its own surface expects; nothing here knows what that looks like.
+
+    Silent on every path where it cannot be sure. A reminder that arrives at the wrong
+    moment is worse than one that never arrives — it teaches its reader to ignore the
+    next one, and there is only ever one that matters.
+    """
+    args = args or {}
+    at = cfg["wrap"]["at_percent"]
+    window = cfg["wrap"]["context_tokens"]
+    try:
+        used = int(args.get("used") or 0)
+    except (TypeError, ValueError):
+        used = 0
+    if not at or not window or used <= 0:
+        return 0
+    percent = used / window * 100
+    if percent < at:
+        return 0
+
+    repo = Path(repo) if repo is not None else Path.cwd()
+    if not _first_time(cfg, repo, args.get("session")):
+        return 0
+
+    from . import extend
+    from .tree import cli
+    spec = cfg["hooks"]["stop"]
+    extra = extend.run(spec.get("extend"), repo)
+    if not spec.get("enabled", True):
+        if not extra:
+            return 0
+        print(json.dumps({"headline": "\n".join(extra), "note": "\n".join(extra)}))
+        return 0
+
+    # Null when the repo names none, and then the reminder says to wrap without naming
+    # a command — better than sending the reader to one that resolves for nobody.
+    command = cfg["wrap"]["command"]
+    # What the last step IS depends on whether this repo has something that can start a
+    # session. Telling a repo with no starter to start one would be the harness
+    # inventing a capability; telling one that has a starter to leave a prompt for a
+    # person would be it withholding what was just wired up.
+    if cfg["session"]["mcp"]:
+        last = (f"`{cli()} kickoff <task>` and START the next session with it — the "
+                "prompt is derived, never hand-written, because a hand-written one "
+                "never invoked the method.")
+    else:
+        last = (f"`{cli()} kickoff <task>` — the prompt that opens the next session on "
+                "this work, with the method actually loaded.")
+    note = (
+        f"Context is {percent:.0f}% full ({used:,} of {window:,} tokens; the threshold "
+        f"is {at}%). Finish this session cleanly while there is still room to do it "
+        f"well:\n"
+        f"  1. `{cli()} handoff <task>` — status, next step, and what you learned.\n"
+        f"  2. Bring the task and epic docs to current — a stale brief is a trap for "
+        f"the next session.\n"
+        f"  3. Move anything finished: `{cli()} move <task> complete`.\n"
+        f"  4. Park anything still open: `{cli()} ask <task> --question \"…\"`.\n"
+        f"  5. {last}\n"
+        + (f"`{command}` runs all five. " if command else "")
+        + "Say so before you start, and if the user is mid-thought, finish their point "
+        "first — this is a reminder, not a stop."
+        + ("\n" + "\n".join(extra) if extra else "")
+    )
+    headline = (f"work: {percent:.0f}% of context used ({used // 1000}k/"
+                f"{window // 1000}k) — time to wrap up"
+                + (f" (`{command}`)." if command else "."))
+    print(json.dumps({"headline": headline, "note": note}))
+    return 0
+
+
+def _first_time(cfg: dict, repo, session, what="wrap-reminded") -> bool:
+    """Claim one of the things this session is told once, or say it is already spent.
+
+    Once, or it fires at the end of every remaining turn and becomes the thing people
+    switch off. The marker is per-machine, per-session state and lives under the
+    gitignored coverage root — never a repo fact.
+
+    `what` names WHICH once — the wrap reminder, the method, one system's rules — so
+    several things can each arrive once without any of them spending another's claim.
+
+    False when the claim cannot be PROVEN, not when it fails: unable to write the
+    marker means unable to promise this happens once, and a reminder repeated every
+    turn costs more than a reminder missed.
+    """
+    marker = _session_state(cfg, repo) / what / str(session or "unknown")
+    try:
+        marker.parent.mkdir(parents=True, exist_ok=True)
+        # Created exclusively, never checked-then-written. A turn issuing two tool
+        # calls at once runs two of these at once, and a look followed by a write
+        # lets both of them believe they were first — which is the one outcome the
+        # whole claim exists to prevent.
+        with open(marker, "x"):
+            pass
+        return True
+    except FileExistsError:
+        return False
+    except OSError:
+        return False
+
+
+def cmd_config(cfg: dict, args=None) -> int:
+    """Print the merged config as one JSON object — shipped defaults under the
+    repo's committed file. This is what the skill reads, so what it prints IS the
+    configuration; there is no second view of it to drift.
+
+    `set` and `unset` write it. They exist because this file has rules — which keys
+    exist, which sections are open, what a value may contain — and those rules
+    belong to whoever owns the format. Every installer that merges the JSON itself
+    carries a second copy of them, and a stale copy writes a config the loader then
+    refuses. One writer, and it validates before it saves."""
+    args = args or {}
+    verb = args.get("_verb")
+    if verb in ("set", "unset"):
+        try:
+            return _cmd_config_write(args)
+        except ConfigError as e:
+            # `die`, not a traceback. This is the command an installer shells out
+            # to, and a stack trace in its output is a refusal nobody can act on.
+            from .tree import die
+            die(f"{e}")
+    print(json.dumps(cfg, indent=2, sort_keys=True))
+    return 0
+
+
+def _key_path(dotted: str) -> list:
+    """Split and CHECK a dotted key against the shipped shape.
+
+    Refused here rather than at the next load. A key nobody recognises is fatal to
+    every command in the repo — so an installer that writes one has not configured
+    something, it has broken the harness for whoever runs it next, and it finds out
+    from them.
+    """
+    parts = [seg for seg in dotted.split(".") if seg]
+    if not parts:
+        raise ConfigError("name a key to write, e.g. session.mcp")
+    node, walked = DEFAULTS, ""
+    for i, seg in enumerate(parts):
+        if walked in _OPEN_MAPS:
+            # The repo's to invent — a command name under `verify` is data, not
+            # schema, and checking it against the defaults would refuse every
+            # legal one.
+            return parts
+        if not isinstance(node, dict) or seg not in node:
+            known = ", ".join(sorted(node)) if isinstance(node, dict) else "(a value)"
+            raise ConfigError(f"unknown config key '{dotted}' — "
+                              f"'{'.'.join(parts[:i + 1])}' is not one of: {known}")
+        node = node[seg]
+        walked = f"{walked}.{seg}" if walked else seg
+        if not isinstance(node, dict) and i < len(parts) - 1:
+            raise ConfigError(f"'{walked}' is a value, so '{dotted}' cannot exist "
+                              f"under it")
+    return parts
+
+
+def _parse_value(raw: str, force_json: bool):
+    """A value from a command line. JSON when it parses as JSON, else the string.
+
+    `jarvis work config set ids.prefix P` should not need quoting, and
+    `jarvis work config set hooks.stop.enabled false` must not write the STRING "false" —
+    which is truthy, and would switch on the thing it was typed to switch off.
+    """
+    if force_json:
+        try:
+            return json.loads(raw)
+        except json.JSONDecodeError as e:
+            raise ConfigError(f"--json given but {raw!r} is not JSON: {e}") from None
+    try:
+        return json.loads(raw)
+    except json.JSONDecodeError:
+        return raw
+
+
+#: Written where a value would be, and not values themselves — so they are never
+#: JSON-quoted into looking like one. `"(unset)"` is a string somebody could set.
+_UNSET = "(unset)"
+_DEFAULTED = "(the shipped default)"
+_REMOVED = "(removed — the schema has no such key, so there is no default to fall back to)"
+_MARKERS = (_UNSET, _DEFAULTED, _REMOVED)
+
+
+def _show(v) -> str:
+    return v if isinstance(v, str) and v in _MARKERS else json.dumps(v)
+
+
+def _present(node, parts) -> bool:
+    """Is this dotted path actually IN the file? Used to decide whether an `unset`
+    of a key the schema does not know is a removal or a typo."""
+    for seg in parts:
+        if not isinstance(node, dict) or seg not in node:
+            return False
+        node = node[seg]
+    return True
+
+
+def _why_invalid(raw: dict):
+    """The ConfigError this file would raise, or None. Deep-copied through JSON
+    because `_merge` and `_validate` are free to look at anything."""
+    try:
+        _validate(_merge(DEFAULTS, json.loads(json.dumps(raw))))
+    except ConfigError as e:
+        return e
+    return None
+
+
+def _cmd_config_write(args) -> int:
+    if args.get("branch"):
+        raise ConfigError("`config set` writes this checkout's own config — it "
+                          "cannot write another branch's. Check that branch out "
+                          "and run it there.")
+    repo = Path(args["project_root"])
+    dotted = args.get("key") or ""
+    p = repo / CONFIG_PATH
+
+    raw, was = {}, ""
+    if p.is_file():
+        try:
+            was = p.read_text()
+            raw = json.loads(was)
+        except json.JSONDecodeError as e:
+            raise ConfigError(f"{CONFIG_PATH} is not valid JSON, so it cannot be "
+                              f"written safely: {e}") from None
+        if not isinstance(raw, dict):
+            raise ConfigError(f"{CONFIG_PATH} must contain a JSON object")
+    schema = raw.pop("$schema", None)
+
+    unknown = False
+    try:
+        parts = _key_path(dotted)
+    except ConfigError:
+        # An `unset` may remove a key the shipped schema does not know, and that is
+        # not a loophole — it is the repair. A typo'd key, or one written by a
+        # different version of the plugin, is fatal to every command in the repo,
+        # and refusing to remove it would leave the only tool that can fix it
+        # refusing on the grounds that the thing being fixed is broken.
+        parts = [seg for seg in dotted.split(".") if seg]
+        if args["_verb"] != "unset" or not _present(raw, parts):
+            raise
+        unknown = True
+
+    # What was wrong with this file BEFORE the write, so a refusal can tell the two
+    # apart. Without it, `config set ids.prefix P` on a file with an unrelated bad
+    # key fails with a message about a key the caller never touched.
+    before_err = _why_invalid(raw)
+
+    node = raw
+    for seg in parts[:-1]:
+        nxt = node.get(seg)
+        if not isinstance(nxt, dict):
+            nxt = {}
+            node[seg] = nxt
+        node = nxt
+    before = node.get(parts[-1], _UNSET)
+    if args["_verb"] == "unset":
+        node.pop(parts[-1], None)
+        # An override removed from a nested section leaves `{}` behind, which is a
+        # section a reader would take for a deliberate empty. Prune back up.
+        trail, cur = [], raw
+        for seg in parts[:-1]:
+            trail.append((cur, seg))
+            cur = cur[seg]
+        for parent, seg in reversed(trail):
+            if parent[seg] == {}:
+                parent.pop(seg)
+        after = _REMOVED if unknown else _DEFAULTED
+    else:
+        after = _parse_value(args.get("value", ""), args.get("json") == "true")
+        node[parts[-1]] = after
+
+    # Validated as a WHOLE before anything is saved. A key can be legal on its own
+    # and illegal beside its neighbours — `session.mcp` without `session.tool` is
+    # exactly that — and the alternative is writing a file that makes every later
+    # command in the repo fail.
+    after_err = _why_invalid(raw)
+    if after_err:
+        if before_err and str(before_err) == str(after_err):
+            raise ConfigError(
+                f"{CONFIG_PATH} was ALREADY invalid before this change and still "
+                f"is — your write is not the cause and has not been saved. The "
+                f"problem is: {after_err}\n"
+                f"       Fix that first. `config unset <key>` drops an override, "
+                f"and it will remove a key this schema does not recognise.")
+        raise after_err
+
+    if schema is not None:
+        raw = {"$schema": schema, **raw}
+    # This writes ONE canonical shape, so a file that was formatted differently
+    # comes back reformatted. That is the right trade for a file two installers may
+    # both write — they cannot fight over layout — but it is somebody else's diff,
+    # so it is announced rather than discovered.
+    reflowed = was.strip() and json.dumps(json.loads(was), indent=2) + "\n" != was
+    p.parent.mkdir(parents=True, exist_ok=True)
+    # Written beside the target and renamed: a half-written config is a repo where
+    # nothing runs, and an interrupted write is not a hypothetical on a laptop.
+    tmp = p.with_suffix(".json.tmp")
+    tmp.write_text(json.dumps(raw, indent=2) + "\n")
+    tmp.replace(p)
+    print(f"{dotted}: {_show(before)} -> {_show(after)}")
+    print(f"wrote {CONFIG_PATH}" + (" — and reformatted it to canonical 2-space "
+                                    "JSON, so the diff is larger than this one key"
+                                    if reflowed else ""))
+    return 0