wdi-method 0.5.3 → 0.5.9

package/kit/.constitution/method/document/templates/uc.md

@@ -1,69 +1,69 @@
----
-type: uc
-id: UC-{NN}                  # allocated from .control/registry/usecases.yaml
-component: '{pc}'
-satisfies: []                # FR ids — V2 checks every FR has at least one UC
-critical: false              # true ONLY when it touches money, personal data, or an irreversible
-                             # action. Nothing else — the two elastic criteria are repealed
-created: '{YYYY-MM-DD}'
----
-
-# UC-{NN} — {a sentence the user would say}
-
-<!-- TEMPLATE GUIDE — act on these comments, then delete them.
-
-     THE TITLE RULE, and G3 asks it as a starred question: the title MUST be a sentence a user would
-     actually say — "Mendaftar lewat tautan sponsor" — and MUST NOT be a system term — "Referral
-     attribution handler". A system-shaped title means the functional analysis has already leaked
-     into design.
-
-     WHICH USE CASES GET ONE OF THESE FILES IS DECIDED BY `mode`, NOT BY `critical`:
-       catalog            none. The catalogue line in the SRS is the whole record
-       outline · guarded  the use cases the component exists for, AT MOST 3
-       deep               every UC marked `critical`
-     `critical` therefore decides something only at `deep`. Everywhere else it is a label the estimate
-     and the review read, and it MUST NOT be used to justify writing a file the mode does not ask for.
-
-     At most EIGHT steps in the Basic Flow. A flow needing more is either two use cases, or it has
-     started describing implementation. -->
-
-## Trigger
-
-<!-- What starts this. An actor doing something, a schedule, or an external event. -->
-
-## Precondition
-
-<!-- What MUST already be true. Authentication state, prior data, prior status. -->
-
-## Main Flow
-
-<!-- Numbered, one step per line, alternating actor and system. Keep to the happy path — branches
-     go below or, if long, into a SCN- file in 05-scenarios/. No screen names, no endpoints, no
-     table names: this is behaviour, not design. -->
-
-1.
-2.
-
-## Alternate Flows
-
-<!-- Branches that still end in success. Reference the main-flow step they leave from. -->
-
-| From step | Condition | What happens |
-| --- | --- | --- |
-
-## Failure Flows
-
-<!-- Branches that end without the goal. For a `critical` UC this section MUST answer "what happens
-     if it fails halfway" — the paired SDD carries the technical side of the same question. -->
-
-| From step | Failure | What the system does | What the user is left with |
-| --- | --- | --- | --- |
-
-## Outcome
-
-<!-- The state the system and the user are left in when the main flow completes. -->
-
-## Business Rules
-
-<!-- BR ids that govern this use case, referenced not restated. The rules themselves live in
-     02-rules/. -->
+---
+type: uc
+id: UC-{NN}                  # allocated from .control/registry/usecases.yaml
+component: '{pc}'
+satisfies: []                # FR ids — V2 checks every FR has at least one UC
+critical: false              # true ONLY when it touches money, personal data, or an irreversible
+                             # action. Nothing else — the two elastic criteria are repealed
+created: '{YYYY-MM-DD}'
+---
+
+# UC-{NN} — {a sentence the user would say}
+
+<!-- TEMPLATE GUIDE — act on these comments, then delete them.
+
+     THE TITLE RULE, and G3 asks it as a starred question: the title MUST be a sentence a user would
+     actually say — "Sign up through an invitation link" — and MUST NOT be a system term —
+     "Invitation attribution handler". A system-shaped title means the functional analysis has already leaked
+     into design.
+
+     WHICH USE CASES GET ONE OF THESE FILES IS DECIDED BY `mode`, NOT BY `critical`:
+       catalog            none. The catalogue line in the SRS is the whole record
+       outline · guarded  the use cases the component exists for, AT MOST 3
+       deep               every UC marked `critical`
+     `critical` therefore decides something only at `deep`. Everywhere else it is a label the estimate
+     and the review read, and it MUST NOT be used to justify writing a file the mode does not ask for.
+
+     At most EIGHT steps in the Basic Flow. A flow needing more is either two use cases, or it has
+     started describing implementation. -->
+
+## Trigger
+
+<!-- What starts this. An actor doing something, a schedule, or an external event. -->
+
+## Precondition
+
+<!-- What MUST already be true. Authentication state, prior data, prior status. -->
+
+## Main Flow
+
+<!-- Numbered, one step per line, alternating actor and system. Keep to the happy path — branches
+     go below or, if long, into a SCN- file in 05-scenarios/. No screen names, no endpoints, no
+     table names: this is behaviour, not design. -->
+
+1.
+2.
+
+## Alternate Flows
+
+<!-- Branches that still end in success. Reference the main-flow step they leave from. -->
+
+| From step | Condition | What happens |
+| --- | --- | --- |
+
+## Failure Flows
+
+<!-- Branches that end without the goal. For a `critical` UC this section MUST answer "what happens
+     if it fails halfway" — the paired SDD carries the technical side of the same question. -->
+
+| From step | Failure | What the system does | What the user is left with |
+| --- | --- | --- | --- |
+
+## Outcome
+
+<!-- The state the system and the user are left in when the main flow completes. -->
+
+## Business Rules
+
+<!-- BR ids that govern this use case, referenced not restated. The rules themselves live in
+     02-rules/. -->

