@deftai/directive-content 0.55.2 → 0.56.0

package/scripts/triage_welcome.py

@@ -0,0 +1,1178 @@
+#!/usr/bin/env python3
+"""``task triage:welcome`` 6-phase onboarding ritual (#1143).
+
+Consolidates triage bootstrap, subscription scope, wipCap, WIP relief,
+summary, and triage-skill handoff into one idempotent walkthrough.
+D4 (#1124) will replace the hand-rolled wipCap writer with the dedicated
+policy-set surface once that parallel-wave work merges.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import sys
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+# Make sibling scripts importable when invoked as
+# ``python scripts/triage_welcome.py``.
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+from _lifecycle_hygiene import (  # noqa: E402  (sibling import after sys.path tweak)
+    detect_lifecycle_nudges,
+    record_tech_debt_acceptance,
+    resolve_epic_thresholds,
+)
+from _project_definition_io import (  # noqa: E402  (after sys.path tweak)
+    atomic_write_project_definition,
+    project_definition_mutation_lock,
+)
+from framework_commands import (  # noqa: E402
+    format_framework_command,
+    run_framework_command,
+)
+from policy import (  # noqa: E402  (sibling import after sys.path tweak)
+    count_pending_decisions,
+    pending_decisions_nudge_line,
+)
+
+# UTF-8 self-reconfigure -- the prompts emit ⊗ / · / arrows / checkmarks.
+for _stream in (sys.stdout, sys.stderr):
+    if hasattr(_stream, "reconfigure"):
+        with contextlib.suppress(AttributeError, ValueError):
+            _stream.reconfigure(encoding="utf-8", errors="replace")
+
+
+# ---------------------------------------------------------------------------
+# Public constants
+# ---------------------------------------------------------------------------
+
+#: Filesystem-relative location of the PROJECT-DEFINITION vBRIEF.
+PROJECT_DEFINITION_REL_PATH = "vbrief/PROJECT-DEFINITION.vbrief.json"
+
+#: Canonical cache root + source (mirrors ``scripts/triage_summary.py``).
+CACHE_DIR_NAME: str = ".deft-cache"
+CACHE_SOURCE: str = "github-issue"
+
+#: Canonical "bootstrap finished" audit log (#1244). Mirrors
+#: :data:`scripts.preflight_cache.CANDIDATES_RELPATH` and
+#: :data:`scripts.triage_bootstrap.AUDIT_LOG_RELPATH`. Downstream verbs
+#: (`task triage:queue`, `task verify:cache-fresh`) all key off this
+#: file's presence rather than the raw ``.deft-cache/`` entry count, so
+#: welcome's Phase 3 idempotency probe MUST use the same signal.
+CANDIDATES_RELPATH: tuple[str, ...] = ("vbrief", ".eval", "candidates.jsonl")
+
+#: vBRIEF lifecycle folders that contribute to the WIP count.
+WIP_LIFECYCLE_DIRS: tuple[str, ...] = ("pending", "active")
+
+#: Audit log written by :func:`write_triage_scope` and :func:`write_wip_cap`.
+#: Mirrors the location :mod:`policy` uses for branch-policy audit so
+#: a future operator can grep one file for every policy mutation.
+AUDIT_LOG_REL_PATH: str = "meta/policy-changes.log"
+
+#: Default WIP cap per umbrella #1119 Current Shape v3 (comment 4471269010).
+#: The legacy issue-body wording (``12``) is superseded; see #1124 / D4.
+DEFAULT_WIP_CAP: int = 10
+
+#: WIP-relief preview default age window (days). Issue body cites 30; the
+#: companion D1 (#1121) default is 45 -- N3 honours the issue-body number
+#: because welcome's job is consolidation, not policy. Override via the
+#: relief prompt's `--older-than-days N` follow-up.
+DEFAULT_RELIEF_AGE_DAYS: int = 30
+
+#: Canonical pointer to the triage skill (#1130 / D6).
+TRIAGE_SKILL_PATH: str = "skills/deft-directive-triage/SKILL.md"
+
+#: Path to the framework's deterministic-questions contract.
+DETERMINISTIC_QUESTIONS_PATH: str = "contracts/deterministic-questions.md"
+
+#: Subscription preset rule shapes -- frozen per the issue body. The
+#: framework default per the umbrella §12 framework-vs-consumer-config
+#: boundary is ``[{"rule": "all-open"}]`` (Small). Mid and Mega are
+#: consumer-agnostic generic shapes; deft-specific values live in
+#: #1186 consumer-example (Wave-2e, intentionally separate).
+SUBSCRIPTION_PRESETS: dict[str, list[dict[str, Any]]] = {
+    "small": [{"rule": "all-open"}],
+    "mid": [
+        {
+            "rule": "labels",
+            "any-of": ["urgent", "breaking", "security", "p0", "p1"],
+        },
+        {"rule": "opened-since", "duration": "60d"},
+    ],
+    "mega": [
+        {"rule": "explicit-watch", "issues": []},
+        {"rule": "referenced-by-vbrief", "scope": "active"},
+    ],
+}
+
+#: Audit sigil written to ``meta/policy-changes.log`` for triage-welcome.
+WELCOME_AUDIT_TAG: str = "triage-welcome"
+
+
+# ---------------------------------------------------------------------------
+# Dataclass: detected prior state (Phase 1 output)
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class PriorState:
+    """Snapshot of the state probes Phase 1 needs.
+
+    ``audit_log_present`` is the canonical "bootstrap finished" signal
+    (#1244); the raw ``.deft-cache/`` entry count is diagnostic only.
+    """
+
+    triage_scope_set: bool
+    triage_scope_summary: str  # human-readable label (e.g. "unset" / "Mid")
+    cache_empty: bool
+    cache_entry_count: int
+    wip_cap_set: bool
+    wip_cap: int  # current value OR the DEFAULT_WIP_CAP fallback
+    wip_count: int  # pending/ + active/
+    audit_log_present: bool  # vbrief/.eval/candidates.jsonl exists (#1244)
+    # Pending human-clearance backlog count (#1419 Slice 5). Defaulted so any
+    # legacy direct construction stays valid; detect_prior_state always sets it.
+    pending_decisions: int = 0
+
+
+# ---------------------------------------------------------------------------
+# Helpers: PROJECT-DEFINITION reader + audit-log writer
+# ---------------------------------------------------------------------------
+
+
+def project_definition_path(project_root: Path | None = None) -> Path:
+    """Absolute path to ``vbrief/PROJECT-DEFINITION.vbrief.json``."""
+    root = project_root or Path.cwd()
+    return root / PROJECT_DEFINITION_REL_PATH
+
+
+def _load_project_definition(project_root: Path) -> dict[str, Any] | None:
+    """Tolerant reader -- returns None on missing / malformed file."""
+    path = project_definition_path(project_root)
+    if not path.is_file():
+        return None
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, UnicodeDecodeError, json.JSONDecodeError):
+        return None
+    return data if isinstance(data, dict) else None
+
+
+def _utc_iso(dt: datetime | None = None) -> str:
+    return (dt or datetime.now(UTC)).astimezone(UTC).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def append_audit_entry(project_root: Path, entry: str) -> Path:
+    """Append a one-line audit entry to ``meta/policy-changes.log``.
+
+    Atomic append-mode write (mirrors :func:`policy.append_audit_log`) so
+    concurrent welcome runs cannot lose entries on a torn write.
+    """
+    log_path = project_root / AUDIT_LOG_REL_PATH
+    log_path.parent.mkdir(parents=True, exist_ok=True)
+    line = f"{_utc_iso()} {entry}\n"
+    if not log_path.exists():
+        header = (
+            "# meta/policy-changes.log -- audit trail for "
+            "PROJECT-DEFINITION plan.policy.* mutations (#746 / #1143)\n"
+        )
+        log_path.write_text(header, encoding="utf-8")
+    with open(log_path, "a", encoding="utf-8") as handle:
+        handle.write(line)
+    return log_path
+
+
+# ---------------------------------------------------------------------------
+# Phase 1 -- prior-state detection
+# ---------------------------------------------------------------------------
+
+
+def _count_cache_entries(project_root: Path) -> int:
+    base = project_root / CACHE_DIR_NAME / CACHE_SOURCE
+    if not base.is_dir():
+        return 0
+    count = 0
+    for owner_dir in base.iterdir():
+        if not owner_dir.is_dir():
+            continue
+        for repo_dir in owner_dir.iterdir():
+            if not repo_dir.is_dir():
+                continue
+            for entry in repo_dir.iterdir():
+                if entry.is_dir() and entry.name.isdecimal():
+                    count += 1
+    return count
+
+
+def candidates_log_path(project_root: Path) -> Path:
+    """Absolute path to ``vbrief/.eval/candidates.jsonl`` (#1244)."""
+    return project_root.joinpath(*CANDIDATES_RELPATH)
+
+
+def _audit_log_present(project_root: Path) -> bool:
+    """True iff ``vbrief/.eval/candidates.jsonl`` exists (zero-length OK)."""
+    return candidates_log_path(project_root).is_file()
+
+
+def _count_wip(project_root: Path) -> int:
+    total = 0
+    root = project_root / "vbrief"
+    for sub in WIP_LIFECYCLE_DIRS:
+        folder = root / sub
+        if not folder.is_dir():
+            continue
+        total += sum(
+            1
+            for child in folder.iterdir()
+            if child.is_file() and child.name.endswith(".vbrief.json")
+        )
+    return total
+
+
+def _summarize_scope(rules: list[dict[str, Any]] | None) -> tuple[bool, str]:
+    """Return ``(set, label)`` for the operator-visible scope display."""
+    if not rules:
+        return False, "unset (default applied -- all-open)"
+    if rules == SUBSCRIPTION_PRESETS["small"]:
+        return True, "Small (all-open)"
+    if rules == SUBSCRIPTION_PRESETS["mid"]:
+        return True, "Mid (curated labels + opened-since 60d)"
+    # Compare without the (possibly populated) explicit-watch issues list.
+    mega_baseline = [dict(r) for r in SUBSCRIPTION_PRESETS["mega"]]
+    if len(rules) == len(mega_baseline):
+        match = True
+        for live, baseline in zip(rules, mega_baseline, strict=False):
+            if live.get("rule") != baseline.get("rule"):
+                match = False
+                break
+        if match:
+            return True, "Mega (explicit-watch + referenced-by-vbrief)"
+    return True, f"custom ({len(rules)} rule(s))"
+
+
+def detect_prior_state(project_root: Path) -> PriorState:
+    """Read every Phase 1 probe in one pass. Pure -- no writes."""
+    data = _load_project_definition(project_root) or {}
+    plan = data.get("plan") if isinstance(data, dict) else None
+    policy = plan.get("policy") if isinstance(plan, dict) else None
+    raw_scope = policy.get("triageScope") if isinstance(policy, dict) else None
+    scope_rules = raw_scope if isinstance(raw_scope, list) else None
+
+    raw_cap = policy.get("wipCap") if isinstance(policy, dict) else None
+    if isinstance(raw_cap, int) and not isinstance(raw_cap, bool) and raw_cap >= 0:
+        wip_cap = raw_cap
+        wip_cap_set = True
+    else:
+        wip_cap = DEFAULT_WIP_CAP
+        wip_cap_set = False
+
+    scope_set, scope_label = _summarize_scope(scope_rules)
+    cache_count = _count_cache_entries(project_root)
+    return PriorState(
+        triage_scope_set=scope_set,
+        triage_scope_summary=scope_label,
+        cache_empty=cache_count == 0,
+        cache_entry_count=cache_count,
+        wip_cap_set=wip_cap_set,
+        wip_cap=wip_cap,
+        wip_count=_count_wip(project_root),
+        audit_log_present=_audit_log_present(project_root),
+        pending_decisions=count_pending_decisions(project_root),
+    )
+
+
+def pending_decisions_oneliner(project_root: Path) -> str:
+    """Return the budgeted pending-human-decisions backlog one-liner (#1419 S5).
+
+    Surfaces the count derived from the durable audit log
+    (``vbrief/.audit/pending-human-decisions.jsonl``). When the backlog exceeds
+    the Tier-1 threshold the nudge text is appended so a session-start caller
+    can emit one actionable line. The headline is returned even when the
+    backlog is empty so callers may choose to show or suppress it. Additive /
+    localized so a later slice can wire it into the default-mode surface.
+    """
+    count = count_pending_decisions(project_root)
+    headline = f"[clearance] pending human decisions: {count}"
+    nudge = pending_decisions_nudge_line(count)
+    if not nudge:
+        return headline
+    return f"{headline} -- {nudge}"
+
+
+# ---------------------------------------------------------------------------
+# Phase 2 -- subscription scope writer (typed-flag pattern via #1131 surface)
+# ---------------------------------------------------------------------------
+
+
+def write_triage_scope(
+    project_root: Path,
+    rules: list[dict[str, Any]],
+    *,
+    preset_label: str,
+    actor: str = WELCOME_AUDIT_TAG,
+) -> tuple[bool, str]:
+    """In-place set ``plan.policy.triageScope`` to *rules*.
+
+    Returns ``(changed, audit_entry)``. Audit entry is appended whether
+    the value changed or not (the trail matters for re-run analysis).
+
+    Schema validation runs through ``scripts.triage_scope.validate_scope_rules``
+    when importable; a validation failure surfaces a clear error and refuses
+    the write. Pure-stdlib otherwise so the script runs without uv on PATH.
+    """
+    path = project_definition_path(project_root)
+    if not path.is_file():
+        raise FileNotFoundError(f"PROJECT-DEFINITION not found at {path}")
+
+    # Best-effort schema check via D12's validator. Tolerant of ImportError
+    # ONLY (e.g. triage_scope not yet on sys.path because uv sync has not
+    # run). Any other exception class -- SyntaxError, AttributeError, name
+    # collisions, validation ValueErrors -- MUST propagate so the caller
+    # learns about the real bug instead of silently dropping schema checks.
+    _validate = None
+    try:
+        from triage_scope import (  # type: ignore[import-not-found]
+            validate_scope_rules as _validate,
+        )
+    except ImportError:
+        _validate = None
+    if _validate is not None:
+        errors, _warnings = _validate(rules)
+        if errors:
+            joined = "; ".join(errors)
+            raise ValueError(f"plan.policy.triageScope schema errors: {joined}")
+
+    with project_definition_mutation_lock(project_root):
+        data = json.loads(path.read_text(encoding="utf-8"))
+        plan = data.setdefault("plan", {})
+        if not isinstance(plan, dict):
+            raise ValueError("PROJECT-DEFINITION 'plan' is not an object")
+        policy = plan.setdefault("policy", {})
+        if not isinstance(policy, dict):
+            raise ValueError("plan.policy is not an object")
+        previous = policy.get("triageScope")
+        policy["triageScope"] = rules
+        atomic_write_project_definition(path, data)
+
+        changed = previous != rules
+        audit_parts = [
+            f"actor={actor}",
+            "field=plan.policy.triageScope",
+            f"preset={preset_label}",
+            f"rule_count={len(rules)}",
+            f"changed={'true' if changed else 'false'}",
+        ]
+        audit_entry = " ".join(audit_parts)
+        append_audit_entry(project_root, audit_entry)
+        return changed, audit_entry
+
+
+# ---------------------------------------------------------------------------
+# Phase 4 -- wipCap writer (hand-rolled until D4 / #1124 lands its surface)
+# ---------------------------------------------------------------------------
+
+
+def write_wip_cap(
+    project_root: Path,
+    wip_cap: int,
+    *,
+    actor: str = WELCOME_AUDIT_TAG,
+) -> tuple[bool, str]:
+    """Persist, omit, or clear ``plan.policy.wipCap`` per #1250.
+
+    Matrix: fresh default-confirm => no JSON write and no audit row;
+    existing override reset to default => remove the typed field and
+    audit cleanup; non-default values => materialize/audit the typed
+    override, with ``changed=false`` for same-value re-confirm.
+
+    Hand-rolled until D4 (#1124) lands the dedicated policy-set surface.
+    """
+    if not isinstance(wip_cap, int) or isinstance(wip_cap, bool) or wip_cap < 1:
+        raise ValueError(f"wipCap must be a positive int, got {wip_cap!r}")
+    path = project_definition_path(project_root)
+    if not path.is_file():
+        raise FileNotFoundError(f"PROJECT-DEFINITION not found at {path}")
+    with project_definition_mutation_lock(project_root):
+        data = json.loads(path.read_text(encoding="utf-8"))
+        plan = data.setdefault("plan", {})
+        if not isinstance(plan, dict):
+            raise ValueError("PROJECT-DEFINITION 'plan' is not an object")
+        policy = plan.setdefault("policy", {})
+        if not isinstance(policy, dict):
+            raise ValueError("plan.policy is not an object")
+        previous = policy.get("wipCap")
+
+        # Case 1: default-confirm on a fresh consumer -- the field stays
+        # omitted (#1250 / #1186 Deliverable 1). No JSON write, no audit row.
+        if previous is None and wip_cap == DEFAULT_WIP_CAP:
+            return False, ""
+
+        # Case 2: operator cleared back to the framework default -- remove the
+        # typed field so downstream resolvers report ``source=default``.
+        if previous is not None and wip_cap == DEFAULT_WIP_CAP:
+            del policy["wipCap"]
+            atomic_write_project_definition(path, data)
+            audit_entry = (
+                f"actor={actor} field=plan.policy.wipCap "
+                f"action=cleared-to-default value={wip_cap} "
+                f"previous={previous!r} changed=true"
+            )
+            append_audit_entry(project_root, audit_entry)
+            return True, audit_entry
+
+        # Case 3: explicit non-default write (including same-value re-confirm).
+        policy["wipCap"] = wip_cap
+        atomic_write_project_definition(path, data)
+
+        changed = previous != wip_cap
+        audit_entry = (
+            f"actor={actor} field=plan.policy.wipCap "
+            f"value={wip_cap} previous={previous!r} "
+            f"changed={'true' if changed else 'false'}"
+        )
+        append_audit_entry(project_root, audit_entry)
+        return changed, audit_entry
+
+
+# ---------------------------------------------------------------------------
+# Phase 5 -- WIP-relief preview
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class ReliefPreview:
+    """Synthetic preview of a planned `scope:demote --batch` invocation."""
+
+    older_than_days: int
+    eligible_count: int
+    eligible_files: tuple[str, ...]
+    skipped_count: int
+
+
+def preview_wip_relief(
+    project_root: Path,
+    older_than_days: int = DEFAULT_RELIEF_AGE_DAYS,
+) -> ReliefPreview:
+    """Walk ``vbrief/pending/`` and classify each vBRIEF by age.
+
+    Mirrors :func:`scope_demote.batch_demote`'s eligibility check without
+    invoking the writer. Pure -- the script consumes this to render the
+    `--dry-run` preview the issue body requires before any real demote.
+    """
+    pending_dir = project_root / "vbrief" / "pending"
+    if not pending_dir.is_dir():
+        return ReliefPreview(older_than_days, 0, (), 0)
+
+    now = datetime.now(UTC)
+    eligible: list[str] = []
+    skipped = 0
+    for candidate in sorted(pending_dir.glob("*.vbrief.json")):
+        days = _days_in_pending(candidate, now)
+        if days >= older_than_days:
+            eligible.append(candidate.name)
+        else:
+            skipped += 1
+    return ReliefPreview(
+        older_than_days=older_than_days,
+        eligible_count=len(eligible),
+        eligible_files=tuple(eligible),
+        skipped_count=skipped,
+    )
+
+
+def _days_in_pending(path: Path, now: datetime) -> int:
+    """Approximate days-in-pending using ``plan.updated`` then file mtime."""
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+        plan = data.get("plan") if isinstance(data, dict) else None
+        raw = plan.get("updated") if isinstance(plan, dict) else None
+        if isinstance(raw, str):
+            text = raw.strip()
+            if text.endswith("Z"):
+                text = text[:-1] + "+00:00"
+            try:
+                stamp = datetime.fromisoformat(text)
+            except ValueError:
+                stamp = None
+            if stamp is not None:
+                delta = now - stamp.astimezone(UTC)
+                return max(0, int(delta.total_seconds() // 86400))
+    except (OSError, UnicodeDecodeError, json.JSONDecodeError):
+        pass
+    try:
+        mtime = datetime.fromtimestamp(path.stat().st_mtime, tz=UTC)
+        return max(0, int((now - mtime).total_seconds() // 86400))
+    except OSError:
+        return 0
+
+
+# ---------------------------------------------------------------------------
+# Subprocess dispatch (Phase 3 + Phase 5 + Phase 6)
+# ---------------------------------------------------------------------------
+
+
+def normalize_task_prefix(task_prefix: str | None) -> str:
+    """Normalize an optional Taskfile include prefix (``deft`` -> ``deft:``)."""
+    prefix = (task_prefix or "").strip()
+    if prefix and not prefix.endswith(":"):
+        prefix = f"{prefix}:"
+    return prefix
+
+
+def task_command_args(args: list[str], *, task_prefix: str | None = None) -> list[str]:
+    """Return task argv with *task_prefix* applied to the task name only."""
+    if not args:
+        return []
+    prefix = normalize_task_prefix(task_prefix)
+    return [f"{prefix}{args[0]}", *args[1:]]
+
+
+def format_task_command(args: list[str], *, task_prefix: str | None = None) -> str:
+    """Render an operator-facing ``task ...`` command string."""
+    return " ".join(["task", *task_command_args(args, task_prefix=task_prefix)])
+
+
+def format_welcome_command(args: list[str], *, task_prefix: str | None = None) -> str:
+    """Render the preferred command for welcome guidance (#1659)."""
+    prefix = normalize_task_prefix(task_prefix)
+    if prefix:
+        return format_framework_command(args, surface="task", task_prefix=prefix)
+    return format_framework_command(args, surface="deft")
+
+
+def _run_task(args: list[str], *, cwd: Path, task_prefix: str | None = None) -> int:
+    """Run a Deft framework verb in-process. Returns exit code; never raises."""
+    _ = task_prefix  # The no-task rail ignores Taskfile namespaces at runtime.
+    if not args:
+        return 2
+    command, *argv = args
+    result = run_framework_command(command, argv, project_root=cwd)
+    if result.stdout:
+        sys.stdout.write(result.stdout)
+    if result.stderr:
+        sys.stderr.write(result.stderr)
+    return result.code
+
+
+# ---------------------------------------------------------------------------
+# Interactive prompt helpers + CLI argparse shim live in
+# ``scripts/_triage_welcome_cli.py`` so this module stays under the
+# 500-line SHOULD ceiling from ``coding/coding.md``. The names below are
+# re-exported for backward compatibility with importers / tests that
+# reference them via ``triage_welcome.<name>``.
+# ---------------------------------------------------------------------------
+
+from _triage_welcome_cli import (  # noqa: E402,F401  (after sys.path tweak; _classify_onboarding + run_default_mode re-wrapped below)
+    FIRST_TIME_NUDGE,
+    INCOMPLETE_NUDGE_TEMPLATE,
+    PromptOutcome,
+    _classify_onboarding,
+    default_input,
+    default_output,
+    emit_oneliner,
+    prompt_int,
+    prompt_menu,
+    prompt_yes_no,
+    run_default_mode as _cli_run_default_mode,
+)
+
+# ---------------------------------------------------------------------------
+# Session-start lifecycle-hygiene nudges (#1419 Slice 6)
+# ---------------------------------------------------------------------------
+
+#: Overflow pointer appended when the budget hides additional ranked nudges.
+NUDGE_OVERFLOW_POINTER: str = "`deft capacity:show`"
+
+#: Default session-start nudge budget (RFC #1419 Nudge Budgeting: budget 1).
+DEFAULT_NUDGE_BUDGET: int = 1
+
+
+def lifecycle_nudge_lines(
+    project_root: Path, *, now: datetime | None = None
+) -> list[str]:
+    """Rendered lifecycle-hygiene nudge lines (#1419 Slice 6), Tier-ranked.
+
+    Thin adapter over :func:`_lifecycle_hygiene.detect_lifecycle_nudges` that
+    returns just the rendered one-line messages (stranded-slice Tier-1 +
+    stale-epic Tier-2), already sorted most-harmful-first. Unbudgeted -- the
+    verbose onboard readout emits all of them.
+    """
+    return [nudge.message for nudge in detect_lifecycle_nudges(project_root, now=now)]
+
+
+def session_start_nudge_lines(
+    project_root: Path,
+    *,
+    budget: int = DEFAULT_NUDGE_BUDGET,
+    now: datetime | None = None,
+) -> list[str]:
+    """Shared, budgeted session-start nudge ranking (#1419 Slice 6).
+
+    Merges the Slice-5 pending-human-decisions backlog (Tier-1) with the
+    Slice-6 lifecycle-hygiene nudges (stranded-slice Tier-1, stale-epic
+    Tier-2) into one ranked list -- ``(tier, -magnitude, id)`` -- and returns
+    at most *budget* headline lines plus a single ``+N more`` overflow pointer
+    at ``deft capacity:show`` when more nudges remain. This is the budgeted
+    default-mode surface; the full ranked list lives in ``capacity:show``.
+    """
+    ranked: list[tuple[int, int, str, str]] = []
+    count = count_pending_decisions(project_root)
+    backlog_nudge = pending_decisions_nudge_line(count)
+    if backlog_nudge:
+        # Tier-1; magnitude = backlog size (negated at sort time for desc).
+        ranked.append((1, count, "pending-decisions", backlog_nudge))
+    for nudge in detect_lifecycle_nudges(project_root, now=now):
+        ranked.append((nudge.tier, nudge.magnitude, nudge.nudge_id, nudge.message))
+    # Ranking is tier-primary (rate-of-harm), then a coarse magnitude tiebreaker,
+    # then id. NOTE (#1508 review): within a tier the magnitude units are
+    # intentionally NOT normalized in v1 -- a lifecycle nudge's magnitude is
+    # dormancy-days while the backlog's is a decision count, so dormancy-days
+    # effectively dominates same-tier ordering. That is acceptable because the
+    # budgeted surface only shows the single top headline plus a `+N more`
+    # pointer; the full, separately-grouped list lives in `deft capacity:show`.
+    ranked.sort(key=lambda item: (item[0], -item[1], item[2]))
+
+    budget = max(0, budget)
+    lines = [message for *_rest, message in ranked[:budget]]
+    overflow = len(ranked) - len(lines)
+    if overflow > 0:
+        lines.append(
+            f"  +{overflow} more lifecycle/capacity nudge(s) -- run "
+            f"{NUDGE_OVERFLOW_POINTER} for the full ranked list"
+        )
+    return lines
+
+
+def run_default_mode(
+    project_root: Path,
+    *,
+    output_fn: Callable[[str], None] | None = None,
+    write_history: bool = True,
+    now: datetime | None = None,
+    task_prefix: str | None = None,
+) -> WelcomeOutcome:
+    """Default-mode session-start surface (#1309) + budgeted nudges (#1419 S6).
+
+    Delegates to the #1309 default-mode implementation in
+    :mod:`_triage_welcome_cli` (summary one-liner + onboarding nudge), then
+    appends the budgeted shared session-start nudge ranking so the
+    lifecycle-hygiene nudges ride the same surface as the Slice-5 backlog
+    one-liner. Always advisory -- never changes the delegate's exit code.
+
+    *now* is forwarded to the lifecycle detector so callers / tests can pin a
+    deterministic clock; ``None`` uses the real clock (#1508 review).
+    """
+    out_fn = output_fn or default_output
+    outcome = _cli_run_default_mode(
+        project_root,
+        output_fn=out_fn,
+        write_history=write_history,
+        task_prefix=task_prefix,
+    )
+    for line in session_start_nudge_lines(project_root, now=now):
+        out_fn(line)
+    return outcome
+
+
+# Re-export names for callers / tests reading them off this module. Kept
+# compact (single sorted tuple) so the file stays under the 1000-line
+# MUST cap from ``coding/coding.md`` while still serving any future
+# ``from triage_welcome import *`` consumer.
+__all__ = (
+    "AUDIT_LOG_REL_PATH", "CACHE_DIR_NAME", "CACHE_SOURCE",
+    "CANDIDATES_RELPATH", "DEFAULT_NUDGE_BUDGET", "DEFAULT_RELIEF_AGE_DAYS",
+    "DEFAULT_WIP_CAP", "FIRST_TIME_NUDGE", "INCOMPLETE_NUDGE_TEMPLATE",
+    "NUDGE_OVERFLOW_POINTER", "PROJECT_DEFINITION_REL_PATH", "PriorState",
+    "PromptOutcome", "ReliefPreview", "SUBSCRIPTION_PRESETS",
+    "TRIAGE_SKILL_PATH", "WELCOME_AUDIT_TAG", "WIP_LIFECYCLE_DIRS",
+    "WelcomeOutcome", "append_audit_entry", "candidates_log_path",
+    "default_input", "default_output", "detect_lifecycle_nudges",
+    "detect_prior_state", "emit_oneliner", "lifecycle_nudge_lines", "main",
+    "pending_decisions_oneliner", "preview_wip_relief",
+    "project_definition_path", "prompt_int", "prompt_menu", "prompt_yes_no",
+    "record_tech_debt_acceptance", "resolve_epic_thresholds",
+    "format_task_command", "format_welcome_command", "normalize_task_prefix", "run_default_mode",
+    "run_welcome", "session_start_nudge_lines", "task_command_args",
+    "write_triage_scope", "write_wip_cap",
+)
+
+
+# ---------------------------------------------------------------------------
+# Ritual orchestrator
+# ---------------------------------------------------------------------------
+
+
+#: ``WelcomeOutcome.bootstrap_action`` tokens (#1244). Compare via these
+#: constants -- a rename then surfaces as a NameError at import time.
+BOOTSTRAP_ACTION_RAN = "ran"
+BOOTSTRAP_ACTION_SKIPPED_ALREADY_BOOTSTRAPPED = "skipped:already-bootstrapped"
+BOOTSTRAP_ACTION_SKIPPED_DECLINED = "skipped:declined"
+BOOTSTRAP_ACTION_SKIPPED_DRY_MODE = "skipped:dry-mode"
+
+
+@dataclass
+class WelcomeOutcome:
+    """End-of-run summary for tests / dispatcher consumers.
+
+    ``bootstrap_action`` (#1244) surfaces whether Phase 3 invoked
+    ``deft triage:bootstrap`` or skipped it (and why). One of the
+    ``BOOTSTRAP_ACTION_*`` constants above, or ``None`` if the ritual
+    exited before Phase 3 (e.g. Discuss / Back at Phase 2).
+    """
+
+    phases_run: list[int] = field(default_factory=list)
+    phases_skipped: list[int] = field(default_factory=list)
+    subscription_choice: str | None = None
+    wip_cap_choice: int | None = None
+    relief_offered: bool = False
+    relief_confirmed: bool = False
+    discussed_at_phase: int | None = None
+    exit_code: int = 0
+    bootstrap_action: str | None = None
+
+
+def run_welcome(
+    project_root: Path,
+    *,
+    input_fn: Callable[[str], str] | None = None,
+    output_fn: Callable[[str], None] | None = None,
+    run_subprocess: bool = True,
+    skip_bootstrap: bool = False,
+    task_prefix: str | None = None,
+) -> WelcomeOutcome:
+    """Execute the 6-phase ritual. Returns a structured outcome.
+
+    Phases 1-6 run inside a single ``while True`` loop so the
+    deterministic-questions ``Back`` semantic re-renders the prior
+    question (a Back at Phase 4 rewinds to Phase 2 with
+    ``force_re_prompt_*`` overriding the already-set-skip). A Discuss
+    selection returns immediately. Subprocess failures in Phases 3 and
+    5 set ``outcome.exit_code = 2``.
+
+    Phase 3 bootstrap-skip semantics (#1244): the canonical "bootstrap
+    already finished" signal is ``vbrief/.eval/candidates.jsonl`` (the
+    audit log seeded by ``deft triage:bootstrap`` step 5), NOT the raw
+    ``.deft-cache/`` entry count. When the audit log is absent the
+    ritual MUST (a) run bootstrap (the default, idempotent), (b) loudly
+    surface dry-mode suppression when ``run_subprocess=False``, or
+    (c) record an explicit operator decline via ``skip_bootstrap=True``
+    and append a visible audit entry.
+    """
+    in_fn = input_fn or default_input
+    out_fn = output_fn or default_output
+    outcome = WelcomeOutcome()
+    normalized_task_prefix = normalize_task_prefix(task_prefix)
+
+    def _display_task(args: list[str]) -> str:
+        return format_welcome_command(args, task_prefix=normalized_task_prefix)
+
+    def _run_welcome_task(args: list[str]) -> int:
+        return _run_task(args, cwd=project_root)
+
+    # ``Back`` overrides the "already set, skip" rule for ONE iteration so
+    # the operator can re-answer the question they rewound to. Consumed at
+    # the top of the corresponding phase block.
+    force_re_prompt_phase_2 = False
+    force_re_prompt_phase_4 = False
+
+    # Tracking sets prevent duplicate phases_run / phases_skipped entries
+    # when the loop revisits a phase via Back.
+    phases_run_seen: set[int] = set()
+    phases_skipped_seen: set[int] = set()
+
+    def _record_run(n: int) -> None:
+        if n not in phases_run_seen:
+            phases_run_seen.add(n)
+            outcome.phases_run.append(n)
+
+    def _record_skipped(n: int) -> None:
+        if n not in phases_skipped_seen:
+            phases_skipped_seen.add(n)
+            outcome.phases_skipped.append(n)
+
+    phase = 1
+    while phase <= 6:
+        if phase == 1:
+            out_fn("[1/6] Detecting prior state...")
+            state = detect_prior_state(project_root)
+            out_fn(f"  triageScope: {state.triage_scope_summary}")
+            out_fn(
+                f"  cache: {state.cache_entry_count} raw entry/entries "
+                f"({'empty' if state.cache_empty else 'populated'})"
+            )
+            out_fn(
+                f"  candidates.jsonl: "
+                f"{'present' if state.audit_log_present else 'absent'} "
+                f"({'/'.join(CANDIDATES_RELPATH)})"
+            )
+            if state.wip_cap_set:
+                out_fn(f"  wipCap: set ({state.wip_cap})")
+            else:
+                out_fn(
+                    f"  wipCap: unset (default applied -- {DEFAULT_WIP_CAP})"
+                )
+            out_fn(f"  WIP (pending/+active/): {state.wip_count}")
+            out_fn(f"  pending human decisions: {state.pending_decisions}")
+            backlog_nudge = pending_decisions_nudge_line(state.pending_decisions)
+            if backlog_nudge:
+                out_fn(f"  {backlog_nudge}")
+            # #1419 Slice 6: stranded-slice (Tier-1) + stale-epic (Tier-2)
+            # lifecycle-hygiene nudges, alongside the Slice 5 backlog one-liner
+            # above. The onboard readout is verbose, so emit every nudge here;
+            # the budgeted default-mode surface ranks + caps them instead.
+            for line in lifecycle_nudge_lines(project_root):
+                out_fn(f"  {line}")
+            _record_run(1)
+            phase = 2
+            continue
+
+        if phase == 2:
+            state = detect_prior_state(project_root)
+            if state.triage_scope_set and not force_re_prompt_phase_2:
+                out_fn(
+                    f"[2/6] Subscription scope already set "
+                    f"({state.triage_scope_summary}); skipping."
+                )
+                _record_skipped(2)
+                phase = 3
+                continue
+            force_re_prompt_phase_2 = False
+            sub_outcome = prompt_menu(
+                title="[2/6] Choose subscription scope:",
+                options=[
+                    ("Small -- all open issues (recommended <200)", "small"),
+                    (
+                        "Mid   -- curated labels (urgent/breaking/security/p0/p1) "
+                        "+ opened-since 60d (recommended 200-2000)",
+                        "mid",
+                    ),
+                    (
+                        "Mega  -- explicit-watch + referenced-by-vbrief only "
+                        "(recommended 2000+)",
+                        "mega",
+                    ),
+                ],
+                default_index=1,  # Mid is the canonical recommendation
+                input_fn=in_fn,
+                output_fn=out_fn,
+            )
+            if sub_outcome.discuss:
+                outcome.discussed_at_phase = 2
+                outcome.exit_code = 0
+                return outcome
+            if sub_outcome.back:
+                # Phase 2 is the first interactive prompt; Back here
+                # re-renders Phase 1 (the detection readout), which
+                # iterates the loop without changing flow.
+                out_fn(
+                    "  [back] Nothing earlier to return to; "
+                    "re-rendering Phase 1."
+                )
+                phase = 1
+                continue
+            preset_key = str(sub_outcome.value)
+            rules = SUBSCRIPTION_PRESETS[preset_key]
+            try:
+                _changed, _entry = write_triage_scope(
+                    project_root,
+                    rules,
+                    preset_label=preset_key,
+                )
+            except (FileNotFoundError, ValueError) as exc:
+                out_fn(f"  ! Failed to write plan.policy.triageScope: {exc}")
+                outcome.exit_code = 2
+                return outcome
+            out_fn(f"  Wrote plan.policy.triageScope ({preset_key})")
+            outcome.subscription_choice = preset_key
+            _record_run(2)
+            phase = 3
+            continue
+
+        if phase == 3:
+            # #1244: audit log presence (NOT raw cache count) is the
+            # canonical "bootstrap finished" signal; see run_welcome
+            # docstring for the full rationale.
+            refreshed = detect_prior_state(project_root)
+            audit_rel = "/".join(CANDIDATES_RELPATH)
+            if refreshed.audit_log_present:
+                out_fn(
+                    f"[3/6] Bootstrap audit log already present "
+                    f"({audit_rel}, {refreshed.cache_entry_count} raw cache "
+                    f"entry/entries); skipping `{_display_task(['triage:bootstrap'])}`."
+                )
+                outcome.bootstrap_action = (
+                    BOOTSTRAP_ACTION_SKIPPED_ALREADY_BOOTSTRAPPED
+                )
+                _record_skipped(3)
+            elif skip_bootstrap:
+                out_fn(
+                    f"[3/6] `{_display_task(['triage:bootstrap'])}` "
+                    "explicitly declined via --skip-bootstrap."
+                )
+                out_fn(
+                    f"  ! {audit_rel} remains absent; downstream verbs "
+                    f"(`{_display_task(['triage:queue'])}`, "
+                    f"`{_display_task(['verify:cache-fresh'])}`) "
+                    "will refuse to run."
+                )
+                out_fn(
+                    f"  ! Run `{_display_task(['triage:bootstrap'])}` separately when "
+                    "ready to populate the cache."
+                )
+                append_audit_entry(
+                    project_root,
+                    (
+                        f"actor={WELCOME_AUDIT_TAG} "
+                        "action=bootstrap-declined "
+                        "reason=explicit-skip-flag "
+                        f"audit_log={audit_rel} "
+                        "audit_log_present=false"
+                    ),
+                )
+                outcome.bootstrap_action = BOOTSTRAP_ACTION_SKIPPED_DECLINED
+                _record_skipped(3)
+            elif not run_subprocess:
+                # Test-mode -- loudly surface the cache gap so dispatchers
+                # don't mistake dry-mode for a populated cache (#1244).
+                out_fn(
+                    f"[3/6] `{_display_task(['triage:bootstrap'])}` suppressed by "
+                    "--no-subprocess (test-mode)."
+                )
+                out_fn(
+                    f"  ! {audit_rel} remains absent; downstream verbs "
+                    f"(`{_display_task(['triage:queue'])}`, "
+                    f"`{_display_task(['verify:cache-fresh'])}`) "
+                    "will refuse to run until bootstrap is invoked."
+                )
+                outcome.bootstrap_action = BOOTSTRAP_ACTION_SKIPPED_DRY_MODE
+                _record_skipped(3)
+            else:
+                # Audit log absent, no decline, subprocess enabled.
+                # Bootstrap is idempotent so re-running over a
+                # partially-populated `.deft-cache/` is safe.
+                out_fn(f"[3/6] Running `{_display_task(['triage:bootstrap'])}`...")
+                rc = _run_welcome_task(["triage:bootstrap"])
+                if rc != 0:
+                    out_fn(
+                        f"  ! `{_display_task(['triage:bootstrap'])}` exited {rc}; "
+                        "see stderr above. Setting outcome.exit_code=2 "
+                        "so the dispatcher learns the ritual hit a "
+                        "downstream failure (re-run welcome after "
+                        "fixing bootstrap to resume)."
+                    )
+                    outcome.exit_code = 2
+                outcome.bootstrap_action = BOOTSTRAP_ACTION_RAN
+                _record_run(3)
+            phase = 4
+            continue
+
+        if phase == 4:
+            state_p4 = detect_prior_state(project_root)
+            if state_p4.wip_cap_set and not force_re_prompt_phase_4:
+                out_fn(
+                    f"[4/6] wipCap already set ({state_p4.wip_cap}); skipping."
+                )
+                _record_skipped(4)
+                phase = 5
+                continue
+            force_re_prompt_phase_4 = False
+            cap_outcome = prompt_menu(
+                title="[4/6] Choose wipCap:",
+                options=[
+                    ("8 (small team)", "8"),
+                    (
+                        f"{DEFAULT_WIP_CAP} (default per umbrella Current Shape v3)",
+                        str(DEFAULT_WIP_CAP),
+                    ),
+                    ("15 (large team)", "15"),
+                    ("custom", "custom"),
+                ],
+                default_index=1,
+                input_fn=in_fn,
+                output_fn=out_fn,
+            )
+            if cap_outcome.discuss:
+                outcome.discussed_at_phase = 4
+                return outcome
+            if cap_outcome.back:
+                # Rewind to the prior interactive prompt (Phase 2). Force
+                # re-prompt even if subscription scope is already set so
+                # the operator can change their previous answer.
+                out_fn("  [back] Rewinding to Phase 2.")
+                force_re_prompt_phase_2 = True
+                phase = 2
+                continue
+            if cap_outcome.value == "custom":
+                custom = prompt_int(
+                    title="    Enter custom wipCap",
+                    default=DEFAULT_WIP_CAP,
+                    input_fn=in_fn,
+                    output_fn=out_fn,
+                )
+                if custom is None:
+                    # prompt_int returns None on either Discuss or Back; both
+                    # exit the ritual at this layer (the wipCap menu is
+                    # already the rewind target so deeper rewind is a no-op).
+                    outcome.discussed_at_phase = 4
+                    return outcome
+                cap_choice = custom
+            else:
+                cap_choice = int(str(cap_outcome.value))
+            try:
+                _changed, _entry = write_wip_cap(project_root, cap_choice)
+            except (FileNotFoundError, ValueError) as exc:
+                out_fn(f"  ! Failed to write plan.policy.wipCap: {exc}")
+                outcome.exit_code = 2
+                return outcome
+            if "action=cleared-to-default" in _entry:
+                out_fn(
+                    "  Cleared plan.policy.wipCap override "
+                    f"(inheriting framework default {cap_choice})"
+                )
+            elif _entry:
+                out_fn(f"  Wrote plan.policy.wipCap = {cap_choice}")
+            else:
+                out_fn(
+                    f"  plan.policy.wipCap = {cap_choice} "
+                    "(framework default; field not materialized)"
+                )
+            outcome.wip_cap_choice = cap_choice
+            _record_run(4)
+            phase = 5
+            continue
+
+        if phase == 5:
+            state_p5 = detect_prior_state(project_root)
+            cap = state_p5.wip_cap
+            if state_p5.wip_count <= cap:
+                out_fn(
+                    f"[5/6] WIP ({state_p5.wip_count}) within cap ({cap}); "
+                    "no relief needed."
+                )
+                _record_skipped(5)
+                phase = 6
+                continue
+            out_fn(
+                f"[5/6] WIP ({state_p5.wip_count}) exceeds cap ({cap}); "
+                "previewing relief."
+            )
+            preview = preview_wip_relief(project_root)
+            outcome.relief_offered = True
+            cmd_str = _display_task(
+                [
+                    "scope:demote",
+                    "--",
+                    "--batch",
+                    "--older-than-days",
+                    str(preview.older_than_days),
+                ]
+            )
+            out_fn("  Planned invocation (dry-run preview):")
+            out_fn(f"    {cmd_str}")
+            out_fn(
+                f"  Eligible (>= {preview.older_than_days}d in pending/): "
+                f"{preview.eligible_count} file(s); "
+                f"not eligible: {preview.skipped_count}"
+            )
+            for name in preview.eligible_files[:10]:
+                out_fn(f"    - {name}")
+            if len(preview.eligible_files) > 10:
+                out_fn(f"    ... and {len(preview.eligible_files) - 10} more")
+            confirm = prompt_yes_no(
+                title="  Apply this relief now?",
+                default_yes=False,
+                input_fn=in_fn,
+                output_fn=out_fn,
+            )
+            if confirm and preview.eligible_count > 0:
+                outcome.relief_confirmed = True
+                if run_subprocess:
+                    rc = _run_welcome_task(
+                        [
+                            "scope:demote",
+                            "--",
+                            "--batch",
+                            "--older-than-days",
+                            str(preview.older_than_days),
+                        ],
+                    )
+                    if rc != 0:
+                        out_fn(
+                            f"  ! `{_display_task(['scope:demote'])}` exited {rc}. Setting "
+                            "outcome.exit_code=2 so the dispatcher learns "
+                            "the relief hop hit a downstream failure."
+                        )
+                        outcome.exit_code = 2
+                else:
+                    out_fn(
+                        f"  [dry-mode] {_display_task(['scope:demote'])} "
+                        "subprocess suppressed by caller."
+                    )
+            else:
+                out_fn(
+                    "  Relief declined; WIP cap remains over by "
+                    f"{state_p5.wip_count - cap}."
+                )
+            _record_run(5)
+            phase = 6
+            continue
+
+        if phase == 6:
+            out_fn("[6/6] Final state:")
+            if run_subprocess:
+                _run_welcome_task(["triage:summary"])
+                # TODO(#1148 / N8): follow-up to add `_run_task(["policy:show",
+                # "--", "--changed-only"])` here once N3's PR has shipped --
+                # the inspector landed via N8 after N3 merged.
+            else:
+                out_fn(
+                    f"  [dry-mode] {_display_task(['triage:summary'])} "
+                    "subprocess suppressed by caller."
+                )
+            out_fn(
+                f"  Next: {TRIAGE_SKILL_PATH}  "
+                "(read this skill to continue triage)"
+            )
+            _record_run(6)
+            phase = 7  # exit loop
+            continue
+
+        # Defensive: unreachable under normal flow; guards against a future
+        # edit that introduces an unhandled phase value.
+        raise RuntimeError(f"run_welcome: unexpected phase value {phase!r}")
+
+    return outcome
+
+
+# ---------------------------------------------------------------------------
+# CLI entry point (argparse shim lives in _triage_welcome_cli.py).
+# The default-mode (non-onboard) helpers (#1309) live in the sibling
+# module so this file stays under the 1000-line MUST cap from
+# ``coding/coding.md`` -- they are re-imported above for backward
+# compatibility.
+# ---------------------------------------------------------------------------
+
+
+def main(argv: list[str] | None = None) -> int:
+    """CLI entry point. Delegates to :mod:`_triage_welcome_cli`."""
+    import sys as _sys
+
+    # N10 (#1150): structured --help via scripts/triage_help.REGISTRY.
+    from triage_help import intercept_help
+
+    rc = intercept_help("triage_welcome", argv)
+    if rc is not None:
+        return rc
+
+    from _triage_welcome_cli import run_cli  # local import: 1000-line cap
+
+    return run_cli(argv, _sys.modules[__name__])
+
+
+if __name__ == "__main__":
+    sys.exit(main())