aw-spec-cli 0.1.32 → 0.1.34

package/assets/.appweaver/scripts/python/aw-plan-coverage.py

@@ -29,6 +29,13 @@ TWO KINDS OF ELEMENT.
 An element is a GAP when it is checked and not found, or when the model's report does not
 say it was done — including when the report does not mention it at all.
 
+THE API PLAN. A backend plan realises the endpoints of the API plan beside it and does not
+restate them, so `--api-plan` names that document — the feature's api-plan.md on the master
+path, a change's delta-api-plan.md on the delta path — and each endpoint block in it (a
+`### `VERB /route`` heading under "## Endpoints" or "## Endpoints added or changed") is a
+report-only element of the backend lane. A plan written before API plans existed keeps its
+endpoints in its own API section and is read as it always was; a name in both is listed once.
+
 THE REPORT. `--reported` takes the `elements` list a generation pass returned —
 [{"element": "<name as listed>", "status": "done|blocked", "reason": "…"}] — and may be
 given more than once; a later report overrides an earlier one for the same element, which
@@ -36,11 +43,44 @@ is how a completion pass's answers replace the first pass's.
 
 `--list-only` returns the element names without scanning, for the generation prompt.
 
+TEST CITATIONS (`--citations`, the `test-citations` subcommand). The same plan read from the
+other side: which of the requirements the plan traces does NO test of the slice name.
+`implement` tells every paired test to cite the spec id it covers, and a requirement whose
+test was never written leaves nothing red — the suite is green and the gap is invisible.
+  required     FR- and BR- ids — the testable behaviour and the invariants. From a master
+               plan, the ids in its Traceability section (located by heading text, so §6,
+               §4 and §7 all count); from a delta plan (`--mode delta`), the ids its ADDED,
+               MODIFIED, model-change and interaction-state rows serve, removed rows aside.
+  reported     every other id class (US-, UX-, CN-, DC-, IC-, SC-) no test names — listed,
+               never required, since a retention period or a success criterion rarely has
+               a unit test of its own.
+  a citation   the id anywhere in a test file — its name, a comment, an attribute, a tag —
+               as `FR-004`, `FR_004` or `FR004`, in any case, leading zeros ignored, and
+               not glued to a word before it (`XBR-1` is not `BR-1`; `TestFR004` is
+               `FR-004`, because a lower-case letter followed by the upper-case id is a
+               word boundary in camel case).
+  the tests    the slice's own test files: the `--paths` given (the OKF concept's list, plus
+               what a fix loop wrote) that are tests, inside this lane's folders. FR numbers
+               restart in every feature, so another feature's FR-001 must not count. When
+               the list holds no test file, every test file under the lane's test path is
+               searched instead and `scoped` is false.
+A master plan stamped `origin: reverse-engineered` is ADVISORY: an adopted slice's legacy
+tests predate the spec ids, so its gaps are reported and `ok` stays true. An id the plan
+still traces but spec.md / domain-model.md no longer defines (`--spec` / `--model`; a change
+removed it and the master plan is not re-derived yet) is `stale`, not required. A plan the
+mock transport wrote is skipped. Each uncited id is also returned as a finding routed to
+`fix-test-coverage`, the workflow that writes the missing tests. What this proves is that every required id has a test that
+NAMES it — not that the test asserts what the requirement says.
+
 Always exits 0 with a JSON object; the workflow decides what a gap means.
 
 Usage:
   aw-plan-coverage.py --repo R --plan P --kind backend|frontend [--mode bootstrap|delta]