package/kit/.constitution/method/scripts/inventory.py

@@ -23,70 +23,36 @@ will be. This script therefore has two modes, and the first is the default:
 Determinism is the contract, same as validate.py: two runs over the same code MUST produce the
 same result. That is why every iteration is ordered and none depends on the wall clock.
 
-THE STATED-UP-FRONT LIMIT. This is a pattern reader, not a compiler. It reads:
-    table     CREATE TABLE statements in src/internal/platform/migrate/migrations/*.sql
-    endpoint  route registrations on the Gin router in src/**/*.go
-    screen    route components in the React SPA in web/*/src/**/*.tsx
-Whatever the pattern cannot read is reported as unread — NOT guessed, and NOT silently
-dropped. An inventory MUST NOT be assembled from a README or from a route name that merely
-looks plausible.
+WHERE THE STACK LIVES, AND WHY NOT HERE. Comparing, reporting, rendering, and keeping the numbers
+stable do not depend on a language. READING the code does — a migration folder, a router, a screen
+route are each written differently in every stack. So this file holds none of that. It loads three
+functions from the product:
+
+    .constitution/project/inventory-readers.py    derive_db · derive_api · derive_screen
+
+That path is the room: `wdi-method update` never overwrites it and `promote` never publishes it, so
+a product owns how its own code is read while every product shares this engine. What the package
+seeds there is a SKELETON — no patterns, no stack, and it says so. The `wdi-init` skill, intent
+`readers`, writes it against the repo actually in front of it, which is why no example ships: an
+example is a guess about somebody else's stack, and guessing is the thing this script exists to
+refuse. An unwritten reader is reported, never worked around.
+
+THE STATED-UP-FRONT LIMIT, which no stack changes: this is a pattern reader, not a compiler.
+Whatever a reader cannot read is reported as unread — NOT guessed, and NOT silently dropped. An
+inventory MUST NOT be assembled from a README or from a route name that merely looks plausible.
 """
 
 from __future__ import annotations
 
 import argparse
+import importlib.util
 import re
 import sys
 from dataclasses import dataclass, field
 from pathlib import Path
 
 KINDS = ("db", "api", "screen")
-
-# ------------------------------------------------------------------ read patterns
-
-# CREATE TABLE [IF NOT EXISTS] `name` | name
-RE_TABLE = re.compile(
-    r"CREATE\s+TABLE\s+(?:IF\s+NOT\s+EXISTS\s+)?[`\"]?([A-Za-z_][A-Za-z0-9_]*)[`\"]?",
-    re.I)
-RE_DROP_TABLE = re.compile(
-    r"DROP\s+TABLE\s+(?:IF\s+EXISTS\s+)?[`\"]?([A-Za-z_][A-Za-z0-9_]*)[`\"]?", re.I)
-# PRIMARY KEY / UNIQUE / FOREIGN KEY — key columns, not every column
-RE_KEYCOL = re.compile(
-    r"(?:PRIMARY\s+KEY|UNIQUE(?:\s+KEY)?|FOREIGN\s+KEY)[^(\n]*\(([^)]*)\)", re.I)
-
-# r.GET("/path", ...) · group.POST(`/path`, ...) · r.Handle("GET", "/path", ...)
-RE_ROUTE = re.compile(
-    r"\.\s*(GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS)\s*\(\s*[`\"]([^`\"]+)[`\"]", re.I)
-RE_GROUP = re.compile(r"\.\s*Group\s*\(\s*[`\"]([^`\"]+)[`\"]", re.I)
-
-# A route group is CREATED in one file and USED in another:
-#     portal.go:26   mountMemberAPI(engine.Group("/api"), ...)
-#     member_api.go  api.GET("/me", ...)
-# Because of that, a prefix CANNOT be inferred per file. It must follow its mount, and the host
-# comes along from the mount point in app.go. The patterns below are what make that trace possible.
-RE_FUNC_DEF = re.compile(r"^func\s+([A-Za-z_][A-Za-z0-9_]*)\s*\(([^)]*)\)", re.M)
-# mux.Handle(cfg.HostPublic, routing.NewPublicWithStore(...)) -> host `public`, entry NewPublicWithStore
-RE_HOST_MOUNT = re.compile(
-    r"Handle\s*\(\s*[A-Za-z_][A-Za-z0-9_]*\.Host([A-Za-z0-9_]+)\s*,\s*"
-    r"(?:[A-Za-z_][A-Za-z0-9_]*\.)?([A-Za-z_][A-Za-z0-9_]*)\s*\(")
-# mountX(engine.Group("/api"), ...)  |  mountX(api, ...)
-RE_CALL_GROUP = re.compile(
-    r"\b([a-z][A-Za-z0-9_]*)\s*\(\s*([A-Za-z_][A-Za-z0-9_]*)\s*\.\s*Group\s*\(\s*[`\"]([^`\"]*)[`\"]\s*\)")
-RE_CALL_PLAIN = re.compile(r"\b([a-z][A-Za-z0-9_]*)\s*\(\s*([A-Za-z_][A-Za-z0-9_]*)\s*[,)]")
-# api := engine.Group("/x")  |  protected := api.Group("")
-RE_ASSIGN_GROUP = re.compile(
-    r"^\s*([A-Za-z_][A-Za-z0-9_]*)\s*:?=\s*([A-Za-z_][A-Za-z0-9_]*)\s*\.\s*Group\s*\(\s*[`\"]([^`\"]*)[`\"]",
-    re.M)
-RE_ASSIGN_ENGINE = re.compile(r"^\s*([A-Za-z_][A-Za-z0-9_]*)\s*:?=\s*gin\.New\s*\(", re.M)
-RE_ROUTE_ON = re.compile(
-    r"\b([A-Za-z_][A-Za-z0-9_]*)\s*\.\s*(GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS)\s*\(\s*[`\"]([^`\"]+)[`\"]",
-    re.I)
-
-# <Route path="/x" element={<Thing />} /> — react-router
-RE_ROUTE_TSX = re.compile(
-    r"<Route\s[^>]*path\s*=\s*[{\"']+([^\"'}]+)[\"'}]+[^>]*?"
-    r"element\s*=\s*\{\s*<\s*([A-Za-z0-9_]+)", re.S)
-
+READERS = Path(".constitution") / "project" / "inventory-readers.py"
 
 @dataclass
 class Row:
@@ -108,245 +74,6 @@ def read(path: Path) -> str:
         return ""
 
 
-RE_DOWN = re.compile(r"^\s*--\s*\+(?:goose|migrate)\s+Down\b", re.I | re.M)
-
-
-def up_section(text: str) -> str:
-    """Only a migration's Up section.
-
-    The Down section holds a DROP TABLE for every table its Up creates, so reading the whole
-    file makes every table read as dropped. This split MUST happen BEFORE comments are
-    stripped, because the goose marker itself is a comment.
-    """
-    match = RE_DOWN.search(text)
-    return text[:match.start()] if match else text
-
-
-def strip_sql_comments(text: str) -> str:
-    text = re.sub(r"/\*.*?\*/", " ", text, flags=re.S)
-    return "\n".join(re.sub(r"(--|#).*$", "", line) for line in text.splitlines())
-
-
-# --------------------------------------------------------------------- table
-
-
-def table_owner(root: Path) -> dict[str, str]:
-    """Every table's owner, read from `owns` and `platform_owns` in components.yaml.
-
-    The owner column CAN be derived as soon as an `owns` value is set, so writing it as
-    [NEEDS CONFIRMATION] would flag as unknown something the registry has already stated.
-    Whatever no one claims stays [NEEDS CONFIRMATION] — that is a finding, not a gap in the rule.
-    """
-    import yaml as _yaml
-    path = root / ".control/registry/components.yaml"
-    if not path.exists():
-        return {}
-    data = _yaml.safe_load(path.read_text(encoding="utf-8")) or {}
-    out: dict[str, str] = {}
-    for pc in (data.get("product_components") or []):
-        for entity in (pc.get("owns") or []):
-            out[str(entity)] = str(pc.get("id"))
-    for entity in (data.get("platform_owns") or []):
-        out.setdefault(str(entity), "_platform")
-    return out
-
-
-def derive_db(root: Path) -> Derived:
-    out = Derived()
-    owner = table_owner(root)
-    folder = root / "src/internal/platform/migrate/migrations"
-    if not folder.is_dir():
-        out.unread.append(f"{folder.as_posix()} does not exist — no migration can be read")
-        return out
-
-    created: dict[str, tuple[str, str]] = {}   # table -> (key columns, file)
-    dropped: set[str] = set()
-    for path in sorted(folder.glob("*.sql")):
-        body = strip_sql_comments(up_section(read(path)))
-        rel = path.relative_to(root).as_posix()
-        for stmt in body.split(";"):
-            match = RE_TABLE.search(stmt)
-            if match:
-                name = match.group(1)
-                keys = sorted({c.strip().strip("`\"") for group in RE_KEYCOL.findall(stmt)
-                               for c in group.split(",") if c.strip()})
-                created[name] = (", ".join(f"`{k}`" for k in keys) or "—", rel)
-                continue
-            for name in RE_DROP_TABLE.findall(stmt):
-                dropped.add(name)
-
-    for name in sorted(created):
-        if name in dropped:
-            continue
-        keys, rel = created[name]
-        who = owner.get(name)
-        out.rows.append(Row(key=name, source=rel,
-                            cells=[f"`{name}`",
-                                   f"`{who}`" if who else "[NEEDS CONFIRMATION]",
-                                   "[NEEDS CONFIRMATION]", keys, "published"]))
-        if not who:
-            out.unread.append(f"table `{name}` is claimed by neither `owns` nor `platform_owns` — "
-                              f"V21 does not see it, and no one is authorized to write it")
-    if dropped:
-        out.unread.append("tables dropped in the Up section and therefore not registered: "
-                          + ", ".join(sorted(dropped)))
-    return out
-
-
-# ------------------------------------------------------------------ endpoint
-
-
-def _go_funcs(root: Path) -> tuple[dict[str, str], list[str]]:
-    """Every Go function in src/ with its body, plus the list of files read."""
-    bodies: dict[str, str] = {}
-    files: list[str] = []
-    for path in sorted((root / "src").rglob("*.go")):
-        if path.name.endswith("_test.go"):
-            continue
-        body = read(path)
-        files.append(body)
-        marks = [(m.start(), m.group(1), m.group(2)) for m in RE_FUNC_DEF.finditer(body)]
-        for i, (start, name, params) in enumerate(marks):
-            end = marks[i + 1][0] if i + 1 < len(marks) else len(body)
-            bodies[name] = body[start:end]
-            bodies[name + "\x00params"] = params
-    return bodies, files
-
-
-def _walk(fn: str, host: str, prefix: str, router_vars: dict[str, str],
-          bodies: dict[str, str], out: dict[tuple[str, str, str], str],
-          seen_calls: set[tuple[str, str, str]], depth: int = 0) -> None:
-    """Walk one function: record its routes, then follow the mounts it sets up.
-
-    A function MAY be mounted from more than one host — `mountSharedPublicReads` is called from
-    `member_api.go` AND `public_api.go` — so this recursion deliberately does not memoize per
-    function, only per (function, host, prefix). Without that, the endpoints on the second host
-    disappear without a trace.
-    """
-    if depth > 8 or (fn, host, prefix) in seen_calls:
-        return
-    seen_calls.add((fn, host, prefix))
-    body = bodies.get(fn)
-    if body is None:
-        return
-
-    local = dict(router_vars)
-    params = bodies.get(fn + "\x00params", "")
-    for piece in params.split(","):
-        piece = piece.strip()
-        if "gin.RouterGroup" in piece or "gin.Engine" in piece:
-            local[piece.split()[0]] = prefix
-    for m in RE_ASSIGN_ENGINE.finditer(body):
-        local[m.group(1)] = prefix
-    for m in RE_ASSIGN_GROUP.finditer(body):
-        base = local.get(m.group(2))
-        if base is not None:
-            local[m.group(1)] = (base + m.group(3)).rstrip("/")
-
-    for var, method, raw in RE_ROUTE_ON.findall(body):
-        if not raw.startswith("/") or var not in local:
-            continue
-        full = (local[var] + raw).replace("//", "/")
-        out.setdefault((host, method.upper(), full), fn)
-
-    for callee, var, grp in RE_CALL_GROUP.findall(body):
-        if var in local and callee in bodies:
-            _walk(callee, host, (local[var] + grp).rstrip("/"), {}, bodies, out, seen_calls, depth + 1)
-    for callee, var in RE_CALL_PLAIN.findall(body):
-        if var in local and callee in bodies:
-            _walk(callee, host, local[var], {}, bodies, out, seen_calls, depth + 1)
-
-
-def derive_api(root: Path) -> Derived:
-    out = Derived()
-    if not (root / "src").is_dir():
-        out.unread.append("src/ does not exist — no route registration can be read")
-        return out
-
-    bodies, files = _go_funcs(root)
-    entries: list[tuple[str, str]] = []
-    for body in files:
-        for host, fn in RE_HOST_MOUNT.findall(body):
-            entries.append((host.lower(), fn))
-    if not entries:
-        out.unread.append(
-            "not one host mount point was read (pattern `Handle(cfg.Host<X>, <Fn>(`) — "
-            "every path below MUST be checked by hand, since a group's prefix cannot be "
-            "traced without its mount point")
-
-    found: dict[tuple[str, str, str], str] = {}
-    for host, fn in sorted(set(entries)):
-        _walk(fn, host, "", {}, bodies, found, set())
-
-    _, plat = decisions(root / ".how/_platform/inventory-api.md")
-    for (host, method, path_str) in sorted(found):
-        key = f"{host} {method} {path_str}"
-        owner = "`_platform`" if (key in plat or f"{method} {path_str}" in plat
-                                 or path_str in plat) else "[NEEDS CONFIRMATION]"
-        out.rows.append(Row(key=key, source=found[(host, method, path_str)],
-                            cells=[host, method, f"`{path_str}`", owner,
-                                   "[NEEDS CONFIRMATION]", "published"]))
-    if not found:
-        out.unread.append("not one route registration was read in src/**/*.go — "
-                          "if the API genuinely does not exist yet, `derived_from: plan` is correct")
-    return out
-
-
-def derive_screen(root: Path) -> Derived:
-    out = Derived()
-    folder = root / "web"
-    if not folder.is_dir():
-        out.unread.append("web/ does not exist — no page can be read")
-        return out
-
-    # THE KEY IS (spa, route), NOT the route alone. This product has two SPAs built separately,
-    # and both declare `/`, `/login`, and `*`. Keying on the route alone silently collapses the
-    # duplicates: 26 screens read as 23. A route is not a screen's identity in a product with
-    # multiple SPAs — the host is part of that identity.
-    seen: dict[tuple[str, str], tuple[str, str]] = {}
-    for path in sorted(folder.rglob("*.tsx")):
-        if "node_modules" in path.parts or path.name.endswith(".test.tsx"):
-            continue
-        rel = path.relative_to(root).as_posix()
-        parts = path.relative_to(folder).parts
-        spa = parts[0] if parts else "?"
-        for route, component in RE_ROUTE_TSX.findall(read(path)):
-            seen.setdefault((spa, route.strip()), (component, rel))
-
-    states, _ = decisions(root / ".how/_platform/inventory-screen.md")
-    folded: dict[str, list[str]] = {}
-    for (spa, route) in sorted(seen):
-        parent = states.get(route)
-        if parent:
-            folded.setdefault(f"{spa}:{parent}", []).append(route)
-
-    for spa, route in sorted(seen):
-        if route in states:
-            continue  # it is a state of another screen, not a row of its own
-        component, rel = seen[(spa, route)]
-        extra = folded.get(f"{spa}:{route}") or []
-        state_cell = ", ".join(f"`{r}`" for r in sorted(extra)) if extra else "—"
-        out.rows.append(Row(key=f"{spa}:{route}", source=rel,
-                            cells=[f"`{spa}/{component}`", f"`{route}`", state_cell,
-                                   "[NEEDS CONFIRMATION]", "[NEEDS CONFIRMATION]"]))
-
-    orphan = sorted(r for r in states
-                    if not any(states[r] == route for _, route in seen))
-    if orphan:
-        out.unread.append("state-routes whose parent was not read in the code: " + ", ".join(orphan))
-    if not seen:
-        out.unread.append("not one <Route path=... element={<X />}> was read in web/**/*.tsx")
-    else:
-        shared = sorted({r for _, r in seen} & {r for s, r in seen if s != sorted({x for x, _ in seen})[0]})
-        dupes = sorted({r for s, r in seen} )
-        collide = sorted({r for r in dupes if sum(1 for s2, r2 in seen if r2 == r) > 1})
-        if collide:
-            out.unread.append("routes declared by MORE THAN ONE SPA, and therefore not a "
-                              "screen's identity on their own: " + ", ".join(collide))
-    return out
-
-
-DERIVERS = {"db": derive_db, "api": derive_api, "screen": derive_screen}
 HEADERS = {
     "db": ("No", "Table", "Owning component", "What it holds", "Key columns", "Status"),
     "api": ("No", "Host", "Method", "Path", "Owning component", "Description", "Status"),
@@ -460,6 +187,70 @@ def write_rows(path: Path, block: str) -> None:
     path.write_text(head + "## Rows\n\n" + block + "\n" + tail, encoding="utf-8")
 
 
+# ------------------------------------------------------------- the product's readers
+
+
+def load_readers(root: Path):
+    """Load the product's three readers, or return None if it has not written them.
+
+    Three names are injected BEFORE the module executes, so a reader neither imports them nor
+    redeclares them: one definition, and it is this file's. That also means a reader written against
+    an older shape fails loudly at import rather than silently producing rows the engine then
+    mis-renders.
+
+        Row · Derived    the shape every reader returns
+        decisions        an inventory's own `platform_rows:` and `states:`. Those are a judgement
+                         the pattern cannot derive, declared in the artifact they govern, so every
+                         reader needs them and none should re-implement reading them
+
+    Nothing else is offered. A reader needing more of the engine is a sign the seam is in the wrong
+    place, and moving the seam is the fix — not reaching through it.
+    """
+    file = root / READERS
+    if not file.exists():
+        return None
+    spec = importlib.util.spec_from_file_location("wdi_inventory_readers", file)
+    if spec is None or spec.loader is None:
+        raise SystemExit(f"inventory: {READERS.as_posix()} could not be loaded as Python")
+    mod = importlib.util.module_from_spec(spec)
+    mod.Row, mod.Derived, mod.decisions = Row, Derived, decisions
+    spec.loader.exec_module(mod)
+    missing = [f"derive_{k}" for k in KINDS if not callable(getattr(mod, f"derive_{k}", None))]
+    if missing:
+        raise SystemExit(f"inventory: {READERS.as_posix()} defines no {', '.join(missing)} — "
+                         f"the engine expects one function per kind, each taking the repo root")
+    return mod
+
+
+def is_skeleton(mod) -> bool:
+    """The seeded skeleton announces itself, because silence would be a lie.
+
+    A skeleton returns no rows, and so does a product that genuinely stores no tables. In the
+    output those are the same thing — "0 rows read from code" — and only one of them is true. The
+    flag is what keeps an unwritten reader from reading as a finished one.
+    """
+    return bool(getattr(mod, "SKELETON", False))
+
+
+def shaped(kind: str, result) -> Derived:
+    """Refuse a reader's answer that is not the shape the engine renders.
+
+    A reader is the product's code, so it is the one part of this run the method did not write.
+    Checking its shape here turns a wrong return into one clear sentence, rather than a
+    TypeError thrown from inside render_rows with no clue whose fault it was.
+    """
+    rows = getattr(result, "rows", None)
+    unread = getattr(result, "unread", None)
+    if not isinstance(rows, list) or not isinstance(unread, list):
+        raise SystemExit(f"inventory: derive_{kind} returned {type(result).__name__}, "
+                         f"which carries no `rows` and `unread` lists")
+    for row in rows:
+        if not all(hasattr(row, attr) for attr in ("key", "cells", "source")):
+            raise SystemExit(f"inventory: derive_{kind} returned a row without key, cells, "
+                             f"and source — see the contract in {READERS.as_posix()}")
+    return result
+
+
 # ----------------------------------------------------------------------- CLI
 
 
@@ -481,13 +272,28 @@ def main(argv: list[str] | None = None) -> int:
         print(f"inventory: {root} has no .control/registry/ — wrong repo root?", file=sys.stderr)
         return 2
 
+    readers = load_readers(root)
+    # NOT an error, and NOT a reason to guess. A product that has not written its readers has said
+    # nothing about how its code is read, and inventing an answer here is the one failure this
+    # script exists to prevent. Both states get the same refusal and the same next step.
+    if readers is None or is_skeleton(readers):
+        state = ("has no" if readers is None else "still has the seeded skeleton at")
+        print(f"inventory: this product {state} {READERS.as_posix()}, so nothing can be derived "
+              f"from code.\n"
+              f"  The engine is generic; reading a stack is not. Write the three readers for this "
+              f"repo with\n"
+              f"  the `wdi-init` skill, intent `readers` — it reads the code in front of it rather "
+              f"than\n"
+              f"  starting from somebody else's stack.", file=sys.stderr)
+        return 2
+
     kinds = args.kind or list(KINDS)
     findings = 0
 
     for kind in kinds:
         path = root / f".how/_platform/inventory-{kind}.md"
         rel = path.relative_to(root).as_posix()
-        derived = DERIVERS[kind](root)
+        derived = shaped(kind, getattr(readers, f"derive_{kind}")(root))
         recorded, mode = plan_rows(path)
         keys = plan_keys(kind, recorded)