@stylusnexus/work-plan 2026.6.15 → 2026.6.16

package/skills/work-plan/commands/set_next_up.py

@@ -1,10 +1,20 @@
 """set-next-up subcommand — guarded edit of a track's next_up ranking preset.
 
 Usage:
-  work_plan.py set-next-up <track> [--repo=<key>] (--preset=<name> | --order=a,b,c | --clear) [--confirm=<token>]
+  work_plan.py set-next-up <track> [--repo=<key>]
+      (--preset=<name> | --order=a,b,c | --clear | --auto=on|off)
+      [--confirm=<token>]
 
-Writes `next_up_order` into the track's frontmatter. Does NOT touch the
-`next_up` issue-list key.
+Writes `next_up_order` and/or `next_up_auto` into the track's frontmatter.
+Does NOT touch the `next_up` issue-list key.
+
+  --preset=<name>   Set one of the named ranking presets (flow, priority-driven,
+                    backlog) or 'custom' (which requires --order).
+  --order=a,b,c     Set a custom comma-separated criterion list.
+  --clear           Remove the next_up_order key (reverts to global/default).
+  --auto=on|off     Toggle the next_up_auto flag. When on, brief/orient/export
+                    auto-derive the next-up list via the ranking preset (#326).
+                    Can be used standalone or combined with --preset/--order/--clear.
 
 Public-repo gated: without --confirm it prints {needs_confirm, reason, token}
 and makes no change. The VS Code extension surfaces that as a modal then
@@ -22,12 +32,12 @@ from lib.next_up import CRITERIA, PRESETS
 
 def run(args: list[str]) -> int:
     flags, positional = parse_flags(
-        args, {"--confirm", "--repo", "--clear", "--preset", "--order"}
+        args, {"--confirm", "--repo", "--clear", "--preset", "--order", "--auto"}
     )
     if not positional:
         print(
             "usage: work_plan.py set-next-up <track> "
-            "(--preset=<name> | --order=a,b,c | --clear) "
+            "(--preset=<name> | --order=a,b,c | --clear | --auto=on|off) "
             "[--repo=<key>] [--confirm=<token>]"
         )
         return 2
@@ -41,11 +51,27 @@ def run(args: list[str]) -> int:
     clear = bool(flags.get("--clear"))
     preset_flag = flags.get("--preset") if flags.get("--preset") is not True else None
     order_flag = flags.get("--order") if flags.get("--order") is not True else None
+    auto_raw = flags.get("--auto") if flags.get("--auto") is not True else None
+
+    # Parse and validate --auto value
+    auto_value = None  # None means not specified
+    if auto_raw is not None:
+        auto_lower = auto_raw.lower() if isinstance(auto_raw, str) else ""
+        if auto_lower == "on":
+            auto_value = True
+        elif auto_lower == "off":
+            auto_value = False
+        else:
+            print(
+                f"ERROR: --auto must be 'on' or 'off', got {auto_raw!r}",
+                file=sys.stderr,
+            )
+            return 2
 
-    # Must have at least one of --preset, --order, or --clear
-    if not clear and preset_flag is None and order_flag is None:
+    # Must have at least one of --preset, --order, --clear, or --auto
+    if not clear and preset_flag is None and order_flag is None and auto_value is None:
         print(
-            "ERROR: specify --preset=<name>, --order=a,b,c, or --clear",
+            "ERROR: specify --preset=<name>, --order=a,b,c, --clear, or --auto=on|off",
             file=sys.stderr,
         )
         return 2
@@ -123,8 +149,19 @@ def run(args: list[str]) -> int:
 
     if clear:
         track.meta.pop("next_up_order", None)
+        if auto_value is not None:
+            _apply_auto(track, auto_value)
         write_file(track.path, track.meta, track.body)
         print(f"✓ cleared next_up_order on {track.name}")
+        if auto_value is not None:
+            _print_auto_result(track, auto_value)
+        return 0
+
+    # If --auto is the only flag (no preset/order/clear), write just the auto flag.
+    if preset_flag is None and order_list is None and auto_value is not None:
+        _apply_auto(track, auto_value)
+        write_file(track.path, track.meta, track.body)
+        _print_auto_result(track, auto_value)
         return 0
 
     # Build the next_up_order mapping
@@ -145,10 +182,29 @@ def run(args: list[str]) -> int:
             )
 
     track.meta["next_up_order"] = nuo
+    if auto_value is not None:
+        _apply_auto(track, auto_value)
     write_file(track.path, track.meta, track.body)
 
     if preset_flag and preset_flag != "custom":
         print(f"✓ set next_up_order preset={preset_flag!r} on {track.name}")
     elif order_list is not None:
         print(f"✓ set next_up_order custom order={order_list!r} on {track.name}")
+    if auto_value is not None:
+        _print_auto_result(track, auto_value)
     return 0
+
+
+def _apply_auto(track: "SimpleNamespace", auto_value: bool) -> None:
+    """Mutate track.meta to set or remove next_up_auto."""
+    if auto_value:
+        track.meta["next_up_auto"] = True
+    else:
+        track.meta.pop("next_up_auto", None)
+
+
+def _print_auto_result(track: "SimpleNamespace", auto_value: bool) -> None:
+    if auto_value:
+        print(f"✓ set next_up_auto=true on {track.name}")
+    else:
+        print(f"✓ cleared next_up_auto on {track.name}")

package/skills/work-plan/commands/which_repo.py

@@ -0,0 +1,52 @@
+"""which-repo — resolve the current directory to a configured repo.
+
+Prints the matched repo's config key + GitHub slug, or reports no match. The
+VS Code viewer spawns this with cwd set to the workspace folder to auto-focus its
+repo lens (#357); `brief` calls the underlying resolver directly for cwd
+auto-scope (#358). Read-only — never mutates anything.
+
+Exit codes (human form): 0 on a match, 1 on no match — so a shell caller can
+gate on it. The `--json` form always exits 0 and prints a `{"key": ...}` payload
+(key is null on no match) for the viewer to parse.
+"""
+import json
+import os
+
+from lib.config import load_config, ConfigError
+from lib.cwd_repo import resolve_repo_for_dir
+from lib.prompts import parse_flags
+
+
+def run(args: list) -> int:
+    flags, _ = parse_flags(args, {"--json"})
+    want_json = bool(flags.get("--json"))
+
+    try:
+        cfg = load_config()
+    except ConfigError as e:
+        if want_json:
+            print(json.dumps({"key": None}))
+            return 0
+        print(f"ERROR: {e}")
+        return 1
+
+    match = resolve_repo_for_dir(cfg, os.getcwd())
+
+    if want_json:
+        if match:
+            print(json.dumps({
+                "key": match["key"],
+                "github": match.get("github"),
+                "matched_by": match["matched_by"],
+            }))
+        else:
+            print(json.dumps({"key": None}))
+        return 0
+
+    if match:
+        how = "local clone path" if match["matched_by"] == "local" else "git remote"
+        print(f"Resolved to repo '{match['key']}' (matched by {how}).")
+        return 0
+
+    print("No configured repo matches the current directory.")
+    return 1

package/skills/work-plan/lib/cwd_repo.py

@@ -0,0 +1,133 @@
+"""Resolve a directory to a configured repo (config key + GitHub slug).
+
+Shared substrate for two sibling features: `brief` cwd auto-scope (#358) and the
+VS Code viewer auto-focus (#357). Both need the same "which configured repo is
+this directory?" answer, so it lives here once — exposed to the viewer through
+the `which-repo` command and called directly by `brief`.
+
+Resolution order: the local clone path is the primary signal (it's the most
+explicit thing the user configured); the git `origin` remote is the fallback for
+repos registered with `local: null`. If both resolve but to different keys (which
+shouldn't happen in practice), the local-path key wins.
+
+Read-only and never raises — every git call goes through the bounded `_git`
+wrapper, which returns None on failure, and a no-match returns None so callers
+fall back to their current all-repos behavior unchanged.
+"""
+import re
+from pathlib import Path
+from typing import Optional
+
+from lib.git_state import _git
+
+
+def _normalize_remote_url(url: str) -> Optional[str]:
+    """Normalize a git remote URL to a lowercased `org/repo` slug, or None.
+
+    Handles the forms git emits for GitHub remotes:
+      git@github.com:org/repo.git        -> org/repo   (scp-like)
+      ssh://git@github.com/org/repo.git  -> org/repo
+      https://github.com/org/repo.git    -> org/repo
+      https://github.com/org/repo        -> org/repo
+
+    A trailing `.git`, surrounding whitespace, and trailing slashes are stripped.
+    Returns None for anything it can't parse into a host-path.
+    """
+    if not url:
+        return None
+    u = url.strip()
+
+    # scp-like syntax: [user@]host:path  (no scheme, single colon before path)
+    m = re.match(r"^[\w.+-]+@[\w.-]+:(.+)$", u)
+    if m:
+        path = m.group(1)
+    else:
+        # url syntax: scheme://[user@]host[:port]/path
+        m = re.match(r"^[\w.+-]+://(?:[^/@]+@)?[^/]+/(.+)$", u)
+        if not m:
+            return None
+        path = m.group(1)
+
+    path = path.strip().strip("/")
+    if path.endswith(".git"):
+        path = path[:-len(".git")]
+    path = path.strip("/")
+    return path.lower() or None
+
+
+def _toplevel(start_dir) -> Optional[Path]:
+    """The git work-tree root containing `start_dir`, resolved absolute, or None.
+
+    Uses `rev-parse --show-toplevel` (not the raw dir) so resolution works from
+    any nested subdirectory and a configured `local` that merely *contains* the
+    cwd can't false-match.
+    """
+    proc = _git(start_dir, "rev-parse", "--show-toplevel")
+    if proc is None or proc.returncode != 0:
+        return None
+    out = proc.stdout.strip()
+    if not out:
+        return None
+    try:
+        return Path(out).resolve()
+    except OSError:
+        return None
+
+
+def _origin_slug(start_dir) -> Optional[str]:
+    """The `org/repo` slug of `start_dir`'s `origin` remote, or None."""
+    proc = _git(start_dir, "remote", "get-url", "origin")
+    if proc is None or proc.returncode != 0:
+        return None
+    return _normalize_remote_url(proc.stdout.strip())
+
+
+def resolve_repo_for_dir(cfg: dict, start_dir) -> Optional[dict]:
+    """Resolve `start_dir` to a single configured repo.
+
+    Returns `{"key", "github", "matched_by"}` (matched_by is "local" or
+    "remote") when exactly one repo matches, else None. None covers: no repos
+    configured, dir isn't a git repo, no match, or an ambiguous (>1) match —
+    callers treat all of these as "don't auto-scope."
+    """
+    repos = cfg.get("repos") or {}
+    if not repos:
+        return None
+
+    # --- local clone path (primary) ---
+    top = _toplevel(start_dir)
+    if top is not None:
+        local_keys = []
+        for key, entry in repos.items():
+            local_raw = (entry or {}).get("local")
+            if not local_raw:
+                continue
+            try:
+                cfg_root = Path(local_raw).expanduser().resolve()
+            except OSError:
+                continue
+            if cfg_root == top:
+                local_keys.append(key)
+        if len(local_keys) == 1:
+            key = local_keys[0]
+            return {"key": key,
+                    "github": (repos[key] or {}).get("github"),
+                    "matched_by": "local"}
+        if len(local_keys) > 1:
+            # Ambiguous local config — refuse to guess.
+            return None
+
+    # --- git origin remote (fallback) ---
+    slug = _origin_slug(start_dir)
+    if slug:
+        remote_keys = [
+            key for key, entry in repos.items()
+            if entry and entry.get("github") and entry["github"].lower() == slug
+        ]
+        if len(remote_keys) == 1:
+            key = remote_keys[0]
+            return {"key": key,
+                    "github": repos[key].get("github"),
+                    "matched_by": "remote"}
+
+    return None

package/skills/work-plan/lib/drift.py

@@ -23,8 +23,13 @@ def detect_drift(body: str, github_issues: list[dict]) -> list[dict]:
                 continue
             gh_state = state_by_num[num]
             looks_closed = any(k in body_status for k in ("✅", "shipped", "merged", "closed"))
-            looks_open = "🔲" in body_status or "open" in body_status
 
+            # Asymmetric by design: CLOSED is terminal, so a closed issue whose
+            # row doesn't explicitly read closed (open marker, ambiguous, or empty)
+            # is drift. OPEN is not terminal — an open issue legitimately sits in
+            # many states (in-progress, blocked, todo), so only an explicit closed
+            # marker contradicts it. A broad open-side check (`not looks_open`)
+            # would false-positive every in-progress row, which is why we don't.
             if gh_state == "CLOSED" and not looks_closed:
                 drift.append({"issue": num, "body_status": body_status, "github_state": "CLOSED"})
             elif gh_state == "OPEN" and looks_closed:

package/skills/work-plan/lib/export_model.py

@@ -1,6 +1,6 @@
 """Build the versioned viewer export structure from tracks + fetched issues."""
 from lib.github_state import format_assignees, short_milestone
-from lib.next_up import resolve_next_up_order
+from lib.next_up import resolve_next_up_order, suggest_next_up
 
 SCHEMA = 1
 
@@ -86,7 +86,7 @@ def normalize_issue(i: dict, in_progress: bool = False,
 def build_export(tracks, issues_by_track, visibility, now: str,
                  untracked_by_repo=None, config_repos=None,
                  plan_by_track=None, hot_by_track=None,
-                 next_up_default=None) -> dict:
+                 next_up_default=None, tier_duplicates=None) -> dict:
     plan_by_track = plan_by_track or {}
     hot_by_track = hot_by_track or {}
     out = {"schema": SCHEMA, "generated_at": now, "tracks": []}
@@ -110,9 +110,22 @@ def build_export(tracks, issues_by_track, visibility, now: str,
         issues.sort(key=lambda i: milestone_sort_key(i, milestone_alignment))
         opened = sum(1 for i in issues if i["state"] == "open")
         closed_nums = {i["number"] for i in issues if i["state"] == "closed"}
-        next_up = [n for n in (t.meta.get("next_up") or []) if n not in closed_nums]
         track_path = getattr(t, "path", None)
-        next_up_preset_name, _ = resolve_next_up_order(t.meta, next_up_default)
+        next_up_preset_name, next_up_order = resolve_next_up_order(t.meta, next_up_default)
+        # When `next_up_auto: true`, derive the next-up list live from the track's
+        # open issues using the resolved ranking preset — same as brief/orient —
+        # instead of reading the curated `next_up` frontmatter list. This is what
+        # surfaces the ranking in the viewer (which only reads this export). #326.
+        if t.meta.get("next_up_auto") and raw:
+            in_progress_set = {i["number"] for i in raw if issue_in_progress(i, hot)}
+            next_up = suggest_next_up(
+                raw, t.meta.get("blockers") or [],
+                track_milestone=milestone_alignment or None,
+                in_progress_nums=in_progress_set,
+                order=next_up_order,
+            )
+        else:
+            next_up = [n for n in (t.meta.get("next_up") or []) if n not in closed_nums]
         out["tracks"].append({
             "name": t.name,
             "repo": t.repo,
@@ -140,6 +153,11 @@ def build_export(tracks, issues_by_track, visibility, now: str,
             "plan": plan_by_track.get(t.name),
             # Effective next_up ranking preset for this track (#326 Phase 2).
             "next_up_preset": next_up_preset_name,
+            # True when the track has `next_up_auto: true` set in its frontmatter,
+            # meaning the next-up list is auto-derived from the ranking preset (#326).
+            # Reflects the SETTING, not whether derivation actually ran (so the
+            # viewer toggle shows On even when a track has zero open issues).
+            "next_up_auto": bool(t.meta.get("next_up_auto")),
         })
     out["untracked"] = [
         {"repo": repo, "issues": [normalize_issue(r) for r in rows]}
@@ -151,4 +169,9 @@ def build_export(tracks, issues_by_track, visibility, now: str,
     # the starting point for adding fresh tracks. Each entry:
     # {folder, repo(slug), local, has_local, visibility}.
     out["repos"] = list(config_repos or [])
+    # Shared/private tier duplicates (#361, additive): tracks that exist in both
+    # a repo's shared .work-plan/ and the private notes_root tier. Read-only
+    # health signal for the viewer; resolved with the `dedupe-tiers` CLI verb.
+    # Each entry: {repo, folder, name, shared_path, private_path, safe}.
+    out["tier_duplicates"] = list(tier_duplicates or [])
     return out

package/skills/work-plan/lib/tracks.py

@@ -1,4 +1,5 @@
 """Discover tracks under notes_root and shared .work-plan/ dirs."""
+import re
 import sys
 from dataclasses import dataclass, field
 from pathlib import Path
@@ -74,9 +75,11 @@ def discover_tracks(cfg: dict) -> list[Track]:
     for t in private:
         key = (t.repo, t.name)
         if key in shared_keys:
+            hint = f" --repo={t.folder}" if t.folder else ""
             print(
                 f"WARN: track {t.name!r} (repo={t.repo!r}) exists in both shared"
-                f" ({shared_keys[key].path}) and private ({t.path}); using shared.",
+                f" ({shared_keys[key].path}) and private ({t.path}); using shared."
+                f" → resolve with `/work-plan dedupe-tiers{hint}`.",
                 file=sys.stderr,
             )
         else:
@@ -85,6 +88,63 @@ def discover_tracks(cfg: dict) -> list[Track]:
     return merged
 
 
+def issue_refs(track: "Track") -> set:
+    """All GitHub issue numbers a track references: the union of its frontmatter
+    `github.issues` list and every `#NNNN` token in its body. Used by
+    dedupe-tiers as the no-data-loss invariant — a private copy is only safe to
+    drop when its issue refs are a subset of the shared twin's.
+    """
+    refs: set = set()
+    fm_issues = (track.meta.get("github") or {}).get("issues") or []
+    for n in fm_issues:
+        try:
+            refs.add(int(n))
+        except (TypeError, ValueError):
+            continue
+    for m in re.finditer(r"#(\d+)", track.body or ""):
+        refs.add(int(m.group(1)))
+    return refs
+
+
+def find_tier_duplicates(cfg: dict) -> list:
+    """Return (shared, private) Track pairs that collide on (repo, name) across
+    BOTH the active and archived tiers. Unlike discover_tracks, this does NOT
+    print a warning and does NOT drop the private side — it hands both copies to
+    the caller (dedupe-tiers) so the orphan can be inspected and removed.
+    """
+    pairs: list = []
+
+    # A duplicate requires a PRIVATE copy, which lives under notes_root. With no
+    # notes_root configured there can be no private tier and thus no duplicates —
+    # return early (also keeps the helper safe to call with a bare cfg).
+    if not cfg.get("notes_root"):
+        return pairs
+
+    shared_active = {(t.repo, t.name): t
+                     for t in _discover_shared_tracks(cfg, include_archive=False)}
+    for t in _discover_private_tracks(cfg, include_archive=False):
+        s = shared_active.get((t.repo, t.name))
+        if s is not None:
+            pairs.append((s, t))
+
+    shared_arch = {(t.repo, t.name): t
+                   for t in _discover_shared_tracks(cfg, include_archive=True,
+                                                    archive_only=True)}
+    notes_root = Path(cfg["notes_root"]).expanduser()
+    if notes_root.exists():
+        for md_path in sorted(notes_root.rglob("*.md")):
+            if "archive" not in md_path.parts:
+                continue
+            if md_path.name.startswith((".", "_", "-")):
+                continue
+            t = _build_track(md_path, notes_root, cfg)
+            s = shared_arch.get((t.repo, t.name))
+            if s is not None:
+                pairs.append((s, t))
+
+    return pairs
+
+
 def filter_tracks_by_repo(tracks: list[Track], key: str) -> list[Track]:
     """Filter tracks by repo. Matches the config-key folder name OR the
     `org/repo` GitHub slug, so users can pass either. Case-insensitive."""
@@ -176,10 +236,12 @@ def discover_archived_tracks(cfg: dict) -> list[Track]:
     for t in private_archived:
         key = (t.repo, t.name)
         if key in shared_keys:
+            hint = f" --repo={t.folder}" if t.folder else ""
             print(
                 f"WARN: archived track {t.name!r} (repo={t.repo!r}) exists in"
                 f" both shared ({shared_keys[key].path}) and private"
-                f" ({t.path}); using shared.",
+                f" ({t.path}); using shared."
+                f" → resolve with `/work-plan dedupe-tiers{hint}`.",
                 file=sys.stderr,
             )
         else:

package/skills/work-plan/tests/test_brief_autoscope.py

@@ -0,0 +1,126 @@
+"""brief cwd auto-scope (#358 Phase 2).
+
+Exercises brief.run()'s scope resolution with the resolver, config loader,
+track discovery, and the archived-reopen pass all mocked — so no network/git.
+Tracks are inactive (status 'shipped') so the render loop stays trivial; we
+assert behavior through the banner text and the `repo_key` threaded into
+`_surface_archived_reopens` (which is exactly the value used to scope both the
+track list and the archived callouts).
+"""
+import io
+import sys
+import types
+import unittest
+from contextlib import redirect_stdout
+from pathlib import Path
+from unittest import mock
+
+SKILL_ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(SKILL_ROOT))
+
+from commands import brief
+
+
+def _track(folder, repo):
+    return types.SimpleNamespace(
+        has_frontmatter=True,
+        meta={"status": "shipped"},   # inactive → no per-track render
+        needs_init=False,
+        needs_filing=False,
+        folder=folder,
+        repo=repo,
+        path=Path(f"/notes/{folder}/{folder}.md"),
+    )
+
+
+CFG = {"repos": {
+    "work-plan-toolkit": {"local": "/code/wpt", "github": "stylusnexus/work-plan-toolkit"},
+    "defect-scan": {"local": "/code/ds", "github": "stylusnexus/defect-scan"},
+}}
+
+TRACKS = [
+    _track("work-plan-toolkit", "stylusnexus/work-plan-toolkit"),
+    _track("defect-scan", "stylusnexus/defect-scan"),
+]
+
+BANNER = "Scoped to repo"
+
+
+def _run(args, cfg=None, resolve_return=mock.DEFAULT):
+    """Run brief.run(args) with collaborators mocked. Returns (stdout, archived_mock, resolve_mock)."""
+    cfg = CFG if cfg is None else cfg
+    buf = io.StringIO()
+    with mock.patch.object(brief, "load_config", return_value=cfg), \
+         mock.patch.object(brief, "discover_tracks", return_value=list(TRACKS)), \
+         mock.patch.object(brief, "_surface_archived_reopens") as archived, \
+         mock.patch.object(brief, "resolve_repo_for_dir") as resolve:
+        if resolve_return is not mock.DEFAULT:
+            resolve.return_value = resolve_return
+        with redirect_stdout(buf):
+            brief.run(args)
+    return buf.getvalue(), archived, resolve
+
+
+def _archived_repo_key(archived):
+    self_call = archived.call_args
+    return self_call.kwargs.get("repo_key")
+
+
+class BriefAutoScopeTest(unittest.TestCase):
+    # --- auto-detect on (default) -------------------------------------------
+
+    def test_autoscope_prints_banner_and_scopes(self):
+        out, archived, _ = _run(
+            [], resolve_return={"key": "work-plan-toolkit",
+                                "github": "stylusnexus/work-plan-toolkit",
+                                "matched_by": "local"})
+        self.assertIn(BANNER, out)
+        self.assertIn("work-plan-toolkit", out)
+        # archived-reopen pass scoped to the same detected key
+        self.assertEqual(_archived_repo_key(archived), "work-plan-toolkit")
+
+    def test_archived_reopens_scoped_to_detected_repo(self):
+        _, archived, _ = _run(
+            [], resolve_return={"key": "defect-scan",
+                                "github": "stylusnexus/defect-scan",
+                                "matched_by": "local"})
+        self.assertEqual(_archived_repo_key(archived), "defect-scan")
+
+    def test_banner_printed_exactly_once(self):
+        out, _, _ = _run(
+            [], resolve_return={"key": "work-plan-toolkit",
+                                "github": "stylusnexus/work-plan-toolkit",
+                                "matched_by": "local"})
+        self.assertEqual(out.count(BANNER), 1)
+
+    def test_no_match_shows_all_no_banner(self):
+        out, archived, _ = _run([], resolve_return=None)
+        self.assertNotIn(BANNER, out)
+        self.assertIsNone(_archived_repo_key(archived))
+
+    # --- explicit --repo / escape hatch -------------------------------------
+
+    def test_repo_all_shows_everything_no_banner_no_autodetect(self):
+        out, archived, resolve = _run(["--repo=all"])
+        self.assertNotIn(BANNER, out)
+        self.assertIsNone(_archived_repo_key(archived))
+        resolve.assert_not_called()   # --repo=all must short-circuit auto-detect
+
+    def test_explicit_repo_scopes_without_banner_or_autodetect(self):
+        out, archived, resolve = _run(["--repo=defect-scan"])
+        self.assertNotIn(BANNER, out)
+        self.assertEqual(_archived_repo_key(archived), "defect-scan")
+        resolve.assert_not_called()
+
+    # --- opt-out -------------------------------------------------------------
+
+    def test_optout_disables_autoscope(self):
+        cfg = {"repos": CFG["repos"], "brief_auto_scope": False}
+        out, archived, resolve = _run([], cfg=cfg)
+        self.assertNotIn(BANNER, out)
+        self.assertIsNone(_archived_repo_key(archived))
+        resolve.assert_not_called()
+
+
+if __name__ == "__main__":
+    unittest.main()