-                      [--source-path S] [--test-path T] [--reported JSON]... [--list-only]
+                      [--api-plan A] [--source-path S] [--test-path T] [--reported JSON]...
+                      [--list-only]
+  aw-plan-coverage.py --repo R --plan P --kind backend|frontend --citations
+                      [--mode bootstrap|delta] [--paths JSON]... [--source-path S]
+                      [--test-path T] [--spec F] [--model F] [--known-gaps JSON]...
 """
 
 import argparse
@@ -223,6 +263,21 @@ def extract(lines, kind, mode):
     return found
 
 
+def extract_api(lines):
+    """[(route, "endpoint", False)] — the endpoint blocks of an API plan, in order.
+
+    Every `### `VERB /route`` heading under a heading that starts "Endpoints": the master's
+    "## Endpoints" and a change's "## Endpoints added or changed" alike.
+    """
+    found = []
+    for h2, _h3, what, payload in walk_sections(lines):
+        if what == "h3" and h2.lower().startswith("endpoints"):
+            name = re.sub(r"\s+", " ", first_tick(payload))
+            if name:
+                found.append((name, "endpoint", False))
+    return found
+
+
 HASH_COMMENT_EXT = {".py", ".rb", ".ex", ".exs"}
 BLOCK_COMMENT = re.compile(r"/\*.*?\*/|<!--.*?-->|@\*.*?\*@", re.S)
 LINE_COMMENT = re.compile(r"(?<![:\"'])//[^\n]*")
@@ -351,12 +406,342 @@ def load_reports(raw_list):
     return out, readable
 
 
+# ─────────────────────────────── test citations ───────────────────────────────
+
+REQUIRED_CLASSES = ("FR", "BR")
+PLAN_ID = re.compile(r"(?<![A-Za-z0-9])(FR|BR|US|UX|CN|DC|IC|SC)-(\d+)(?!\d)")
+CITE = re.compile(r"(FR|BR|US|UX|CN|DC|IC|SC)[-_]?0*(\d+)(?!\d)", re.I)
+DEFINED = re.compile(r"^\s*(?:[-*+]\s+|\|\s*|#{2,6}\s+)[*_`\s]*(FR|BR)-(\d+)(?!\d)")
+REVERSED = re.compile(r"(?i)\borigin\b[^\n]{0,12}?reverse-engineered")
+MOCK_MARK = "<!-- authored by aw-orchestrator MOCK transport -->"
+# Test-only formats: a behaviour spec is a test whatever folder it sits in.
+TEST_ONLY_EXT = {".feature", ".robot", ".story"}
+# The kit's own trees, skipped only at the repo root: a project's test folder may be called
+# `specs` too.
+KIT_DIRS = {"specs", "guardrails", "knowledge", "foundations"}
+DELTA_SECTIONS = ("ADDED", "MODIFIED", "MODEL CHANGES", "INTERACTION STATES")
+
+
+def id_key(cls, num):
+    return (cls.upper(), int(num))
+
+
+def traced_ids(lines):
+    """(section found, [(key, label)]) — the ids a master plan's Traceability section
+    traces. The FIRST cell of each row is the id column in every plan template; a section
+    whose rows carry none there is read whole instead."""
+    in2 = in3 = found = False
+    first, anywhere = [], []
+    for i, line in enumerate(lines):
+        s = line.strip()
+        if s.startswith("#"):
+            level = len(s) - len(s.lstrip("#"))
+            title = s[level:].strip().lower()
+            if level <= 2:
+                in2, in3 = "traceability" in title, False
+            elif level == 3:
+                in3 = "traceability" in title
+            found = found or in2 or in3
+            continue
+        if not (in2 or in3) or not s:
+            continue
+        if s.startswith("|"):
+            if is_separator(s):
+                continue
+            nxt = lines[i + 1].strip() if i + 1 < len(lines) else ""
+            if is_separator(nxt):
+                continue
+            cells = split_row(s)
+            first.extend(PLAN_ID.findall(cells[0] if cells else ""))
+        anywhere.extend(PLAN_ID.findall(s))
+    return found, [(id_key(c, n), "%s-%s" % (c, n)) for c, n in (first or anywhere)]
+
+
+def delta_ids(lines):
+    """(a change section found, [(key, label)]) — the ids a delta plan's ADDED, MODIFIED,
+    model-change and interaction-state rows serve. A row marked removed serves nothing the
+    code still has to prove."""
+    sec = found = False
+    out = []
+    for i, line in enumerate(lines):
+        s = line.strip()
+        if s.startswith("#"):
+            level = len(s) - len(s.lstrip("#"))
+            if level <= 2:
+                title = s[level:].strip().upper()
+                sec = title.startswith(DELTA_SECTIONS)
+                found = found or title.startswith(("ADDED", "MODIFIED"))
+            continue
+        if not sec or not s:
+            continue
+        if s.startswith("|"):
+            if is_separator(s):
+                continue
+            nxt = lines[i + 1].strip() if i + 1 < len(lines) else ""
+            if is_separator(nxt):
+                continue
+            if any(c.strip("`* ").lower() == "removed" for c in split_row(s)):
+                continue
+        out.extend(PLAN_ID.findall(s))
+    return found, [(id_key(c, n), "%s-%s" % (c, n)) for c, n in out]
+
+
+def defined_ids(path, repo):
+    """{key} an authority defines — a bullet, a table row or a heading that opens with the
+    id. Empty when the file is absent or defines none in that form, which turns the stale
+    filter off rather than declaring every traced id stale."""
+    if not path:
+        return set()
+    full = path if os.path.isabs(path) else os.path.join(repo, path)
+    if not os.path.isfile(full):
+        return set()
+    return {id_key(m.group(1), m.group(2))
+            for line in read_plan(full) for m in [DEFINED.match(line)] if m}
+
+
+def parse_list(raw_list):
+    """Every path the caller passed, flattened: JSON lists, comma-separated strings, or the
+    engine's rendering of an unset variable."""
+    out = []
+    for raw in raw_list or []:
+        got = parse_generated(raw)
+        out.extend(got or [])
+    return out
+
+
+def under(rel, prefixes):
+    return not prefixes or any(p == "" or (rel + "/").startswith(p) for p in prefixes)
+
+
+def is_test(rel, test_prefix, source_prefix):
+    ext = os.path.splitext(rel)[1].lower()
+    if ext in TEST_ONLY_EXT:
+        return True
+    if ext not in CODE_EXT:
+        return False
+    if test_prefix and test_prefix != source_prefix and (rel + "/").startswith(test_prefix):
+        return True
+    return is_test_file(rel)
+
+
+def lane_test_files(repo, base, test_prefix, source_prefix):
+    """Every test file under one lane folder — the fallback when the slice's own list
+    names none."""
+    out = []
+    top = os.path.join(repo, base.rstrip("/")) if base else repo
+    if not os.path.isdir(top):
+        return out
+    for dirpath, dirnames, filenames in os.walk(top):
+        at_root = os.path.abspath(dirpath) == os.path.abspath(repo)
+        dirnames[:] = [d for d in dirnames
+                       if not (d in SKIP_DIRS - KIT_DIRS or d.startswith(".")
+                               or (at_root and d in KIT_DIRS))]
+        for fn in filenames:
+            rel = os.path.relpath(os.path.join(dirpath, fn), repo).replace("\\", "/")
+            if is_test(rel, test_prefix, source_prefix):
+                out.append(rel)
+                if len(out) >= MAX_FILES:
+                    return out
+    return out
+
+
+def citations(repo, files):
+    """{key: first file citing it} over the given test files. A letter right before the id
+    rules a match out — that is what keeps `XBR-1` from reading as `BR-1` — except a
+    lower-case letter before an upper-case id, the camel-case word boundary of
+    `TestFR004`."""
+    found = {}
+    for rel in files:
+        full = os.path.join(repo, rel)
+        try:
+            if os.path.getsize(full) > MAX_BYTES:
+                continue
+            text = open(full, encoding="utf-8", errors="ignore").read()
+        except OSError:
+            continue
+        for m in CITE.finditer(text):
+            st = m.start()
+            prev = text[st - 1] if st else ""
+            if prev.isalpha() and not (prev.islower() and m.group(0)[0].isupper()):
+                continue
+            found.setdefault(id_key(m.group(1), m.group(2)), rel)
+    return found
+
+
+def known_test_refs(raw_list, kind):
+    """{key} a gate's own findings already report as untested for this lane, so the same
+    gap is not reported twice."""
+    refs = set()
+    for raw in raw_list or []:
+        raw = (raw or "").strip()
+        if raw in ("", "[]", "None", "null"):
+            continue
+        try:
+            data = json.loads(raw)
+        except ValueError:
+            continue
+        if isinstance(data, dict):
+            data = data.get("gaps") or []
+        for g in data if isinstance(data, list) else []:
+            if not isinstance(g, dict) or str(g.get("check", "")).lower() != "test":
+                continue
+            if g.get("lane") and str(g.get("lane")).lower() != kind:
+                continue
+            m = PLAN_ID.search(str(g.get("ref", "")).upper())
+            if m:
+                refs.add(id_key(m.group(1), m.group(2)))
+    return refs
+
+
+def cmd_citations(args, repo, plan):
+    kind, mode = args.kind, args.mode if args.mode in ("bootstrap", "delta") else "bootstrap"
+    lane = "%s lane" % kind
+    # Messages name the plan from the repo root, however the caller spelled it.
+    try:
+        shown = os.path.relpath(plan, repo).replace("\\", "/")
+    except ValueError:      # another drive on Windows
+        shown = ".."
+    if shown.startswith(".."):
+        shown = args.plan
+    src, tst = norm_path(args.source_path), norm_path(args.test_path)
+    base = {"plan": args.plan, "kind": kind, "mode": mode, "source_path": args.source_path,
+            "test_path": args.test_path, "required": [], "required_count": 0, "cited": [],
+            "uncited": [], "uncited_count": 0, "uncited_csv": "", "uncited_text": "none",
+            "other_uncited": [], "other_uncited_csv": "", "stale": [], "findings": [],
+            "test_files": [], "tests_scanned": 0, "scoped": True, "advisory": False,
+            "origin": "", "checked": False, "readable": True}
+
+    def done(ok, clean, outcome, warning, message):
+        base.update({"ok": ok, "all_cited": not base["uncited"], "clean": clean,
+                     "outcome": outcome, "warning": warning, "message": message})
+        emit(base)
+
+    if not os.path.isfile(plan):
+        done(True, False, "no-plan",
+             "WARNING — %s: the plan %s does not exist, so which requirements have a test "
+             "was not checked." % (lane, shown), "the plan %s does not exist" % shown)
+        return
+    raw = open(plan, encoding="utf-8", errors="ignore").read()
+    if MOCK_MARK in raw:
+        done(True, True, "mock", "", "the plan was written by the mock transport — not checked")
+        return
+    lines = read_plan(plan)
+    reversed_plan = mode == "bootstrap" and bool(REVERSED.search("\n".join(lines)))
+    base.update({"origin": "reverse-engineered" if reversed_plan else "",
+                 "advisory": reversed_plan})
+    found, ids = (delta_ids if mode == "delta" else traced_ids)(lines)
+    where = ("the ADDED / MODIFIED rows" if mode == "delta" else "the Traceability section")
+    if not found or (mode == "bootstrap" and not ids):
+        base["readable"] = False
+        done(True, False, "unreadable",
+             "WARNING — %s: no requirement id could be read from %s of %s, so which "
+             "requirements have a test was not checked. %s" % (
+                 lane, where, shown,
+                 "A delta plan carries `## ADDED` / `## MODIFIED` tables whose rows cite the "
+                 "ids they serve." if mode == "delta" else
+                 "A master plan carries a `## … Traceability` heading over a table whose "
+                 "first column holds the ids."),
+             "no requirement id readable from %s" % where)
+        return
+
+    labels, order = {}, []
+    for key, label in ids:
+        if key not in labels:
+            labels[key] = label
+            order.append(key)
+
+    stale = []
+    if mode == "bootstrap":
+        spec_ids = defined_ids(args.spec, repo)
+        model_ids = defined_ids(args.model, repo) | spec_ids
+        authority = {"FR": {k for k in spec_ids if k[0] == "FR"},
+                     "BR": {k for k in model_ids if k[0] == "BR"}}
+        for key in order:
+            known = authority.get(key[0])
+            if known and key not in known:
+                stale.append(key)
+
+    files, lane_dirs = [], [x for x in (src, tst) if x]
+    for p in parse_list(args.paths):
+        try:
+            rel = (os.path.relpath(p, repo) if os.path.isabs(p) else p).replace("\\", "/")
+        except ValueError:  # another drive on Windows: not in this repo
+            continue
+        while rel.startswith("./"):
+            rel = rel[2:]
+        if (rel not in files and under(rel, lane_dirs) and is_test(rel, tst, src)
+                and os.path.isfile(os.path.join(repo, rel))):
+            files.append(rel)
+    scoped = bool(files)
+    if not files:
+        folder = tst or src
+        files = lane_test_files(repo, folder, tst, src)
+    cited = citations(repo, files)
+
+    required = [k for k in order if k[0] in REQUIRED_CLASSES and k not in stale]
+    uncited = [k for k in required if k not in cited]
+    other = [k for k in order if k[0] not in REQUIRED_CLASSES and k not in cited]
+    skip = known_test_refs(args.known_gaps, kind)
+    advisory = base["advisory"]
+    findings = [] if advisory else [
+        {"severity": "high", "check": "test", "lane": kind, "ref": labels[k],
+         "where": "absent",
+         "gap": "no test of this slice names %s — a requirement whose test was never "
+                "written leaves the suite green" % labels[k],
+         "fix": "fix-test-coverage"}
+        for k in uncited if k not in skip]
+    show = lambda keys: [labels[k] for k in keys]
+    base.update({"checked": True, "required": show(required), "required_count": len(required),
+                 "cited": show([k for k in required if k in cited]),
+                 "uncited": show(uncited), "uncited_count": len(uncited),
+                 "uncited_csv": ", ".join(show(uncited)),
+                 "uncited_text": ", ".join(show(uncited)) or "none",
+                 "other_uncited": show(other), "other_uncited_csv": ", ".join(show(other)),
+                 "stale": show(stale), "findings": findings,
+                 "test_files": files[:25], "tests_scanned": len(files), "scoped": scoped})
+
+    scope_note = "" if scoped else (
+        " This feature's file list names no test file, so every test file under %s was "
+        "searched — a test of another feature that names the same id counts too."
+        % ((tst or src) or "the repository"))
+    if not uncited:
+        done(True, True, "traced", "",
+             "every one of the %d required id(s) in %s is named by a test (%d test file(s) "
+             "read)%s" % (len(required), where, len(files), scope_note))
+        return
+    ids_text = ", ".join(show(uncited))
+    if advisory:
+        done(True, False, "advisory",
+             "NOTE — %s: %s, traced by the reverse-engineered plan %s, %s no test that names "
+             "%s. Reported, not blocking: an adopted slice's legacy tests predate the spec "
+             "ids. /appweaver fix-test-coverage writes the tests or names the ids in the "
+             "ones that cover them.%s" % (
+                 lane, ids_text, shown, "has" if len(uncited) == 1 else "have",
+                 "it" if len(uncited) == 1 else "them", scope_note),
+             "%d required id(s) uncited (advisory)" % len(uncited))
+        return
+    done(False, False, "uncited",
+         "WARNING — %s: %s, from %s of %s, %s no test that names %s. Write %s, or name the "
+         "id in the test that already exercises it — `%s`, `%s` or `%s` in its name, a "
+         "comment, an attribute or a tag; /appweaver fix-test-coverage%s does either.%s" % (
+             lane, ids_text, where, shown, "has" if len(uncited) == 1 else "have",
+             "it" if len(uncited) == 1 else "them",
+             "its test" if len(uncited) == 1 else "a test for each", labels[uncited[0]],
+             labels[uncited[0]].replace("-", "_"), labels[uncited[0]].replace("-", ""),
+             " <CR-id>" if mode == "delta" else "", scope_note),
+         "%d of %d required id(s) named by no test: %s" % (len(uncited), len(required), ids_text))
+
+
 def main():
     ap = argparse.ArgumentParser(description="plan element coverage of a lane's code")
     ap.add_argument("--repo", default=".")
     ap.add_argument("--plan", required=True)
     ap.add_argument("--kind", choices=["backend", "frontend"], required=True)
     ap.add_argument("--mode", default="", help="bootstrap | delta (default: read the plan)")
