@appchy/jarvis 0.1.37 → 0.1.39

package/harness/harness/align.py

@@ -0,0 +1,582 @@
+import re
+from pathlib import Path
+
+from . import ids
+from .tree import _skipped, rel
+from .frontmatter import as_list, parse_frontmatter, unquote
+from . import registry
+from .registry import (definition_sites, definition_surfaces, hosts, is_judgement,
+                       locate_system, scan_domains, scan_systems)
+from .model import scan_features
+from .shard import _load_run
+from .lint import _feature_ac_ids, feature_ac_levels
+
+#: Sibling repos whose ledger ids may legally appear here. Set from config
+#: (`ids.foreign`); empty by default, because a fresh repo has no siblings and a
+#: hardcoded list of somebody else's repo names is exactly the bias this plugin
+#: exists to remove.
+FOREIGN_REPOS: tuple = ()
+
+#: Directories under `work/` that are NOT durable governance. `product/` and
+#: `architecture/` are handled on their own (they are the two sides the
+#: single-feature check compares); the rest here hold work-in-flight or history,
+#: and an id cited in a task brief says nothing about whether a rule's blast
+#: radius reaches past one feature.
+_NOT_GOVERNANCE = {"product", "architecture", "versions", "backlog", "archive",
+                   "research", "plans"}
+
+
+def live_surfaces(root: Path) -> list:
+    """The governance a fresh session actually reads and can be MISLED by.
+
+    Deliberately excludes `versions/*/complete/**`: a finished task's plan.md
+    describing a since-deleted package is accurate HISTORY, not drift. Unscoped,
+    these checks return thousands of historical hits and nobody reads the report —
+    which is the failure mode that makes a lint worthless."""
+    repo = root.parent
+    out = []
+    for name in ("CLAUDE.md", "STANDARDS.md", "README.md", "Makefile", "package.json"):
+        if (repo / name).is_file():
+            out.append(repo / name)
+    for pattern in ("ROADMAP.md", "README.md", "DECISIONS.md",
+                    "product/*.md", "*/README.md",
+                    "architecture/*.md", "versions/*/version.md",
+                    "versions/*/architecture.md", "versions/*/design.md",
+                    "versions/*/queue/*/*.md", "versions/*/in-progress/*/*.md",
+                    # …and the same, one level deeper, inside an epic. A
+                    # `complete/` bucket stays excluded at BOTH depths: a finished
+                    # task's plan describing a since-deleted package is accurate
+                    # history, not drift.
+                    "versions/*/*/epic.md", "versions/*/*/queue/*/*.md",
+                    "versions/*/*/in-progress/*/*.md",
+                    "backlog/*/*.md", "backlog/*/*/*.md"):
+        out += sorted(root.glob(pattern))
+    # The repo's OWN `.claude/` — hooks, skills and scripts a session reads, and a
+    # place ids genuinely get cited.
+    out += sorted((repo / ".claude").rglob("*.md"))
+    out += sorted((repo / ".claude").rglob("*.py"))
+    return [p for p in out if p.is_file() and not _is_harness_code(p)]
+
+
+def _is_harness_code(p: Path) -> bool:
+    """The harness's OWN modules and suite, wherever they sit.
+
+    Not governance, and not a citation surface: the suite's fixtures deliberately
+    render in the shipped dialect, so reading them means a consumer's `align`
+    reports the PLUGIN's test data as dangling citations against the consumer's
+    ledger — ids that repo never wrote and cannot resolve.
+
+    Excluded structurally rather than by location, because "the payload lives in the
+    plugin cache, so this cannot happen" is only true after cutover. Before it, both
+    consumer repos vendor this tree under `.claude/skills/work/`, which is exactly
+    where the check looks — and one of them already hit it, reporting an invented
+    `G-200` test fixture as a dangling citation.
+    """
+    parts = p.parts
+    return ("harness" in parts and p.suffix == ".py") or p.name.startswith("test_")
+def _align_definitions(root: Path) -> list:
+    """Every definition surface must be able to resolve the ids it hosts. Both
+    findings here have actually happened: three ids were written at `##`, invisible
+    to any lookup while shipped code cited them; five had two `###` headings, so a
+    lookup returned two homes.
+
+    Scoped by the SURFACE LIST, not by filename. The `##`-form check used to run on
+    `DECISIONS.md` alone, so the same mistake in `architecture/graph.md` — and now
+    in `quality/README.md` — went unreported: the check was as narrow as the
+    hosting rule it grew up beside."""
+    out = []
+    for home, md in definition_surfaces(root):
+        if not md.is_file():
+            continue
+        for m in ids.heading(2).finditer(md.read_text()):
+            out.append(("error", "definition-form", f"{home}: {m.group(1)} is a "
+                        f"`##` heading — the definition site is `### {m.group(1)}`, "
+                        f"and a resolver cannot see it here"))
+    # One definition site per id, across every surface. Once a rule's home moves to
+    # its system or its domain, a leftover `### <id>` on the old surface is a SECOND
+    # home — exactly the drift the split exists to remove.
+    for id_, sites in sorted(definition_sites(root).items(),
+                             key=lambda kv: ids.sort_key(kv[0])):
+        if len(sites) > 1:
+            homes = ", ".join(home for home, _ in sites)
+            out.append(("error", "definition-form", f"{id_} has {len(sites)} `###` "
+                        f"definition sites ({homes}) — an id has exactly one (a "
+                        f"refinement is `#### {id_} — Addendum`)"))
+    return out
+def _align_ledger_index(root: Path) -> list:
+    """A legacy ledger's Index vs its own `###` entries. Ledger-specific ON PURPOSE
+    — an Index is a property of that one file, not of hosting — and it disappears
+    with the file when the ledger dissolves."""
+    out = []
+    md = root / "DECISIONS.md"
+    if not md.is_file():
+        return out
+    text = md.read_text()
+    indexed = {m.group(1) for m in ids.index_entry().finditer(text)}
+    defined = {m.group(1) for m in ids.heading(3).finditer(text)}
+    for id_ in sorted(defined - indexed, key=ids.sort_key):
+        out.append(("warn", "ledger-index", f"DECISIONS.md: {id_} is defined but "
+                    f"missing from the Index"))
+    for id_ in sorted(indexed - defined, key=ids.sort_key):
+        out.append(("error", "ledger-index", f"DECISIONS.md: {id_} is in the Index "
+                    f"but has no `### {id_}` entry"))
+    return out
+#: A line that INTRODUCES an id as an illustration is not citing it. Docs that
+#: teach the id format ("pass an artifact id, e.g. `D87`") would otherwise report a
+#: permanent dangling citation for an id nobody ever meant to exist — and a lint
+#: with a permanent red line is one people learn to scroll past. Same shape and
+#: same reasoning as `_RETIRED_MARKER`: suppress by what the line SAYS.
+_EXAMPLE_MARKER = re.compile(
+    r"\be\.g\.|\bfor example\b|\bsuch as\b|\bfor instance\b|\bplaceholder\b"
+    r"|\billustrat|\bexamples?:", re.IGNORECASE)
+_RETIRED_MARKER = re.compile(
+    r"retire|delet|\bis gone\b|\bare gone\b|no longer|there is no|\bno \b.{0,12}\b(target|table|package)\b"
+    r"|supersed|\bdead\b|never (landed|existed)|renamed|does not exist|doesn't exist|→|->|~~|\bwas\b"
+    r"|\bused to\b|\bstale\b",
+    re.IGNORECASE)
+
+#: A dated `log:` entry — `  - 2026-07-24 defined (…)`. History is written in the
+#: vocabulary of its own date, so a retired name inside one is the record working,
+#: not drift: "on this date we settled on `@acme/access`" stays TRUE after the
+#: package is split. Editing it to today's names would falsify the log, which is
+#: the opposite of what this lint is for.
+_DATED_LOG_ENTRY = re.compile(r"^\s*-\s\d{4}-\d{2}-\d{2}\s")
+
+
+def _foreign_qualifier() -> re.Pattern:
+    """A sibling repo's ledger, named right before the id it belongs to — `acme
+    D147`, `acme:D172`, `acme **D-9**`. That is a cross-repo citation, not a local
+    dangling one: the id is not ours to define and never will be, so reporting it
+    forever trains people to scroll past the check.
+
+    Scoped tightly to the id's own LEFT CONTEXT rather than the whole line, so a
+    line that merely mentions another repo still has its own ids checked. Returns a
+    never-matching pattern when no siblings are configured."""
+    if not FOREIGN_REPOS:
+        return re.compile(r"(?!)")
+    alt = "|".join(re.escape(r) for r in FOREIGN_REPOS)
+    return re.compile(rf"(?:{alt})\s*[:=]?\s*[`*\[(\"']{{0,3}}$", re.IGNORECASE)
+def _align_citations(root: Path) -> list:
+    """A cited id that resolves to nothing."""
+    out = []
+    # Defined = every surface that can host a definition, plus the ids a host still
+    # declares only in its rules map. A citation must not go dangling merely
+    # because a rule's home moved.
+    defined = set(definition_sites(root))
+    for _, _, rules, _ in hosts(root):
+        defined |= set(rules)
+    foreign = _foreign_qualifier()
+    dangling: dict = {}
+    for p in live_surfaces(root):
+        try:
+            text = p.read_text(errors="ignore")
+        except Exception:
+            continue
+        label = rel(p, root)
+        # A line that names a deleted id IN ORDER TO SAY IT IS DELETED is a record,
+        # not drift — the same reasoning `_align_retired` uses for retired concepts.
+        # Without this, every de-cite pass would flag the note it just wrote, and
+        # the fix people reach for is deleting the note.
+        #
+        # Scoped to the FILE, not to the line and its neighbour. A doc that says an
+        # id is retired goes on to discuss it in the past tense, and those sentences
+        # carry no marker of their own — "`D-107` wanted a PSL because its entry was
+        # a bare domain" is narration, three paragraphs above the line that calls it
+        # retired. Matching per-line meant chasing that with ever more verbs in
+        # `_RETIRED_MARKER`, which is a losing regex; a document that has told us the
+        # id is dead cannot then be citing it live.
+        lines = text.splitlines()
+        excused = {ids.normalise(m.group(0))
+                   for i, ln in enumerate(lines)
+                   for m in ids.ID.finditer(ln)
+                   if _RETIRED_MARKER.search(ln)
+                   or _EXAMPLE_MARKER.search(ln)
+                   # Both markers get the same one-line lookback. Prose wraps, so
+                   # "e.g. a" and the id it introduces routinely land on separate
+                   # lines — and without this a README that merely teaches the id
+                   # format reports a permanent dangling citation for an id nobody
+                   # ever meant to exist.
+                   or (i and (_RETIRED_MARKER.search(lines[i - 1])
+                              or _EXAMPLE_MARKER.search(lines[i - 1])))}
+        for ln in lines:
+            for m in ids.ID.finditer(ln):
+                if foreign.search(ln[:m.start()]):
+                    continue
+                id_ = ids.normalise(m.group(0))
+                if id_ not in defined and id_ not in excused:
+                    dangling.setdefault(id_, set()).add(label)
+    for id_, files in sorted(dangling.items(), key=lambda kv: ids.sort_key(kv[0])):
+        out.append(("error", "dangling-citation",
+                    f"{id_} resolves to nothing — cited by {len(files)} live "
+                    f"file(s): {', '.join(sorted(files)[:3])}"))
+    return out
+def _align_hosts(root: Path) -> list:
+    """A region owned twice has no single home; a rule with no `enforced_by` is a
+    wish; a rule hosted twice belongs to nobody.
+
+    Checked over SYSTEMS AND DOMAINS together. Split in two, each half would see
+    only its own kind and an id sitting in both `quality/README.md` and
+    `architecture/harness.md` would pass twice."""
+    out = []
+    owners: dict = {}
+    for s in scan_systems(root):
+        for c in s.code:
+            owners.setdefault(c, []).append(s.name)
+    for c, names in sorted(owners.items()):
+        if len(names) > 1:
+            out.append(("error", "region-owner", f"code region '{c}' is claimed by "
+                        f"{len(names)} systems ({', '.join(names)}) — exactly one owns it"))
+    # A domain declaring `code:` would overlap every system that already owns those
+    # files, and one-region-one-owner is what the whole `code:` vocabulary rests on.
+    # A domain's rules key off `task.owner` instead — that is the seam, not regions.
+    for d in scan_domains(root):
+        if d.code:
+            out.append(("error", "region-owner", f"domain '{d.name}' declares "
+                        f"code: [{', '.join(d.code)}] — a region belongs to a "
+                        f"SYSTEM; a domain's rules derive from `task.owner`"))
+    hosted: dict = {}
+    judgement = []
+    for home, name, rules, _ in hosts(root):
+        for id_, evidence in rules.items():
+            hosted.setdefault(id_, []).append(home)
+            if is_judgement(evidence):
+                judgement.append(f"{id_} ({home})")
+            elif not evidence:
+                out.append(("warn", "no-enforced-by", f"{id_} ({name}) declares no "
+                            f"enforced_by — a rule nothing can catch is a wish"))
+    for id_, homes in sorted(hosted.items(), key=lambda kv: ids.sort_key(kv[0])):
+        if len(homes) > 1:
+            out.append(("error", "rule-home", f"{id_} is hosted by "
+                        f"{len(homes)} docs ({', '.join(homes)}) — an id has one home"))
+    # Reported, never silent. Some rules genuinely are judgement — `commercial` is
+    # made of them — so "a person decides" is a legal answer; but if it is never
+    # counted it becomes the cheap way to clear the warning above, and nobody can
+    # see which rules could really have been mechanised.
+    if judgement:
+        out.append(("info", "enforced-by-judgement", f"{len(judgement)} rule(s) are "
+                    f"enforced by judgement, not a check: "
+                    f"{', '.join(sorted(judgement, key=ids.sort_key)[:4])}"
+                    + (" …" if len(judgement) > 4 else "")))
+    return out
+def _align_domains(root: Path) -> list:
+    """A folder that looks like an org-domain but does not declare itself one.
+
+    `type: domain` is what makes a domain, deliberately — not the filename — so a
+    charter that loses its frontmatter becomes invisible to every lookup while
+    still sitting there full of `### <id>` headings. Nothing else reports it: the
+    rules simply stop resolving, and `where` says an id has no home while the file
+    defining it is right there.
+
+    Scoped to top-level folders that are NOT structural (`versions/`, `backlog/`,
+    `archive/` and friends carry READMEs of their own kind), so this asks only about
+    folders whose shape says "domain".
+    """
+    out = []
+    declared = set(registry.DOMAIN_ORDER)
+    for d in sorted(p for p in root.iterdir() if p.is_dir()):
+        if d.name in _NOT_GOVERNANCE or d.name.startswith("."):
+            continue
+        md = d / "README.md"
+        if not md.is_file():
+            continue
+        fm = parse_frontmatter(md.read_text())
+        if fm.get("type") == "domain":
+            continue
+        # A folder the CONFIG calls a domain is unambiguous — the repo said so.
+        # Anything else is a guess, so it is a warning rather than an error, and it
+        # names the one-line fix.
+        level = "error" if d.name in declared else "warn"
+        out.append((level, "undeclared-domain",
+                    f"{d.name}/README.md has no `type: domain` frontmatter"
+                    + (" but `domains.order` lists it as one" if d.name in declared
+                       else " — add it, or the rules it hosts resolve nowhere")))
+    return out
+def _align_single_feature(root: Path) -> list:
+    """A hosted rule that NOTHING outside one feature refers to — the routing test
+    says a rule whose blast radius is one feature's behaviour is that feature's
+    `B-nn`, not a system's rule id.
+
+    A WORKLIST, not a verdict, and deliberately worded as one. Whether a rule is
+    product behaviour or a build rule is a claim about its NATURE, and citation
+    topology cannot settle it: a build rule that happens to protect one feature's
+    surface is cited by exactly that feature and is still correctly a system rule.
+    The routing test is a question a person answers.
+
+    So this reports the one thing that IS checkable — nothing outside
+    `product/<feature>.md` depends on this id — and says "triage", never "misfiled".
+    Measured against three candidate signals, which is why it is the narrowest of
+    them: naming a feature in the PROSE was 0-for-4 (every hit was a table or field
+    that shares a feature's name); being cited by one feature alone flagged 22 of
+    55. This flags 13, and two of those are genuinely build rules — so expect
+    roughly a third to be dismissed, and dismissing one is a result, not a failure
+    of the check."""
+    out = []
+    def cited(md: Path) -> set:
+        if not md.is_file():
+            return set()
+        return {ids.normalise(m.group(0)) for m in ids.ID.finditer(md.read_text())}
+
+    features = {}
+    for md in sorted((root / "product").glob("*.md")):
+        if md.stem == "README":
+            continue
+        for id_ in cited(md):
+            features.setdefault(id_, set()).add(md.stem)
+    # Every OTHER governance surface that names an id. If any of them does, the rule
+    # already reaches past the one feature and there is nothing to triage.
+    #
+    # Derived from the TREE, not from `scan_domains`, and not from a hardcoded list
+    # of domain names. Both alternatives are wrong in opposite directions: a
+    # hardcoded tuple silently ignores a repo's tenth domain, and keying off
+    # `type: domain` makes the answer depend on whether a folder declared itself —
+    # a `quality/README.md` that cites the id still proves the rule reaches past the
+    # feature, frontmatter or not. What matters is that some governance doc names
+    # it, and that is a question about the file, not its metadata.
+    elsewhere = {}
+    for md in sorted((root / "architecture").glob("*.md")):
+        for id_ in cited(md):
+            elsewhere.setdefault(id_, set()).add(f"architecture/{md.stem}")
+    for d in sorted(p for p in root.iterdir() if p.is_dir()):
+        if d.name in _NOT_GOVERNANCE:
+            continue
+        for md in sorted(d.rglob("*.md")):
+            for id_ in cited(md):
+                elsewhere.setdefault(id_, set()).add(f"{d.name}/{md.stem}")
+    legacy = cited(root / "DECISIONS.md")
+
+    for home, name, rules, _ in hosts(root):
+        for id_ in sorted(rules, key=ids.sort_key):
+            named = features.get(id_, set())
+            if len(named) != 1 or id_ in legacy:
+                continue
+            if elsewhere.get(id_, set()) - {home}:
+                continue
+            feature = sorted(named)[0]
+            out.append(("warn", "single-feature", f"{id_} ({name}) is referenced by "
+                        f"product/{feature}.md and by nothing else — triage it: a "
+                        f"rule that only constrains one feature's behaviour is that "
+                        f"feature's B-nn, not a hosted rule id"))
+    return out
+def _align_versions(root: Path, s: dict) -> list:
+    """A version whose every task is complete but which was never released, and a
+    released version still carrying the briefs that should have collapsed."""
+    out = []
+    for v in s["versions"]:
+        tasks = v.all_tasks()
+        if tasks and not v.released and all(t.status == "complete" for t in tasks):
+            out.append(("warn", "version-unreleased", f"version {v.name}: all "
+                        f"{len(tasks)} tasks are complete but it is not released — "
+                        f"`jarvis work release {v.name}`"))
+        if v.released:
+            for brief in ("architecture.md", "design.md"):
+                if (v.folder / brief).is_file():
+                    out.append(("warn", "released-brief", f"version {v.name}: "
+                                f"released but still carries {brief} — a cut-local "
+                                f"brief collapses at release"))
+            # Same rule, one tier down: an epic is the plan-it-together doc, and
+            # `release` removes it. One left standing means a release that did not
+            # go through `jarvis work release`.
+            for e in v.epics:
+                if e.planned:
+                    out.append(("warn", "released-brief", f"version {v.name}: "
+                                f"released but epic '{e.name}' still carries "
+                                f"epic.md — an epic archives at release"))
+    return out
+#: An agent-file reference in skill prose, in either of the two shapes an agent dir
+#: takes: `.claude/agents/<name>.md` in a repo that keeps its own agents, and a bare
+#: `agents/<name>.md` (however deep the relative prefix) once the same prose ships
+#: inside a plugin, where the payload's agent dir sits beside its skills. Anchoring
+#: on `.claude/` alone made the check silently vacuous the moment the prose moved.
+_AGENT_REF = re.compile(r"(?:\.claude/|(?:\.\./)+)?agents/([a-z0-9-]+)\.md")
+
+
+def _align_agents(root: Path) -> list:
+    """A skill that routes work to an agent definition that isn't where the Agent
+    tool loads from. The delegation simply cannot execute."""
+    out = []
+    repo = root.parent
+    for skills_dir in sorted(repo.rglob("skills")):
+        if not skills_dir.is_dir() or _skipped(skills_dir, repo):
+            continue
+        # Both dirs an agent file can legally live in, relative to this skills dir:
+        # a sibling `agents/` (the plugin payload's shape) and the repo's own
+        # `.claude/agents/`. A name found in either resolves.
+        available = set()
+        for d in (skills_dir.parent / "agents", repo / ".claude" / "agents"):
+            if d.is_dir():
+                available |= {p.stem for p in d.glob("*.md")}
+        for p in sorted(skills_dir.rglob("*.md")):
+            text = p.read_text(errors="ignore")
+            for m in set(_AGENT_REF.findall(text)):
+                if m not in available:
+                    out.append(("error", "missing-agent", f"{rel(p, root)} cites "
+                                f"agents/{m}.md, which does not exist "
+                                f"(available: {', '.join(sorted(available)) or 'none'})"))
+    return out
+def _align_retired(root: Path) -> list:
+    """A concept that no longer exists, still named on a live governance surface.
+    This is the highest-frequency drift class and the most dangerous: a doc
+    describing a retired design reads exactly like current truth, so the next
+    session builds against it. The term list is DATA, declared in
+    `architecture/harness.md`'s `retired:` — not hardcoded here."""
+    out = []
+    md = locate_system(root, "harness")
+    if not md:
+        return out
+    entries = as_list(parse_frontmatter(md.read_text()).get("retired"))
+    terms = []
+    for e in entries:
+        e = unquote(e)
+        term, _, why = e.partition("=")
+        if term.strip():
+            terms.append((term.strip(), why.strip()))
+    if not terms:
+        return out
+
+    # A legacy ledger and the harness system are where retired terms are
+    # legitimately NAMED (as history and as this very list) — flagging them is pure
+    # noise.
+    exempt = {root / "DECISIONS.md", md}
+    for term, why in terms:
+        hits = []
+        rx = re.compile(re.escape(term))
+        for p in live_surfaces(root):
+            if p in exempt:
+                continue
+            try:
+                lines = p.read_text(errors="ignore").splitlines()
+            except Exception:
+                continue
+            # A doc that names a retired thing IN ORDER TO SAY IT IS RETIRED is
+            # correct, not drift — "`make db-diff` is dead", "@acme/db deleted". Only
+            # a line that uses the term as if it were live is a finding, and the
+            # marker is looked for on BOTH neighbours: prose wraps at ~100 columns,
+            # so the disclaimer lands either side of the term with equal ease —
+            # "version stories.md is\nretired" was reported as drift by a lint that
+            # only looked backwards.
+            if any(rx.search(ln)
+                   and not _RETIRED_MARKER.search(ln)
+                   and not _DATED_LOG_ENTRY.match(ln)
+                   and not (i and _RETIRED_MARKER.search(lines[i - 1]))
+                   and not _RETIRED_MARKER.search(lines[i + 1] if i + 1 < len(lines) else "")
+                   for i, ln in enumerate(lines)):
+                hits.append(rel(p, root))
+        if hits:
+            out.append(("warn", "retired-concept",
+                        f"'{term}' is retired ({why}) but still named in "
+                        f"{len(hits)} live file(s): {', '.join(sorted(hits)[:3])}"
+                        + (" …" if len(hits) > 3 else "")))
+    return out
+def _covers_bindings(repo: Path) -> dict:
+    """`{feature: {AC-nn}}` claimed by a test — read from the binding the RUNNER
+    reads, never from a comment.
+
+    Three forms, one meaning, all feature-qualified because a bare `AC-01` names a
+    different criterion in every feature file:
+
+        covers("sharing/AC-01", "sharing/AC-04")     a vitest file or suite
+        { tag: ["@sharing/AC-01"] }                  the Playwright equivalent
+        COVERS("sharing/AC-01")                      a C++ doctest TEST_CASE
+
+    **Comments are deliberately not read.** A `// Covers:` header survives the test
+    being renamed, skipped or deleted, so the criterion goes on claiming evidence
+    that no run produces — the exact failure this lint exists to find. Reading the
+    call means a binding cannot outlive the test that carries it: delete the test
+    and the id stops appearing here and in the coverage shard together.
+
+    **The C++ patterns were added 2026-08-23, and their absence was not neutral.**
+    A repo whose criteria are proven by a compiled suite had every one of them
+    reported `checked-unbound` — a standing warning nobody could ever clear, while
+    `coverage` read the same repo's shards and correctly called them proven. Two
+    commands disagreeing about one fact is how a report stops being read. The match
+    itself needed nothing new: a quoted `"<feature>/AC-nn"` is the same shape in
+    every language, which is why the vocabulary was chosen that way."""
+    found: dict = {}
+    for pattern in ("*.test.ts", "*.spec.ts", "*.test.js", "*.spec.js", "*.mjs",
+                    "*_test.cpp", "*_tests.cpp", "*_test.cc", "*_test.cxx"):
+        for p in repo.rglob(pattern):
+            if _skipped(p, repo):
+                continue
+            text = p.read_text(errors="ignore")
+            # The leading `@` is Playwright's tag marker; `covers()` takes the bare id.
+            for feature, ac in re.findall(r"""["']@?([a-z][a-z0-9-]*)/(AC-\d+)["']""", text):
+                found.setdefault(feature, set()).add(ac)
+    return found
+def _align_acceptance(root: Path) -> list:
+    """The spec↔evidence gap: an AC claimed by a test that the feature never
+    declared, a `[x]` with no binding, a binding with no `[x]`, and a feature whose
+    `state:` runs ahead of its evidence."""
+    out = []
+    repo = root.parent
+    features = {p.stem: p for p in scan_features(root)}
+    tasks = {p.parent.name for p in root.glob("versions/*/*/*/task.md")}
+    bindings = _covers_bindings(repo)
+
+    for qualifier, acs in sorted(bindings.items()):
+        if qualifier in features:
+            declared = _feature_ac_ids(features[qualifier].read_text())
+            for ac in sorted(acs - declared):
+                out.append(("error", "orphan-ac", f"a test claims "
+                            f"{qualifier}/{ac}, which that feature does not declare"))
+        elif qualifier in tasks:
+            out.append(("warn", "binding-qualifier", f"a test binds to "
+                        f"'{qualifier}', which is a TASK name, not a feature — "
+                        f"tasks are archived, so the binding dies with it"))
+        else:
+            # Neither a feature nor a task — so the binding names nothing at all and
+            # the run credits a promise that does not exist. Silently ignored until
+            # now, which is the false-green class this whole join exists to catch: a
+            # typo, a renamed feature, or a DOMAIN (`quality/AC-01` — domains host
+            # rule ids, never criteria) all landed here and reported clean.
+            out.append(("error", "binding-qualifier", f"a test binds to "
+                        f"'{qualifier}/{sorted(acs)[0]}', and '{qualifier}' is "
+                        f"neither a feature nor a task — the binding names nothing"))
+
+    # A binding read from source says only that a test NAMES the criterion — not
+    # that it proved anything. A `test.skip`/`todo` carries its tag exactly like a
+    # passing test does, so without the run this told authors to tick criteria whose
+    # only test never executed, which is the false green the whole join exists to
+    # catch. Only statuses the run explicitly reports as not-passed are subtracted,
+    # so `align` still works before anyone has produced a run.
+    run, _, _ = _load_run(repo)
+    unproven = {cid for cid, status in run.items() if status in ("todo", "failed")}
+
+    for name, md in sorted(features.items()):
+        text = md.read_text()
+        levels = feature_ac_levels(text)
+        declared = set(levels)
+        checked = {ac for ac, (_, is_built) in levels.items() if is_built}
+        bound = {ac for ac in bindings.get(name, set()) & declared
+                 if f"{name}/{ac}" not in unproven}
+        state = parse_frontmatter(text).get("state")
+        # An `eyes-on` criterion is settled by a person looking, so it has no test to
+        # be missing — demanding a binding for one would be a warning nobody can ever
+        # clear, and `coverage` already keeps it out of the ratio for the same
+        # reason. Its evidence is the dated ✔ in the feature file.
+        eyes = {ac for ac, (level, _) in levels.items() if level == "eyes-on"}
+        if checked - bound - eyes:
+            out.append(("warn", "checked-unbound", f"feature {name}: "
+                        f"{len(checked - bound - eyes)} AC(s) checked with no test binding "
+                        f"— a [x] is a claim, a passing bound test is evidence"))
+        if bound - checked:
+            out.append(("warn", "bound-unchecked", f"feature {name}: "
+                        f"{', '.join(sorted(bound - checked))} bound by a passing "
+                        f"test but left unchecked — the spec understates what is built"))
+        if state == "shipped" and not bound:
+            out.append(("error", "shipped-unproven", f"feature {name}: state is "
+                        f"'shipped' with zero test bindings"))
+        if state == "building" and declared and checked == declared:
+            # Ticked boxes are the ONLY half of `shipped` this lint can see, and they
+            # are the weakest half. It cannot see whether a run proves them — a
+            # criterion bound to a declared-but-unwritten placeholder looks identical
+            # here — and it cannot see a release reference at all. On the three
+            # features it first fired against, all three were right to be `building`:
+            # one had an open behaviour, one had two unwritten placeholders, and one
+            # was waiting on a release that had not happened. Each said so in its own
+            # log. So this names a candidate and the two things it did not check; it
+            # never says "flip it".
+            out.append(("warn", "state-lag", f"feature {name}: every AC is checked while state is "
+                        f"still 'building' — a shipped candidate. Unchecked here: whether a run "
+                        f"PROVES them (`jarvis work coverage --feature {name}`) and whether a release "
+                        f"has shipped them. The feature's own log usually says which is missing"))
+    return out