aw-spec-cli 0.1.8 → 0.1.9

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

@@ -0,0 +1,1251 @@
+#!/usr/bin/env python3
+"""
+aw-stack — the lane model's deterministic core.
+
+Backs seven aw-spec-actions subcommands, called identically by the bash and the
+powershell twin so the two stay in parity by construction rather than by review:
+
+    list      enumerate .appweaver/stack-profiles/ — the candidate list
+    detect    match the repo's own files against those profiles — the BROWNFIELD
+              candidate list, since an existing repo already answered the question
+    declare   upsert a lane into .appweaver/stacks.json — THE SOLE WRITER
+    resolve   read .appweaver/stacks.json — for every downstream reader
+    verify    is the declaration USABLE for the phase about to run — the gate
+    run-phase run a phase's command for EVERY declared lane, not just the first
+    probe     is there evidence of a lane of this kind — read-only, never fatal
+
+`declare` is the sole writer and has exactly one caller — `select-stack`, where a
+person picks — so the rule is a grep rather than a convention. The `origin` key
+stays optional in the schema for a future caller that proposes a lane without a
+person in the loop; a reader that branches on it keeps working either way.
+
+A person editing stacks.json in a text editor is the other way a lane arrives,
+and it is supported: the kit ships the file holding `{"lanes": []}` for exactly
+that. It is the one path that does not pass the writer's checks, which is why
+`verify` re-checks the roots-disjoint invariant rather than trusting that
+`declare` already did. `resolve` can never write, which is why these are two
+subcommands and not one with a mode flag.
+
+A lane's `root` IS its source path — the subtree the lane owns and the only place
+its implement phase may write. The two words name one field, and `--source-path`
+is accepted wherever `--root` is.
+
+WHERE THE COMMANDS RUN is a separate question, because for most stacks the answer
+is a different directory: `dotnet build` wants the solution file at the top while
+the lane owns `src/`, and `npm run build` wants the package.json at the top while
+the lane owns `web/`. `run_from` carries that answer — "repo" (the default, and
+the shape of every lane written before the key existed) or "root". A stack whose
+manifest lives INSIDE its subtree needs "root" and cannot work without it: a Maven
+wrapper at backend/<app>/mvnw is unreachable from the repository root.
+
+WHERE THE PATH IS CHECKED AGAINST THE DISK. `declare` records a path; it does not
+require the path to exist, because in a greenfield project it does not exist yet —
+the whole point of declaring `src/` on day one is that `implement` will create it.
+`verify` is the check, and it runs where the path has to be real: before implement,
+build, run, and before onboard reverse-engineers a codebase out of it. That split
+is what lets one file serve a project that has no code yet and a project that is
+nothing but code.
+
+Stdlib only. Emits one line of compact JSON on stdout.
+"""
+
+import argparse
+import fnmatch
+import glob
+import json
+import os
+import re
+import sys
+
+STACKS_REL = ".appweaver/stacks.json"
+PROFILES_REL = ".appweaver/stack-profiles"
+
+# A lane id names the ROLE in the project; the profile names the technology.
+# Keeping them separate is what lets a project re-stack a lane without renaming
+# the paths, rules and constitution half that hang off the lane id.
+DEFAULT_LANE_ID = {"backend": "service", "frontend": "web"}
+
+# "(none)" is a real answer for EITHER kind: a backend-only project declines the UI
+# lane, and a UI-only project declines the service lane. Both are projects the kit
+# has to be able to govern, and the sentinel reads as the answer to the question
+# that was actually asked. The leading "(none)" token is what `declare` matches on,
+# so the trailing prose is free to differ by kind.
+NONE_SENTINEL = "(none) — no lane of this kind"
+NONE_SENTINEL_BY_KIND = {
+    "backend": "(none) — no service lane, UI-only project",
+    "frontend": "(none) — no UI lane, backend-only project",
+}
+
+
+def none_sentinel(kind):
+    return NONE_SENTINEL_BY_KIND.get(kind or "", NONE_SENTINEL)
+
+
+def emit(obj):
+    sys.stdout.write(json.dumps(obj, separators=(",", ":")) + "\n")
+
+
+def fail(msg):
+    sys.stderr.write(msg + "\n")
+    sys.exit(1)
+
+
+# ─────────────────────────────── profiles ──────────────────────────────────
+
+def load_profiles(repo, kind=None):
+    base = os.path.join(repo, PROFILES_REL)
+    out = []
+    for path in sorted(glob.glob(os.path.join(base, "*.json"))):
+        try:
+            with open(path, "r", encoding="utf-8") as fh:
+                prof = json.load(fh)
+        except (ValueError, OSError):
+            continue                      # a malformed profile is skipped, never fatal
+        if not prof.get("id") or not prof.get("kind"):
+            continue
+        if kind and kind != "all" and prof.get("kind") != kind:
+            continue
+        out.append(prof)
+    return out
+
+
+def option_label(prof):
+    lang = prof.get("language", "")
+    suffix = " (%s)" % lang if lang else ""
+    return "%s — %s%s" % (prof["id"], prof.get("title", prof["id"]), suffix)
+
+
+def profile_id_from_label(label):
+    """Options are '<id> — <title> (<lang>)'; the id is the leading token.
+
+    Accepts a bare id too, so --profile works with a direct argument and with a
+    selection relayed back from the launcher.
+    """
+    return (label or "").strip().split()[0] if (label or "").strip() else ""
+
+
+def resolve_preselect(text, profiles, include_none, kind=None):
+    """Match a direct argument against THIS kind's profiles only.
+
+    select-stack asks twice, so one argument would be ambiguous — except that a
+    profile id belongs to exactly one kind. Each list matches the token it owns
+    and ignores the rest, which makes `select-stack dotnet-webapi react-vite`
+    answer both selects and `select-stack react-vite` answer only the UI one.
+    """
+    tokens = [t.strip().lower() for t in (text or "").replace(",", " ").split()]
+    if not tokens:
+        return ""
+    for prof in profiles:
+        if prof["id"].lower() in tokens:
+            return option_label(prof)
+    if include_none and ("none" in tokens or "(none)" in tokens):
+        return none_sentinel(kind)
+    return ""
+
+
+# ─────────────────────────────── detection ─────────────────────────────────
+# Match a repository against the installed profiles' own `detect` patterns. This
+# is the brownfield source of lane candidates: greenfield asks an operator to pick
+# from `stack-list`, and an existing repo already answered the question in its
+# files. DETECTION PROPOSES — it writes nothing and decides nothing; `declare` is
+# still the only writer, and a person still confirms through select-stack.
+#
+# Patterns are matched on BASENAME, anywhere in the tree, not as root-anchored
+# globs: a profile that ships `detect: ["web/package.json", "web/vite.config.*"]`
+# must still recognise the same stack in `client/` or `apps/portal/`, because a
+# brownfield repo did not choose its layout from our profile. The directory where
+# the patterns actually met IS the detected root, which is why the root comes out
+# of detection rather than out of the profile.
+DETECT_PRUNE = {"node_modules", ".git", "dist", "build", "out", "bin", "obj",
+                "vendor", ".venv", "venv", "__pycache__", ".appweaver", "specs", "knowledge"}
+
+
+_REPO_FILES_CACHE = {}
+
+
+def _repo_files(repo, cap=20000):
+    """Every file in the repo, pruned of the directories detection never looks in.
+
+    Memoised per (repo, cap) for the life of the process. Detection is asked the same
+    question several times in one run — once per kind, plus once more to work out which
+    subtrees another kind already owns — and the answer cannot change underneath a single
+    CLI invocation, which is the only scope this cache spans. On a large brownfield tree
+    the walk is the expensive part of `stack-list --suggest`.
+
+    Callers only read the result, so they share one list.
+    """
+    key = (repo, cap)
+    if key in _REPO_FILES_CACHE:
+        return _REPO_FILES_CACHE[key]
+    out = []
+    for dirpath, dirnames, filenames in os.walk(repo):
+        dirnames[:] = [d for d in dirnames if d not in DETECT_PRUNE and not d.startswith(".")]
+        rel = os.path.relpath(dirpath, repo).replace("\\", "/")
+        rel = "" if rel == "." else rel
+        for f in filenames:
+            out.append((rel + "/" + f) if rel else f)
+            if len(out) >= cap:
+                _REPO_FILES_CACHE[key] = out
+                return out
+    _REPO_FILES_CACHE[key] = out
+    return out
+
+
+def _glob_rx(pattern):
+    """Translate a detect glob to a regex over a '/'-relative path.
+
+    `**` spans directory separators and `*` does not, which is the distinction
+    `src/**/*.csproj` depends on and fnmatch does not make.
+    """
+    out, i = [], 0
+    while i < len(pattern):
+        c = pattern[i]
+        if pattern.startswith("**/", i):
+            out.append("(?:[^/]+/)*"); i += 3
+        elif pattern.startswith("**", i):
+            out.append(".*"); i += 2
+        elif c == "*":
+            out.append("[^/]*"); i += 1
+        elif c == "?":
+            out.append("[^/]"); i += 1
+        else:
+            out.append(re.escape(c)); i += 1
+    return re.compile(r"\A" + "".join(out) + r"\Z")
+
+
+def _ambiguous_basenames(repo):
+    """Detect-pattern filenames that profiles of MORE THAN ONE kind claim.
+
+    `package.json` marks a Node service as readily as a Vite UI, and `*.csproj` a Web API
+    as readily as a Blazor client. Such a name is real evidence where the profile's own
+    layout put it, but it cannot by itself carry a profile into a directory the profile
+    never named — that is how a .NET backend acquires a phantom Blazor UI lane. Derived
+    from the installed profiles rather than listed here, so a new profile that shares a
+    manifest is accounted for by being installed.
+    """
+    owners = {}
+    for prof in load_profiles(repo):
+        for pat in (prof.get("detect") or []):
+            owners.setdefault(os.path.basename(pat), set()).add(prof.get("kind", ""))
+    return {b for b, kinds in owners.items() if len(kinds) > 1}
+
+
+def detect_profiles(repo, kind=None, exclude_roots=()):
+    """Rank the installed profiles against what this repo actually contains.
+
+    `detect` is an ANY-of list: `java-spring` names both `pom.xml` and
+    `build.gradle` because a project has one or the other, and requiring both
+    would make it undetectable. So one pattern hitting is a match, and the COUNT
+    of patterns that hit is the score.
+
+    Matching is tried twice. ANCHORED — the pattern against the repo-relative
+    path, which is how the patterns are written. Then RELOCATED — the same
+    pattern allowed any directory prefix, because a profile that ships
+    `web/package.json` must still recognise the same stack in `client/` or
+    `apps/portal/`: a brownfield repo did not pick its layout from our profiles.
+    An anchored hit outranks a relocated one.
+
+    `root` is reported separately from the match, because in these profiles the
+    two are independent — `go-chi` detects on `go.mod` at the repo root and
+    declares a root of `internal/`. The reported root is the shallowest directory
+    the evidence actually sits in, falling back to the profile's own. Callers with
+    better information override it; `onboard` does exactly that for the frontend
+    lane, from the scan's own candidate roots."""
+    files = _repo_files(repo)
+    ambiguous = _ambiguous_basenames(repo)
+    out = []
+    for prof in load_profiles(repo, kind):
+        patterns = prof.get("detect") or []
+        if not patterns:
+            continue
+        # A subtree another lane already owns cannot be evidence for this one.
+        # Without this a backend profile relocates onto the frontend's own
+        # `package.json` and claims the UI's root — the ownership rule violated by
+        # the very step that is supposed to establish it.
+        scoped = [f for f in files
+                  if not any(norm_root(os.path.dirname(f) or ".").startswith(x)
+                             or (f + "/").startswith(x)
+                             for x in exclude_roots if x)]
+        files_for_prof = scoped if prof.get("kind") != "frontend" else files
+        evidence, matched, anchored_hits = [], 0, 0
+        prof_root = norm_root(prof.get("root") or "")
+        for pat in patterns:
+            rx = _glob_rx(pat)
+            rx_any = _glob_rx("**/" + pat)
+            hits = [f for f in files_for_prof if rx.match(f)]
+            if hits:
+                anchored_hits += 1
+            else:
+                hits = [f for f in files_for_prof if rx_any.match(f)]
+            if not hits and prof_root and pat.startswith(prof_root) \
+                    and os.path.basename(pat) not in ambiguous:
+                # RELOCATED, with the profile's own root segment substituted rather than
+                # prefixed. Prefixing alone only ever finds the profile's own folder name
+                # deeper in the tree — `apps/portal/web/angular.json` — so a UI in
+                # `client/` or at the repo root, which is what most repositories that did
+                # not start from these profiles actually look like, went undetected.
+                # Restricted to names only one kind claims, so substitution widens where a
+                # stack may live without widening what counts as evidence for it.
+                hits = [f for f in files_for_prof
+                        if _glob_rx("**/" + pat[len(prof_root):]).match(f)]
+            if not hits:
+                continue
+            matched += 1
+            evidence.extend(hits[:10])
+        if not matched:
+            continue                      # no evidence at all is not a stack
+        dirs = sorted({os.path.dirname(f) for f in evidence}, key=lambda d: (d.count("/"), len(d)))
+        # WHERE THE SOURCE LIVES, which is not always where the evidence sits. A manifest
+        # at the repo root — `App.sln`, a workspace `package.json` — marks the repository,
+        # not the subtree: the code it describes is under the profile's own root. So repo-
+        # root evidence defers to that root when the directory is really there, and only
+        # falls back to the repo root itself when it is not, which is the case for the
+        # single-package layouts (`create-next-app`, a UI checked out at the top level)
+        # whose files genuinely are at the top.
+        prof_default = norm_root(prof.get("root") or "")
+        if not dirs:
+            root = prof_default
+        elif dirs[0]:
+            root = norm_root(dirs[0])
+        elif prof_default and os.path.isdir(os.path.join(repo, prof_default)):
+            root = prof_default
+        else:
+            root = REPO_ROOT
+        out.append({
+            "id": prof["id"],
+            "kind": prof.get("kind", ""),
+            "title": prof.get("title", prof["id"]),
+            "language": prof.get("language", ""),
+            "root": root,
+            "profile_root": norm_root(prof.get("root") or ""),
+            "build": prof.get("build", ""),
+            "test": prof.get("test", ""),
+            "run": prof.get("run", ""),
+            "patterns": len(patterns),
+            "patterns_matched": matched,
+            "anchored": anchored_hits > 0,
+            "evidence": sorted(set(evidence))[:20],
+        })
+    # Strongest first: an anchored match, then more patterns hit, then a shallower root.
+    out.sort(key=lambda m: (m["anchored"], m["patterns_matched"], -m["root"].count("/")),
+             reverse=True)
+    return out
+
+
+def cmd_detect(args):
+    excl = [norm_root(r) for r in (args.exclude_root or []) if r]
+    matches = detect_profiles(args.repo, args.kind, excl)
+    best = {}
+    for m in matches:
+        best.setdefault(m["kind"], m)
+    emit({
+        "matches": matches,
+        "count": len(matches),
+        "kinds": sorted(best),
+        "backend": best.get("backend", {}),
+        "backend_profile": best.get("backend", {}).get("id", ""),
+        "backend_root": best.get("backend", {}).get("root", ""),
+        "frontend": best.get("frontend", {}),
+        "frontend_profile": best.get("frontend", {}).get("id", ""),
+        "frontend_root": best.get("frontend", {}).get("root", ""),
+    })
+
+
+def suggestion_exclusions(repo, kind):
+    """Subtrees that belong to a DIFFERENT lane, and so cannot be evidence for this one.
+
+    `detect_profiles` already refuses to score a profile on files another lane owns;
+    without a caller supplying that set the rule never engaged on the path select-stack
+    actually uses, and the ownership rule was violated by the very step that establishes
+    it. A repo with an Angular UI in `web/` and a Spring service in `backend/svc/` offered
+    `node-express` rooted at `web/` as its BACKEND: `web/package.json` is anchored evidence
+    for the UI and merely relocated evidence for a Node service, and a shallower root broke
+    the tie the wrong way.
+
+    Two sources, both about a subtree that is already spoken for:
+      - a lane of another kind already declared in stacks.json, and
+      - a profile of another kind whose evidence is ANCHORED — the strength the ranking
+        itself treats as decisive.
+
+    The repo root is never excluded. It is the one directory a fullstack repo legitimately
+    shares — a root `package.json` next to a root `go.mod` — and excluding it would remove
+    every file from consideration rather than narrow the field.
+    """
+    out = set()
+    data = read_stacks(repo) or {}
+    for lane in (data.get("lanes") or []):
+        if lane.get("kind") and lane.get("kind") != kind:
+            r = norm_root(lane.get("root"))
+            if r and r != REPO_ROOT:
+                out.add(r)
+    for other in ("frontend", "backend"):
+        if other == kind:
+            continue
+        others = detect_profiles(repo, other)
+        for i, m in enumerate(others):
+            # The strongest match owns its root even when it had to relocate to find it:
+            # a Vite UI in `client/` is no less the owner of `client/` for the profile
+            # having shipped `web/`. Beyond the strongest, only anchored evidence claims a
+            # subtree, so a weak relocation cannot fence off a directory it merely touched.
+            if i and not m.get("anchored"):
+                continue
+            r = norm_root(m.get("root"))
+            if r and r != REPO_ROOT:
+                out.add(r)
+    return sorted(out)
+
+
+def cmd_list(args):
+    """The menu for one kind, and — with --suggest — the repo's own answer to it.
+
+    Folding detection into the listing is deliberate. select-stack asks two
+    questions and each needs the same two things: the candidates, and what this
+    repository looks like. Two subcommands would walk the file tree twice and add
+    two steps to a workflow whose whole value is being short. One call returns the
+    options, the profile the files point at, and the directory the evidence sits
+    in — which is the source path the operator is about to be asked to confirm.
+
+    HOW A DETECTED STACK IS PROPOSED, and why it is not preselected. Detection
+    moves its match to the FRONT of the option list; it never fills `preselect`.
+    The two are answered at different strengths: `preselect` is the direct-argument
+    fast path and the engine treats it as the answer, ahead of a headless
+    `--select`, so filling it from a scan would let this repo's files silently
+    overrule an operator who named a stack on the command line. Leading the list
+    is the right strength for a proposal — it is what an interactive menu opens on
+    and what `--non-interactive` takes, and both are still choices anyone can
+    override. `(none)` stays last wherever it is offered.
+    """
+    profiles = load_profiles(args.repo, args.kind)
+    sentinel = none_sentinel(args.kind)
+
+    matches = detect_profiles(args.repo, args.kind,
+                              suggestion_exclusions(args.repo, args.kind)) \
+        if args.suggest else []
+    detected = matches[0] if matches else {}
+    suggested_profile = detected.get("id", "")
+    suggested_root = detected.get("root") or detected.get("profile_root") or ""
+    evidence = ", ".join(detected.get("evidence", [])[:4])
+
+    ordered = sorted(profiles, key=lambda p: p["id"] != suggested_profile) \
+        if suggested_profile else profiles
+    options = [option_label(p) for p in ordered]
+    if args.include_none:
+        options.append(sentinel)
+
+    preselect = resolve_preselect(args.preselect, profiles, args.include_none, args.kind)
+    preselect_source = "argument" if preselect else ""
+
+    # Candidate SOURCE PATHS for the follow-up question, best first: where the
+    # evidence actually sits, then each profile's own default. Labelled with why
+    # each is offered, because the operator picking from this list is choosing the
+    # subtree a generator will be allowed to write into. Free text is always
+    # accepted — a repo that matches no profile still has a source path.
+    root_options, seen = [], set()
+
+    def offer(root, why):
+        r = norm_root(root)
+        if not r or r in seen:
+            return
+        seen.add(r)
+        root_options.append(ROOT_LABEL_SEP.join([r, why]))
+
+    if suggested_root:
+        offer(suggested_root, "detected here (%s)" % (suggested_profile or "evidence"))
+    for m in matches[1:]:
+        offer(m.get("root") or m.get("profile_root"), "detected here (%s)" % m["id"])
+    for p in profiles:
+        offer(p.get("root"), "%s default" % p["id"])
+
+    emit({
+        "kind": args.kind or "all",
+        "profiles": profiles,
+        "ids": [p["id"] for p in profiles],
+        "select_options": options,
+        "count": len(profiles),
+        "preselect": preselect,
+        "preselect_source": preselect_source,
+        "detected_profile": suggested_profile,
+        "detected_root": suggested_root,
+        "detected_evidence": evidence,
+        "detected_count": len(matches),
+        "root_options": root_options,
+        "none_sentinel": sentinel,
+    })
+
+
+# ──────────────────────────────── stacks.json ──────────────────────────────
+
+def read_stacks(repo):
+    path = os.path.join(repo, STACKS_REL)
+    if not os.path.isfile(path):
+        return None
+    try:
+        with open(path, "r", encoding="utf-8") as fh:
+            return json.load(fh)
+    except (ValueError, OSError):
+        return None
+
+
+# A source-path option reads "<path>  — <why it is offered>". The separator is two
+# spaces and an em dash, which cannot occur in a path, so one field carries both the
+# value and its justification and `declare` still receives a path.
+ROOT_LABEL_SEP = "  — "
+
+
+def strip_root_label(value):
+    return (value or "").split(ROOT_LABEL_SEP, 1)[0].strip()
+
+
+# The repository root as a source path. A single-module project — a Maven, Cargo, Go
+# or Node repo whose manifest sits at the top — has no subdirectory to name, and the
+# empty string cannot carry it: `verify` reads an empty root as "no source path
+# declared". "./" is the one spelling that survives being normalised twice, which is
+# what makes it usable as a STORED value rather than only as typed input.
+REPO_ROOT = "./"
+
+
+def norm_root(root):
+    """Canonicalise a source path, IDEMPOTENTLY.
+
+    Idempotence is a correctness requirement, not tidiness: `declare` normalises what it
+    writes and `verify` normalises what it reads, so a value that changes on the second
+    pass fails the lane the writer had just accepted. `.` normalising to `./` and `./`
+    then normalising to `""` did exactly that — every repo-root lane declared clean and
+    was rejected by the next gate that looked at it.
+    """
+    raw = strip_root_label(root).replace("\\", "/").strip()
+    r = raw
+    while r.startswith("./"):
+        r = r[2:]
+    if r == ".":
+        r = ""
+    r = r.lstrip("/")               # leading separators only — a '.output/' root keeps its dot
+    if not r:
+        # An empty result means one of two different things: nothing was supplied (no
+        # root), or the repository root itself was. Only the second gets a value.
+        return REPO_ROOT if raw else ""
+    if not r.endswith("/"):
+        r += "/"
+    return r
+
+
+def root_on_disk(repo, root):
+    """Does the lane's source path exist as a directory?
+
+    Reported everywhere a root is reported and enforced only by `verify`. A false
+    here is an ordinary state before any code is written and a hard error once a
+    phase needs to read or write the subtree.
+    """
+    r = norm_root(root)
+    return bool(r) and os.path.isdir(os.path.join(repo, r.rstrip("/")))
+
+
+def lane_workdir(repo, lane):
+    """The directory a lane's commands run in.
+
+    `run_from: "root"` runs them in the lane's own source path; anything else — including
+    the key being ABSENT, which is the shape of every lane written before this key
+    existed — runs them at the repository root. That default is not laziness: a .NET
+    solution file, a go.mod or a package.json at the top is what `dotnet build`,
+    `go build ./...` and `npm run build` need to find, and those profiles declare a `root`
+    that is their SOURCE directory rather than their build directory. The two coincide for
+    a stack whose manifest lives inside the subtree — a Maven wrapper at
+    backend/orderservice/mvnw cannot be reached from the repo root at all.
+
+    Falls back to the repo root when the declared root is not on disk, so the phase
+    reports the command's own failure instead of a chdir error.
+    """
+    if (lane.get("run_from") or "repo") == "root":
+        r = norm_root(lane.get("root"))
+        cand = os.path.join(repo, r.rstrip("/")) if r else repo
+        if os.path.isdir(cand):
+            return cand
+    return repo
+
+
+def lane_command(lane, phase):
+    """The command for one phase, with `{{root}}` standing for the lane's root.
+
+    A profile command sometimes has to NAME the source path — `dotnet run --project
+    src/`, `python -m compileall app`. Written literally, that is the profile's
+    default root frozen into the command, and it stays frozen when the lane declares
+    a different one: a service at `Services/Api/` runs the project at `src/`, or
+    fails looking for it. The placeholder lets the profile say "the root this lane
+    declares" and be right on every layout.
+
+    Expanded at RUN time, not at declare time, so editing `root` in stacks.json by
+    hand keeps the command consistent with it. A command with no placeholder is
+    returned untouched, so every literal command already on disk is unaffected.
+    """
+    cmd = (lane.get(phase) or "").strip()
+    if "{{root}}" not in cmd:
+        return cmd
+    r = norm_root(lane.get("root"))
+    # `./` is the repo root: a bare `./` reads as noise in a command line, and the
+    # only sensible substitution for "the root, which is here" is the cwd itself.
+    sub = "." if (r == REPO_ROOT or not r) else r.rstrip("/")
+    return cmd.replace("{{root}}", sub)
+
+
+def roots_overlap(a, b):
+    """Roots own their subtree, so containment either way is an overlap.
+
+    Compared as '/'-terminated strings, which keeps 'src/' clear of 'src-gen/'
+    while still catching 'src/' against 'src/api/'.
+    """
+    a, b = norm_root(a), norm_root(b)
+    if not a or not b:
+        return False
+    # The repository root contains every other subtree, and prefix comparison cannot see
+    # that — "./" is not a prefix of "web/". Without this a lane rooted at the top and a
+    # lane rooted inside it both pass the writer's check and then own the same files.
+    if a == REPO_ROOT or b == REPO_ROOT:
+        return True
+    return a == b or a.startswith(b) or b.startswith(a)
+
+
+def cmd_declare(args):
+    repo = args.repo
+    data = read_stacks(repo) or {"lanes": []}
+    lanes = data.get("lanes") or []
+
+    # "none" is a declaration too: it says this project has no lane of this kind.
+    # Routing it through the writer keeps re-runs correct — a UI lane declared in
+    # an earlier run is removed here rather than stranded.
+    profile_id = profile_id_from_label(args.profile)
+    if profile_id.lower() in ("none", "(none)"):
+        if not args.kind:
+            fail("lane-declare: --kind is required with --profile none")
+        removed = [l for l in lanes if l.get("kind") == args.kind]
+        lanes = [l for l in lanes if l.get("kind") != args.kind]
+        data["lanes"] = lanes
+        if args.kind == "frontend":
+            data.pop("prototype", None)
+        write_stacks(repo, data)
+        # Same key set as the declare branch below: callers bind these outputs
+        # without knowing which branch ran.
+        emit({
+            "declared": False,
+            "lane": {},
+            "lane_id": "",
+            "kind": args.kind,
+            "profile": "",
+            "root": "",
+            "source_path": "",
+            "root_exists": False,
+            "replaced": False,
+            "removed": [l.get("id") for l in removed],
+            "lanes": lanes,
+            "lane_count": len(lanes),
+            "prototype": data.get("prototype", {}),
+            "path": STACKS_REL,
+            "written": True,
+        })
+        return
+
+    # `detected` is a profile-shaped hole for a stack the kit ships no profile for.
+    # Brownfield needs it and greenfield never does: the eleven installed profiles
+    # describe how a NEW project would be started, while a legacy WebForms, JSP,
+    # ERB or Razor-MVC lane matches none of them and is no less real for it.
+    # Refusing to declare those would leave exactly the repos onboard exists for
+    # unable to record a lane. It is deliberately a distinct sentinel rather than a
+    # relaxation of the unknown-profile check, so a mistyped profile id still fails
+    # loudly instead of silently becoming a lane.
+    prof = None
+    if profile_id.lower() == "detected":
+        if not args.kind:
+            fail("lane-declare: --kind is required with --profile detected")
+        if not args.stack:
+            fail("lane-declare: --stack <label> is required with --profile detected "
+                 "(what the code was found to be, e.g. 'asp.net-webforms')")
+        if not args.root:
+            fail("lane-declare: --root is required with --profile detected "
+                 "(no profile to take a default root from)")
+    else:
+        profiles = {p["id"]: p for p in load_profiles(repo)}
+        prof = profiles.get(profile_id)
+        if prof is None:
+            fail("lane-declare: unknown stack profile '%s'. Known: %s"
+                 % (profile_id, ", ".join(sorted(profiles)) or "(none installed)"))
+
+    kind = args.kind or (prof or {}).get("kind")
+    lane_id = args.id or DEFAULT_LANE_ID.get(kind, kind)
+    root = norm_root(args.root or (prof or {}).get("root") or "")
+    if not root:
+        fail("lane-declare: lane '%s' has no source path. A lane without a root owns "
+             "nothing, so nothing can be built, run or written into it. Pass "
+             "--source-path <dir> (the profile declares no default)." % lane_id)
+
+    # Greenfield declares a path that does not exist yet, so existence is checked
+    # only where a caller says the subtree must already be there — onboard, which
+    # is about to read the code out of it.
+    exists = root_on_disk(repo, root)
+    if args.require_existing_root and not exists:
+        fail("lane-declare: source path '%s' for lane '%s' does not exist under %s. "
+             "Point the lane at the directory that actually holds this lane's source, "
+             "or re-run /appweaver select-stack to correct it."
+             % (root, lane_id, repo))
+
+    lane = {
+        "id": lane_id,
+        "kind": kind,
+        "profile": prof["id"] if prof else "detected",
+        "root": root,
+        "build": args.build or (prof or {}).get("build", ""),
+        "test": args.test or (prof or {}).get("test", ""),
+        "run": args.run or (prof or {}).get("run", ""),
+    }
+    # SCHEMA MIGRATION, the one phase most stacks answer differently. A profile that
+    # declares `migrate` gets it recorded like any other phase command; the shipped
+    # profiles declare none, because there is no single right answer (Flyway, Liquibase,
+    # Alembic, Prisma, golang-migrate all coexist) and inventing one would be a guess
+    # dressed as a default. Absent, `run-migrate` keeps its .NET `dotnet ef` path and
+    # otherwise reports honestly that nothing ran — an empty key here changes nothing.
+    migrate = args.migrate or (prof or {}).get("migrate", "")
+    if migrate:
+        lane["migrate"] = migrate
+    # WHERE this lane's commands run — see lane_workdir. Recorded only when it is not
+    # the default, so a lane reads the same as it always did unless its stack needs the
+    # other answer.
+    run_from = getattr(args, "run_from", "") or (prof or {}).get("run_from", "")
+    if run_from == "root":
+        lane["run_from"] = "root"
+    # What the code was found to be, when no shipped profile names it.
+    if args.stack:
+        lane["stack"] = args.stack
+    # How this lane came to be declared. Absent means a person picked it — the
+    # greenfield path, and the historical shape of every lane written before now.
+    if args.origin and args.origin != "declared":
+        lane["origin"] = args.origin
+
+    # root IS ownership: two generators must never be able to write one file.
+    for other in lanes:
+        if other.get("id") == lane_id:
+            continue
+        if roots_overlap(root, other.get("root")):
+            fail("lane-declare: root '%s' for lane '%s' overlaps lane '%s' at '%s'. "
+                 "Lane roots own their subtree and must be disjoint."
+                 % (root, lane_id, other.get("id"), other.get("root")))
+
+    replaced = False
+    for i, other in enumerate(lanes):
+        if other.get("id") == lane_id:
+            lanes[i] = lane
+            replaced = True
+            break
+    if not replaced:
+        lanes.append(lane)
+
+    data["lanes"] = lanes
+
+    # The prototype block is NOT a lane: a root and a run command so an operator
+    # can open it, and nothing else. It is never built, tested, gated or deployed.
+    if kind == "frontend" and not args.no_prototype:
+        proto_run = args.prototype_run or (prof or {}).get("prototype_run", "")
+        if proto_run:
+            data["prototype"] = {
+                "root": norm_root(args.prototype_root or "prototype/"),
+                "run": proto_run,
+            }
+
+    write_stacks(repo, data)
+    emit({
+        "declared": True,
+        "lane": lane,
+        "lane_id": lane_id,
+        "kind": kind,
+        "profile": lane["profile"],
+        "stack": lane.get("stack", ""),
+        "origin": lane.get("origin", "declared"),
+        "root": root,
+        "source_path": root,
+        "root_exists": exists,
+        "replaced": replaced,
+        "removed": [],
+        "lanes": lanes,
+        "lane_count": len(lanes),
+        "prototype": data.get("prototype", {}),
+        "path": STACKS_REL,
+        "written": True,
+    })
+
+
+def write_stacks(repo, data):
+    os.makedirs(os.path.join(repo, ".appweaver"), exist_ok=True)
+    path = os.path.join(repo, STACKS_REL)
+    with open(path, "w", encoding="utf-8") as fh:
+        json.dump(data, fh, indent=2)
+        fh.write("\n")
+
+
+def profile_of(repo, lane):
+    """The stack profile a lane names, or {} when it names none the kit ships."""
+    if not lane:
+        return {}
+    pid = lane.get("profile", "")
+    if not pid or pid in ("detected", "none"):
+        return {}
+    return next((p for p in load_profiles(repo) if p.get("id") == pid), {})
+
+
+def kind_block(repo, lanes, kind):
+    """Every field a caller needs about ONE kind, flattened and prefixed.
+
+    A workflow that wants the service source path binds `$.backend_source_path`
+    and is done — no `--kind` argument, no second call, and no branch on which
+    lane came back. Both kinds are always present in the payload, so the two-lane
+    steps (a gate that needs backend, a report that names both) resolve one script
+    call rather than two. Empty strings where the lane is not declared: the engine
+    compares variables as text, and an absent lane must read as absent.
+    """
+    lane = next((l for l in lanes if l.get("kind") == kind), {})
+    root = lane.get("root", "")
+    prof = profile_of(repo, lane)
+    return {
+        kind + "_declared": bool(lane),
+        kind + "_lane_id": lane.get("id", ""),
+        kind + "_profile": lane.get("profile", ""),
+        kind + "_stack": lane.get("stack", ""),
+        kind + "_origin": lane.get("origin", "declared") if lane else "",
+        # WHAT the stack IS, as opposed to where it lives. The three identity fields
+        # come from the profile at read time rather than from the lane record, so a
+        # lane declared before they existed answers them too — no re-declaration.
+        # A `detected` lane has no profile to read: its own `stack` label is the
+        # only name it has, and language/ecosystem stay empty rather than guessed.
+        kind + "_language": prof.get("language", ""),
+        kind + "_ecosystem": prof.get("ecosystem", ""),
+        kind + "_title": prof.get("title", "") or lane.get("stack", ""),
+        kind + "_root": root,
+        kind + "_source_path": root,
+        kind + "_root_exists": root_on_disk(repo, root),
+        kind + "_build": lane_command(lane, "build"),
+        kind + "_test": lane_command(lane, "test"),
+        kind + "_run": lane_command(lane, "run"),
+        kind + "_migrate": lane_command(lane, "migrate") or prof.get("migrate", ""),
+    }
+
+
+def cmd_resolve(args):
+    data = read_stacks(args.repo)
+
+    # Absence is a valid state for READING, never a failure: `resolve` reports what
+    # is there and lets the caller decide. It is `verify` that turns an absent or
+    # unusable declaration into a stop, and only in the phases that need one.
+    if data is None:
+        payload = {
+            "declared": False, "exists": False, "lanes": [], "lane_count": 0,
+            "found": False, "lane": {}, "kinds": [], "prototype": {},
+            "lane_id": "", "root": "", "source_path": "", "root_exists": False,
+            "build": "", "test": "", "run": "", "migrate": "",
+            "language": "", "ecosystem": "",
+            "path": STACKS_REL,
+        }
+        payload.update(kind_block(args.repo, [], "backend"))
+        payload.update(kind_block(args.repo, [], "frontend"))
+        emit(payload)
+        return
+
+    lanes = data.get("lanes") or []
+    match = {}
+    if args.id:
+        match = next((l for l in lanes if l.get("id") == args.id), {})
+    elif args.kind:
+        match = next((l for l in lanes if l.get("kind") == args.kind), {})
+
+    # `declared` is about LANES and `exists` about the file — they part company on
+    # the shipped-but-unfilled seed, which is on disk and declares nothing.
+    payload = {
+        "declared": bool(lanes),
+        "exists": True,
+        "lanes": lanes,
+        "lane_count": len(lanes),
+        "kinds": sorted({l.get("kind", "") for l in lanes if l.get("kind")}),
+        "found": bool(match),
+        "lane": match,
+        "lane_id": match.get("id", ""),
+        "root": match.get("root", ""),
+        "source_path": match.get("root", ""),
+        "root_exists": root_on_disk(args.repo, match.get("root", "")),
+        "build": lane_command(match, "build"),
+        "test": lane_command(match, "test"),
+        "run": lane_command(match, "run"),
+        "migrate": lane_command(match, "migrate") or profile_of(args.repo, match).get("migrate", ""),
+        "language": profile_of(args.repo, match).get("language", ""),
+        "ecosystem": profile_of(args.repo, match).get("ecosystem", ""),
+        "prototype": data.get("prototype", {}),
+        "path": STACKS_REL,
+    }
+    payload.update(kind_block(args.repo, lanes, "backend"))
+    payload.update(kind_block(args.repo, lanes, "frontend"))
+    emit(payload)
+
+
+# ──────────────────────────────── verify ───────────────────────────────────
+# The gate. `resolve` reports; this decides whether the declaration is USABLE for
+# the phase about to run, and it is the only place a lane model becomes fatal.
+#
+# TWO CLASSES OF FAILURE, and the distinction is the whole design:
+#
+#   MISSING — the phase needs a lane of this kind and none is declared. Reported
+#   only for the kinds a caller asks for with --require, because "no frontend
+#   lane" is the correct and common state and must never fail a backend build.
+#
+#   BROKEN — a lane IS declared and its source path is empty or is not a directory.
+#   Checked for EVERY declared lane whether or not the caller asked about it. A
+#   stack named against a path that is not there is a mistake in every phase, and
+#   letting it through means discovering it as an empty build or a generator
+#   writing into a directory it just created by accident.
+#
+# --allow-missing-root turns the on-disk half off. That is the greenfield state:
+# select-stack declares `src/` before any code exists, and the path becomes real
+# when implement writes into it. Every phase that READS the subtree — implement,
+# build, run, onboard — leaves the check on.
+
+KIND_PHASES = {
+    "backend": "implement / implement-delta / build / run",
+    "frontend": "ui-implement / ui-implement-delta",
+}
+
+
+def cmd_verify(args):
+    repo = args.repo
+    data = read_stacks(repo)
+    lanes = (data or {}).get("lanes") or []
+    required = [k for k in (args.require or []) if k in ("backend", "frontend")]
+    issues = []
+
+    # An empty file and an absent one are the SAME state. The kit ships
+    # stacks.json holding `{"lanes": []}` so a project can fill it in by hand, so
+    # the file being there says nothing about whether a lane was declared — only
+    # its contents do. Both cases report one issue naming which of the two it is.
+    if not lanes:
+        issues.append(
+            "no lane is declared: %s %s. A project with neither a service nor a UI "
+            "lane has nothing to build, govern or generate. Run "
+            "`/appweaver select-stack` to declare each lane's stack and source "
+            "path, or fill the file in by hand (the schema is in "
+            ".appweaver/STACK-PROFILES.md)."
+            % (STACKS_REL, "does not exist" if data is None else "declares no lanes"))
+    else:
+        for kind in required:
+            if not any(l.get("kind") == kind for l in lanes):
+                issues.append(
+                    "no %s lane is declared in %s, and %s needs one. Run "
+                    "`/appweaver select-stack` and choose a %s stack."
+                    % (kind, STACKS_REL, args.command or KIND_PHASES.get(kind, "this phase"), kind))
+        # BROKEN is checked across every declared lane, not just the required ones.
+        for lane in lanes:
+            kind, lane_id = lane.get("kind", "?"), lane.get("id", "?")
+            root = lane.get("root", "")
+            if not root:
+                issues.append(
+                    "lane '%s' (%s, stack %s) declares no source path. A lane owns a "
+                    "subtree; without one nothing can be built, run or written into it. "
+                    "Re-run `/appweaver select-stack` and give it a source path."
+                    % (lane_id, kind, lane.get("profile", "?")))
+            elif not args.allow_missing_root and not root_on_disk(repo, root):
+                issues.append(
+                    "lane '%s' (%s, stack %s) declares source path '%s', which is not a "
+                    "directory in this repository. Re-run `/appweaver select-stack` and "
+                    "point the lane at the directory that holds its source."
+                    % (lane_id, kind, lane.get("profile", "?"), root))
+        # `declare` refuses an overlap, so one can only arrive here through a
+        # hand-edited file — a supported way to fill this in, and the one path that
+        # does not pass the writer. The invariant is worth a second check anywhere:
+        # two lanes sharing a subtree means two generators can write one file.
+        for i, first in enumerate(lanes):
+            for second in lanes[i + 1:]:
+                if roots_overlap(first.get("root"), second.get("root")):
+                    issues.append(
+                        "lanes '%s' and '%s' claim overlapping source paths '%s' and '%s'. "
+                        "Lane roots own their subtree and must be disjoint, or two "
+                        "generators can write the same file. Give each lane a source path "
+                        "outside the other's."
+                        % (first.get("id", "?"), second.get("id", "?"),
+                           first.get("root", ""), second.get("root", "")))
+
+    payload = {
+        "ok": not issues,
+        "declared": bool(lanes),
+        "required": required,
+        "lanes": lanes,
+        "lane_count": len(lanes),
+        "kinds": sorted({l.get("kind", "") for l in lanes if l.get("kind")}),
+        "root_check": not args.allow_missing_root,
+        "issues": issues,
+        "issue_count": len(issues),
+        # No lanes always carries an issue now, so a clean run always has lanes to name.
+        "message": " ".join(issues) if issues else
+                   ("lane model ok: " + ", ".join(
+                       "%s (%s) at %s" % (l.get("id", "?"), l.get("profile", "?"), l.get("root", "?"))
+                       for l in lanes)),
+        "path": STACKS_REL,
+    }
+    payload.update(kind_block(repo, lanes, "backend"))
+    payload.update(kind_block(repo, lanes, "frontend"))
+    emit(payload)
+    # Exit 0 even when the check fails: the workflow gate owns the stop, so the
+    # message and every flattened field still reach it. A non-zero exit here would
+    # make `on_error: continue` the only way to read the reason a run was refused.
+
+
+# ────────────────────────────── run-phase ──────────────────────────────────
+# Execute a phase's project-supplied command for EVERY declared lane.
+#
+# This is the payoff of declaring a source path. Without a declaration, `build`
+# sniffs: it looks for a .sln, then for a package.json, and takes the first hit.
+# On a single-lane repo that is right. On a two-lane repo it is wrong in the worst
+# way available — it builds the backend, reports green, and never mentions that the
+# frontend was not compiled at all. Iterating the declared lanes is what turns "one
+# build" from a guess into a fact, and a lane whose command fails fails the phase.
+#
+# The engine stays stack-ignorant: these are strings out of stacks.json, run in the
+# repo root, and nothing here knows what a compiler is. A lane with no command for
+# the phase is skipped rather than failed — a profile is allowed to have no test
+# command, and a lane the project never wired up should not fail a build.
+
+LOG_TAIL = 1400
+
+
+def cmd_run_phase(args):
+    import subprocess
+
+    repo = args.repo
+    data = read_stacks(repo)
+    declared = (data or {}).get("lanes") or []
+    lanes = declared
+    if args.kind:
+        lanes = [l for l in lanes if l.get("kind") == args.kind]
+
+    results, tails, cmds = [], [], []
+    ok, ran = True, False
+    for lane in lanes:
+        cmd = lane_command(lane, args.phase)
+        lane_id, root = lane.get("id", "?"), lane.get("root", "")
+        if not cmd:
+            results.append({"lane": lane_id, "root": root, "cmd": "",
+                            "ran": False, "ok": True, "skipped": "no %s command" % args.phase})
+            continue
+        # The source path has to be there before a command is run against it.
+        # Reported per lane rather than raised, so a two-lane run still reports
+        # what the other lane did.
+        if not root_on_disk(repo, root):
+            ok = False
+            results.append({"lane": lane_id, "root": root, "cmd": cmd, "ran": False, "ok": False,
+                            "error": "source path '%s' is not a directory" % root})
+            tails.append("[%s] source path '%s' is not a directory" % (lane_id, root))
+            continue
+        ran = True
+        cmds.append(cmd)
+        workdir = lane_workdir(repo, lane)
+        proc = subprocess.run(cmd, shell=True, cwd=workdir, stdout=subprocess.PIPE,
+                              stderr=subprocess.STDOUT)
+        out = proc.stdout.decode("utf-8", "replace")
+        lane_ok = proc.returncode == 0
+        ok = ok and lane_ok
+        results.append({"lane": lane_id, "root": root, "cmd": cmd, "ran": True,
+                        "ok": lane_ok, "exit_code": proc.returncode,
+                        "cwd": os.path.relpath(workdir, repo).replace("\\", "/")})
+        if not lane_ok or args.phase == "run":
+            tails.append("[%s] %s" % (lane_id, out[-LOG_TAIL:]))
+
+    emit({
+        "ok": ok,
+        # Every lane the file declares, not the kind-filtered slice this phase ran.
+        "declared": bool(declared),
+        "phase": args.phase,
+        "tool": "lanes",
+        "ran": ran,
+        "lane_count": len(lanes),
+        "lanes_run": [r["lane"] for r in results if r["ran"]],
+        "lanes_skipped": [r["lane"] for r in results if not r["ran"]],
+        "results": results,
+        "cmd": " && ".join(cmds),
+        "log_tail": "\n".join(tails)[-LOG_TAIL:],
+    })
+
+
+# ──────────────────────────────── probe ────────────────────────────────────
+
+def profile_terms(prof):
+    """The words that unambiguously NAME this stack: its id and the id's parts.
+
+    Title and language are deliberately excluded. "TypeScript", "Next" and "Web"
+    all occur in ordinary prose about a backend, and the two errors are not
+    symmetric: a false positive authors a governed file the project never asked
+    for, while a false negative only produces a warning that names the fix.
+    """
+    pid = (prof.get("id") or "").lower()
+    terms = {pid} if pid else set()
+    terms.update(p for p in re.split(r"[-_]+", pid) if len(p) >= 3)
+    return terms
+
+
+def hint_tokens(text):
+    """Tokenise free prose into stack-name candidates.
+
+    Keeps '-' and '.' inside a token so "react-vite" and "next.js" survive
+    whole, and adds a punctuation-stripped form of each so "next.js" also
+    reaches the profile id "nextjs".
+    """
+    out = set()
+    for raw in re.split(r"[^A-Za-z0-9+#._-]+", (text or "").lower()):
+        tok = raw.strip("._-+")
+        if not tok:
+            continue
+        out.add(tok)
+        out.add(re.sub(r"[._]", "", tok))
+    return out
+
+
+def cmd_probe(args):
+    """Evidence that a lane of this kind exists, from the two FILE signals.
+
+    This answers only what stacks.json and the shipped profiles can answer. The
+    authoritative signal — whether the active pack maps `## /aw-spec-<command>`
+    for the lane's phases — belongs to `resolve-tech`, and callers OR it in.
+    Re-parsing the rule map here would be a third implementation of a contract
+    that already has two, so this deliberately stops short of it.
+
+    Read-only and never fatal: an absent stacks.json, an absent profile
+    directory and an empty hint are all ordinary answers, not errors.
+    """
+    lanes = (read_stacks(args.repo) or {}).get("lanes") or []
+    lane = next((l for l in lanes if l.get("kind") == args.kind), {})
+
+    tokens = hint_tokens(args.hint)
+    hint_profile, hint_terms = "", []
+    for prof in load_profiles(args.repo, args.kind):
+        hit = sorted(profile_terms(prof) & tokens)
+        if hit:
+            hint_profile, hint_terms = prof["id"], hit
+            break
+
+    signals = []
+    if lane:
+        signals.append("declaration")
+    if hint_profile:
+        signals.append("hint")
+
+    parts = []
+    if lane:
+        parts.append("lane '%s' (%s) declared in %s"
+                     % (lane.get("id", ""), lane.get("profile", ""), STACKS_REL))
+    if hint_profile:
+        parts.append("the request names %s (matched on %s)"
+                     % (hint_profile, ", ".join(hint_terms)))
+
+    emit({
+        "kind": args.kind,
+        "declared": bool(lane),
+        "lane": lane,
+        "declared_lane_id": lane.get("id", ""),
+        "declared_profile": lane.get("profile", ""),
+        "declared_root": lane.get("root", ""),
+        "hint_profile": hint_profile,
+        "hint_terms": hint_terms,
+        "signals": signals,
+        "any": bool(signals),
+        "evidence": "; ".join(parts),
+    })
+
+
+def main():
+    ap = argparse.ArgumentParser(prog="aw-stack", description=__doc__)
+    ap.add_argument("--repo", default=".", help="repository root (callers pass their own resolver's answer)")
+    sub = ap.add_subparsers(dest="cmd")
+
+    p = sub.add_parser("list", help="enumerate the installed stack profiles")
+    p.add_argument("--kind", choices=["backend", "frontend", "all"], default="all")
+    p.add_argument("--include-none", action="store_true",
+                   help="append the '(none)' sentinel — for an optional lane")
+    p.add_argument("--preselect", default="",
+                   help="direct-argument text; matched against this kind's profile ids")
+    p.add_argument("--suggest", action="store_true",
+                   help="also run detection over this repo, so the menu opens on the "
+                        "stack the files point at and root_options leads with the "
+                        "directory the evidence sits in")
+    p.set_defaults(func=cmd_list)
+
+    p = sub.add_parser("detect", help="match the repo's files against the installed profiles")
+    p.add_argument("--kind", choices=["backend", "frontend", "all"], default="all")
+    p.add_argument("--exclude-root", dest="exclude_root", action="append", default=[],
+                   help="a subtree another lane owns; repeatable. Backend candidates find no "
+                        "evidence there, so a service profile cannot relocate onto the UI's files")
+    p.set_defaults(func=cmd_detect)
+
+    p = sub.add_parser("declare", help="upsert a lane into stacks.json (sole writer)")
+    p.add_argument("--profile", required=True,
+                   help="profile id, a select_options label, 'none', or 'detected' "
+                        "(a stack the kit ships no profile for — needs --stack and --root)")
+    p.add_argument("--kind", choices=["backend", "frontend"])
+    p.add_argument("--id", help="lane id (default: service for backend, web for frontend)")
+    p.add_argument("--root", "--source-path", dest="root",
+                   help="the lane's SOURCE PATH — the subtree it owns, overriding the "
+                        "profile's default root. The two spellings are one field")
+    p.add_argument("--run-from", dest="run_from", choices=["repo", "root"],
+                   help="where this lane's build/test/run commands execute: 'repo' (default) "
+                        "at the repository root, which is what a top-level solution file, "
+                        "go.mod or package.json needs; 'root' inside the lane's own source "
+                        "path, which is the only way to reach a manifest nested in the "
+                        "subtree (a Maven wrapper at backend/<app>/mvnw). Defaults to the "
+                        "profile's own setting")
+    p.add_argument("--require-existing-root", dest="require_existing_root", action="store_true",
+                   help="refuse a source path that is not a directory. For a caller about "
+                        "to READ the subtree (onboard); greenfield declares a path that "
+                        "implement has not created yet, and leaves this off")
+    p.add_argument("--stack", default="",
+                   help="what the code was found to be, when no shipped profile names it")
+    p.add_argument("--origin", default="declared", choices=["declared", "reverse-engineered"],
+                   help="how the lane came to be declared; recorded only when not 'declared'")
+    p.add_argument("--build")
+    p.add_argument("--test")
+    p.add_argument("--run")
+    p.add_argument("--migrate", default="",
+                   help="schema-migration command for this lane (overrides the profile's)")
+    p.add_argument("--prototype-root", dest="prototype_root")
+    p.add_argument("--prototype-run", dest="prototype_run")
+    p.add_argument("--no-prototype", dest="no_prototype", action="store_true",
+                   help="do not write the prototype block. Brownfield: the prototype phase "
+                        "does not run on adopted features, and the profile's default would "
+                        "point at a directory the repo does not have")
+    p.set_defaults(func=cmd_declare)
+
+    p = sub.add_parser("resolve", help="read stacks.json")
+    p.add_argument("--kind", choices=["backend", "frontend"])
+    p.add_argument("--id")
+    p.set_defaults(func=cmd_resolve)
+
+    p = sub.add_parser("verify", help="is the declaration usable for the phase about to run")
+    p.add_argument("--require", action="append", default=[], choices=["backend", "frontend"],
+                   help="a lane kind this phase cannot run without; repeatable. Omit to "
+                        "check only that whatever IS declared is sound")
+    p.add_argument("--allow-missing-root", dest="allow_missing_root", action="store_true",
+                   help="do not require the source paths to exist on disk yet — the "
+                        "greenfield state, where select-stack declares a path implement "
+                        "will create")
+    p.add_argument("--command", default="",
+                   help="the phase being gated, quoted back in the failure message")
+    p.set_defaults(func=cmd_verify)
+
+    p = sub.add_parser("run-phase", help="run a phase's command for every declared lane")
+    p.add_argument("--phase", required=True, choices=["build", "test", "run", "migrate"],
+                   help="which project-supplied command to run")
+    p.add_argument("--kind", choices=["backend", "frontend"],
+                   help="restrict to one lane kind (default: every declared lane)")
+    p.set_defaults(func=cmd_run_phase)
+
+    p = sub.add_parser("probe", help="evidence of a lane of this kind (file signals only)")
+    p.add_argument("--kind", choices=["backend", "frontend"], default="frontend")
+    p.add_argument("--hint", default="", help="free prose to scan for a stack name")
+    p.set_defaults(func=cmd_probe)
+
+    args = ap.parse_args()
+    if not getattr(args, "func", None):
+        ap.print_help()
+        sys.exit(0)
+    args.func(args)
+
+
+if __name__ == "__main__":
+    main()