+    ap.add_argument("--api-plan", dest="api_plan", default="",
+                    help="backend: the API plan the plan realises (api-plan.md, or a change's "
+                         "delta-api-plan.md); its endpoint blocks are elements too. Ignored "
+                         "when the file does not exist.")
     ap.add_argument("--source-path", default="")
     ap.add_argument("--test-path", default="")
     ap.add_argument("--reported", action="append", default=[])
@@ -368,12 +753,27 @@ def main():
                     help="comma-separated names the lane's stack already defines in ambient "
                          "scope. Element names matching one are reported as collisions.")
     ap.add_argument("--list-only", action="store_true")
+    ap.add_argument("--citations", action="store_true",
+                    help="report the plan's FR-/BR- ids that no test of the slice names")
+    ap.add_argument("--paths", action="append", default=[],
+                    help="--citations: the slice's files (a JSON list); the tests among them "
+                         "inside this lane's folders are searched")
+    ap.add_argument("--spec", default="",
+                    help="--citations: spec.md — an FR- it no longer defines is stale")
+    ap.add_argument("--model", default="",
+                    help="--citations: domain-model.md — a BR- it no longer defines is stale")
+    ap.add_argument("--known-gaps", dest="known_gaps", action="append", default=[],
+                    help="--citations: a gate's findings; an id already reported there as "
+                         "untested is not reported again")
     args = ap.parse_args()
 
     repo = os.path.abspath(args.repo)
     plan = args.plan if os.path.isabs(args.plan) else os.path.join(repo, args.plan)
-    base = {"plan": args.plan, "kind": args.kind, "source_path": args.source_path,
-            "test_path": args.test_path}
+    if args.citations:
+        cmd_citations(args, repo, plan)
+        return
+    base = {"plan": args.plan, "kind": args.kind, "api_plan": args.api_plan,
+            "source_path": args.source_path, "test_path": args.test_path}
 
     if not os.path.isfile(plan):
         base.update({"ok": False, "outcome": "no-plan",
@@ -390,6 +790,15 @@ def main():
     mode = args.mode if args.mode in ("bootstrap", "delta") else (
         "delta" if any(l.strip().upper().startswith("## ADDED") for l in lines) else "bootstrap")
     elements = extract(lines, args.kind, mode)
+    api = args.api_plan
+    if api and not os.path.isabs(api):
+        api = os.path.join(repo, api)
+    if args.kind == "backend" and api and os.path.isfile(api):
+        seen = {n for n, _, _ in elements}
+        for element in extract_api(read_plan(api)):
+            if element[0] not in seen and not placeholder(element[0]):
+                seen.add(element[0])
+                elements.append(element)
     names = [n for n, _, _ in elements]
     # NAMES THE STACK ALREADY DEFINES. A plan element called `Route` or `Task` is not a
     # naming mistake — the plan carries the ubiquitous language and the generator spells it

package/assets/.appweaver/scripts/python/aw-plangate.py

@@ -17,7 +17,8 @@ and kept in step by eye. One module both shells invoke removes the question: the
 nothing left to keep in step. Same reason aw-crstate.py owns "has this change merged".
 
 ONE RECEIPT PER LANE. With --lane, the receipt is `.aw-plan-gate.<lane>.json` and it
-hashes the spec, the model and THAT lane's plan only, with that lane's verdict. A backend
+hashes the spec, the model and THAT lane's documents only — the backend's are its plan and
+the API plan beside it — with that lane's verdict. A backend
 developer and a frontend developer gate their own plans at different times, so a frontend
 plan edited, or left with gaps, never refuses the backend's implement, and the reverse.
 A feature gated before the per-lane receipts existed still has the shared
@@ -26,14 +27,14 @@ names in it, so the other lane's document moving does not read as this lane's dr
 Without --lane both commands keep the shared receipt.
 
 THE FRONTEND RECEIPT ALSO HASHES THE BACKEND'S PUBLISHED SURFACE. A frontend plan binds to
-the operations the backend plan's API section publishes, and the backend developer can
-change that section after the frontend was gated — rename an operation, change a field,
-answer a contract request. So the frontend receipt records `surface_sha`, the hash of that
-section (aw-stack's api_section; the whole backend plan when it has none, "" when there is
-no backend plan), and `check --lane frontend` reads a different surface as moved bytes. The
-backend plan's other sections are not in it: a change to the domain or infrastructure
-layers leaves the frontend receipt fresh. A receipt written before the field existed has no
-baseline for it and is not refused over it.
+the operations the API plan publishes, and the backend developer can change it after the
+frontend was gated — rename an operation, change a field, answer a contract request. So
+the frontend receipt records `surface_sha`, the hash of the API plan (for a feature planned
+before it existed, the backend plan's API section — aw-stack's api_section — or the whole
+backend plan when it has none; "" when there is neither), and `check --lane frontend` reads
+a different surface as moved bytes. The backend plan is not in it: a change to the domain
+or infrastructure layers leaves the frontend receipt fresh. A receipt written before the
+field existed has no baseline for it and is not refused over it.
 
 NO BASELINE IS NOT "NOTHING MOVED". `spec_moved` / `model_moved` report "" where there is
 nothing to compare against — no receipt, or a receipt that hashed nothing for that
@@ -73,11 +74,13 @@ VERDICTS = ("conformant", "routed-gaps", "gaps")
 # produces — is GATED on those documents. Hashing only the new names would leave such a
 # feature with an empty plan map: a receipt that looks tracked and fresh while the document
 # implement actually generates from is unwatched.
-PLAN_NAMES = ("backend-plan.md", "frontend-plan.md", "design.md", "design.ui.md")
+PLAN_NAMES = ("backend-plan.md", "frontend-plan.md", "design.md", "design.ui.md", "api-plan.md")
 
-# Each lane's plan, under its current name and its pre-lane-split one.
+# Each lane's documents: its plan, under its current name and its pre-lane-split one, and for
+# the backend lane the API plan beside it.
+API_PLAN = "api-plan.md"
 LANE_PLAN_NAMES = {
-    "backend": ("backend-plan.md", "design.md"),
+    "backend": ("backend-plan.md", "design.md", API_PLAN),
     "frontend": ("frontend-plan.md", "design.ui.md"),
 }
 
@@ -115,9 +118,13 @@ def _api_section(text):
 
 
 def surface_sha(fd):
-    """The hash of the backend plan's published surface — its API section, or the whole plan
-    when it has none; "" when the feature has no backend plan."""
-    for name in LANE_PLAN_NAMES["backend"]:
+    """The hash of the backend's published surface — the API plan; for a feature planned
+    before it existed, the backend plan's API section, or the whole plan when it has none;
+    "" when the feature has neither."""
+    api = sha(os.path.join(fd, API_PLAN))
+    if api:
+        return api
+    for name in ("backend-plan.md", "design.md"):
         path = os.path.join(fd, name)
         if os.path.isfile(path):
             with open(path, encoding="utf-8", errors="replace") as fh:
@@ -249,7 +256,7 @@ def check(fd, ctx, root, lane=""):
         if out["model_moved"]:
             bits.append("domain-model.md has changed")
         if out["surface_moved"]:
-            bits.append("the backend plan's published surface (its API section) has changed — "
+            bits.append("the backend's published surface (its API plan) has changed — "
                         "re-gate the frontend plan against it")
         if changed:
             bits.append("%s changed (a re-derive by `plan main`, or a hand edit)"