@deftai/directive-content 0.55.1 → 0.56.0

package/scripts/issue_ingest.py

@@ -0,0 +1,1064 @@
+#!/usr/bin/env python3
+r"""
+issue_ingest.py -- Ingest GitHub issues into vBRIEF lifecycle folders.
+
+Every post-GA issue would otherwise live only on GitHub and reappear in the
+``task reconcile:issues`` unlinked section monotonically -- this script lets a
+maintainer (or an agent running the refinement skill) materialise an issue as a
+scope vBRIEF with origin provenance so the rest of the framework can reason
+about it. Single-issue mode fetches one issue number and writes one scope
+vBRIEF; bulk mode scans all open issues (optionally filtered by label) and
+ingests anything not already referenced by an existing vBRIEF.
+
+Usage:
+    uv run python scripts/issue_ingest.py <N> [--status proposed|pending|active]
+    uv run python scripts/issue_ingest.py --all [--label LABEL]
+                                         [--status STATUS] [--dry-run]
+    uv run python scripts/issue_ingest.py [--vbrief-dir DIR] [--repo OWNER/REPO] ...
+
+Exit codes:
+    0 -- ingest completed successfully
+    1 -- duplicate (single-issue mode; the issue already has a vBRIEF)
+    2 -- external error (missing gh, API failure, usage error)
+
+Story: #454 (task issue:ingest).
+
+Issue bodies are opaque upstream Markdown text. Never decode them through
+Python or JSON string-escape semantics after the GitHub JSON payload has been
+parsed; literal substrings such as ``\vbrief``, ``\task``, ``\n``, and
+``\u0041`` must remain literal text in ``plan.narratives.Overview``.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import subprocess
+import sys
+from pathlib import Path
+from typing import Any
+
+# Make sibling scripts importable both when run as __main__ and when imported
+# by tests that pre-populate sys.path with the ``scripts/`` directory.
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+# #1145 / N5: route the ``gh api`` round-trip in :func:`_fetch_single_issue`
+# through the source-aware shim so a future GitLab / Gitea / local consumer
+# sees ``NotImplementedError`` pointing at #445 / #935 Workstream 6 instead
+# of a confusing ``gh: command not found`` deep in the call stack. The shim
+# resolves the binary via the #884 ``ghx`` -> ``gh`` preference ladder.
+import scm  # noqa: E402 -- sibling-first path insertion above is intentional
+from _project_context import resolve_project_repo, resolve_project_root  # noqa: E402
+from _stdio_utf8 import reconfigure_stdio  # noqa: E402
+from _vbrief_build import EMITTED_VBRIEF_VERSION, TODAY, slugify  # noqa: E402
+from reconcile_issues import (  # noqa: E402
+    GITHUB_ISSUE_REF_TYPES,
+    LIFECYCLE_FOLDERS,
+    detect_repo,
+    extract_references_from_vbrief,
+    fetch_open_issues,
+    parse_issue_number,
+)
+
+# #883 unified cache surface (optional). When present we prefer the cached
+# raw.json payload over a live ``gh api`` round-trip so a Phase 0 walk that
+# pre-populated the cache (``task cache:fetch-all``) does not re-spend the
+# REST budget per issue. The import is guarded so this module imports cleanly
+# in checkouts where ``scripts/cache.py`` is not yet on the branch -- tests
+# substitute fakes via ``monkeypatch.setattr(issue_ingest, "cache", ...)``.
+try:  # pragma: no cover -- exercised once #883 Story 2 lands.
+    import cache  # type: ignore[import-not-found]  # noqa: E402
+except ImportError:  # pragma: no cover
+    cache = None  # type: ignore[assignment]
+
+reconfigure_stdio()
+
+# --- Constants --------------------------------------------------------------
+
+# Allowed target lifecycle folders for ingestion. The rest (``completed/``,
+# ``cancelled/``) are terminal states; a freshly ingested issue doesn't belong
+# there.
+INGEST_STATUSES: tuple[str, ...] = ("proposed", "pending", "active")
+
+# #1096: provenance-narrative parsers. ``_build_issue_vbrief`` emits
+# ``narratives.Origin = "Ingested from <full-URL>"`` when a browser URL
+# resolves, or ``"Ingested from issue #N"`` when no URL is available.
+# ``vBRIEFInfo.description = "Scope vBRIEF ingested from GitHub issue #N"``
+# is the secondary signal. Both shapes yield the same canonical provenance
+# issue number for the dedup pass.
+_ORIGIN_URL_RE = re.compile(
+    r"https?://github\.com/[^/\s]+/[^/\s]+/issues/(\d+)"
+)
+_ORIGIN_BARE_RE = re.compile(r"issue\s*#(\d+)", re.IGNORECASE)
+
+# Map status keyword -> (folder, plan.status) pair used in the generated
+# scope vBRIEF file.
+_STATUS_MAP: dict[str, tuple[str, str]] = {
+    "proposed": ("proposed", "proposed"),
+    "pending": ("pending", "pending"),
+    "active": ("active", "running"),
+}
+
+# #1248: body-parsing patterns. The ingester previously emitted stub-only
+# vBRIEFs (no ``Overview``, ``plan.items == []``) which forced the
+# refinement workflow to re-read the GitHub issue body by hand. The
+# patterns below extract acceptance-criteria checklists, numbered AC
+# items, and Closes / Refs / Blocked-by cross-references from the issue
+# body so downstream consumers (``deft-directive-refinement``,
+# ``task triage:queue`` dedup) have substantive content to project from.
+
+# GitHub-flavoured Markdown task-list line. Captures the marker (space /
+# x / X) and the trailing title text. The trailing ``$`` anchors against
+# trailing whitespace so a multi-line list item only contributes the
+# first line; deeper nesting / continuation lines are explicitly out of
+# scope for v1 and noted as a follow-up in the issue body.
+_CHECKBOX_RE = re.compile(
+    r"^\s*[-*+]\s+\[([ xX])\]\s+(.+?)\s*$",
+    re.MULTILINE,
+)
+
+# Heading whose text contains "Acceptance Criteria" (case-insensitive).
+# Used as the entry point for the AC-section fallback when the body
+# carries no checkbox-style task list.
+_AC_HEADING_RE = re.compile(
+    r"^(#{1,6})\s+.*\bacceptance\s+criteria\b.*$",
+    re.IGNORECASE | re.MULTILINE,
+)
+
+# Bullet- or numbered-list item. Used inside the AC section after the
+# heading match -- both ``- foo`` / ``* foo`` / ``+ foo`` and
+# ``1. foo`` / ``1) foo`` shapes are accepted.
+_LIST_ITEM_RE = re.compile(
+    r"^\s*(?:[-*+]|\d+[.)])\s+(.+?)\s*$",
+    re.MULTILINE,
+)
+
+# Closing / referencing / blocking keyword -> canonical ``x-vbrief/*``
+# reference type. Ordering is significant: ``blocked by`` is matched
+# before ``blocks`` would be (the latter is intentionally absent because
+# ``Blocks #N`` on the source issue has the inverse semantic of the
+# ingested issue being blocked). Patterns are applied against a body
+# stripped of fenced and inline code spans so Markdown examples don't
+# produce spurious cross-refs.
+_CROSS_REF_PATTERNS: tuple[tuple[str, re.Pattern[str]], ...] = (
+    (
+        "x-vbrief/closes",
+        re.compile(
+            r"\b(?:close[sd]?|fix(?:e[sd])?|resolve[sd]?)\s+#(\d+)\b",
+            re.IGNORECASE,
+        ),
+    ),
+    (
+        "x-vbrief/blocks",
+        re.compile(
+            r"\bblocked[\s\-]+by\s+#(\d+)\b",
+            re.IGNORECASE,
+        ),
+    ),
+    (
+        "x-vbrief/refs",
+        re.compile(
+            r"\b(?:refs?|references?|see\s+also|related(?:\s+to)?)\s+#(\d+)\b",
+            re.IGNORECASE,
+        ),
+    ),
+)
+
+# Fenced code block (triple-backtick OR tilde-fence) and inline code
+# span (single backtick, no embedded backtick / newline). Stripped
+# before cross-ref / plan-item extraction so a body that quotes
+# ``Closes #N`` as an illustration does not produce a real cross-ref.
+# The capturing group + ``\1`` backreference enforces matching
+# delimiters (a ``~~~`` fence cannot be closed by ``\`\`\``) per the
+# GitHub Flavoured Markdown spec.
+_CODE_FENCE_RE = re.compile(r"(```|~~~).*?\1", re.DOTALL)
+_INLINE_CODE_RE = re.compile(r"`[^`\n]*`")
+
+_CONTROL_CHAR_LABELS: dict[str, str] = {
+    "\b": "U+0008 backspace",
+    "\t": "U+0009 tab",
+    "\v": "U+000B vertical tab",
+    "\f": "U+000C form feed",
+}
+
+
+# --- Helpers ----------------------------------------------------------------
+
+
+def _strip_code_blocks(body: str) -> str:
+    """Return ``body`` with Markdown code spans elided (#1248).
+
+    Fenced code blocks (triple-backtick) and inline single-backtick code
+    spans are replaced with the empty string before cross-ref / plan-item
+    extraction. This prevents an issue body that *quotes* ``Closes #N``
+    as a syntax example (the #1248 body is itself an example -- it
+    embeds a JSON block illustrating the stub-only shape) from producing
+    spurious cross-refs or plan-items.
+    """
+    if not body:
+        return ""
+    return _INLINE_CODE_RE.sub("", _CODE_FENCE_RE.sub("", body))
+
+
+def _has_non_indentation_prefix(text: str, index: int) -> bool:
+    """Return True when a tab at ``index`` follows non-whitespace on its line."""
+    line_start = text.rfind("\n", 0, index) + 1
+    return any(ch not in " \t" for ch in text[line_start:index])
+
+
+def _body_control_character_labels(body: str) -> list[str]:
+    """Return visible labels for unexpected control characters in issue body text."""
+    labels: list[str] = []
+    seen: set[str] = set()
+    for index, char in enumerate(body):
+        if char == "\t" and not _has_non_indentation_prefix(body, index):
+            continue
+        label = _CONTROL_CHAR_LABELS.get(char)
+        if label is None and ord(char) < 32 and char not in {"\n", "\r"}:
+            label = f"U+{ord(char):04X} control character"
+        if label and label not in seen:
+            seen.add(label)
+            labels.append(label)
+    return labels
+
+
+def _warn_body_control_characters(number: int, body: str) -> None:
+    """Surface decoded upstream control characters before writing a vBRIEF."""
+    labels = _body_control_character_labels(body)
+    if not labels:
+        return
+    print(
+        f"Warning: issue #{number} body contains unexpected control characters "
+        f"({', '.join(labels)}); preserving Overview verbatim, but "
+        "verify_encoding will flag the generated vBRIEF narrative.",
+        file=sys.stderr,
+    )
+
+
+def _extract_plan_items(body: str) -> list[dict]:
+    """Extract ``plan.items[]`` entries from a GitHub issue body (#1248).
+
+    Detection ladder:
+
+    1. Markdown task-list checkboxes (``- [ ] foo`` / ``- [x] bar``) --
+       the GitHub-native shape that ``deft-directive-refinement`` and
+       ``task triage:queue`` both project from. Unchecked boxes map to
+       ``status = "proposed"``; checked boxes map to
+       ``status = "completed"`` so an issue that ships partial progress
+       is reflected honestly.
+    2. Bullet- / numbered-list items underneath an ``Acceptance
+       Criteria`` heading -- the second-most-common shape across the
+       2026-05-20 audit cohort. Stops at the next heading at the same
+       or higher level.
+    3. Graceful degradation: when neither shape is present, return an
+       empty list. The vBRIEF still carries ``narratives.Overview`` so
+       refinement can refine *something*; ``plan.items`` is only ever
+       populated when there is structured source material to project
+       from.
+
+    Every emitted item carries the schema-required ``title`` + ``status``
+    keys (``minLength: 1`` on ``title``; ``status`` from the canonical
+    ``Status`` enum). Duplicate titles are de-duped while preserving
+    document order.
+    """
+    if not body:
+        return []
+    text = _strip_code_blocks(body)
+
+    items: list[dict] = []
+    seen: set[str] = set()
+    for match in _CHECKBOX_RE.finditer(text):
+        marker = match.group(1)
+        title_text = match.group(2).strip()
+        if not title_text or title_text in seen:
+            continue
+        seen.add(title_text)
+        status = "completed" if marker.lower() == "x" else "proposed"
+        items.append({"title": title_text, "status": status})
+    if items:
+        return items
+
+    # Fallback: numbered / bulleted list under an Acceptance Criteria heading.
+    return _extract_ac_section_items(text)
+
+
+def _extract_ac_section_items(text: str) -> list[dict]:
+    """Extract list items from an Acceptance Criteria section (#1248 fallback).
+
+    Walks for an ``Acceptance Criteria`` heading (any level 1-6,
+    case-insensitive). When found, slices the body to the section --
+    bounded by the next heading at the same-or-higher level -- and
+    returns each bullet / numbered list item as a PlanItem dict with
+    ``status = "proposed"``.
+    """
+    heading_match = _AC_HEADING_RE.search(text)
+    if not heading_match:
+        return []
+    heading_level = len(heading_match.group(1))
+    section_start = heading_match.end()
+    next_heading_re = re.compile(
+        rf"^#{{1,{heading_level}}}\s+\S",
+        re.MULTILINE,
+    )
+    after = text[section_start:]
+    next_match = next_heading_re.search(after)
+    section_text = after[: next_match.start()] if next_match else after
+
+    items: list[dict] = []
+    seen: set[str] = set()
+    for li in _LIST_ITEM_RE.finditer(section_text):
+        title_text = li.group(1).strip()
+        # Defensive: strip a leftover ``[ ]`` / ``[x]`` checkbox prefix
+        # if a maintainer mixed checkbox + numbered shapes inside the
+        # AC section. Preserve the checked state so a completed item
+        # in a numbered+checkbox mixed AC list lands as ``completed``
+        # rather than being silently demoted to ``proposed`` (downstream
+        # consumers ``deft-directive-refinement`` / ``task triage:queue``
+        # treat ``status`` as signal for remaining work).
+        status = "proposed"
+        cb = re.match(r"\[([ xX])\]\s+(.+)", title_text)
+        if cb:
+            title_text = cb.group(2).strip()
+            if cb.group(1).lower() == "x":
+                status = "completed"
+        if not title_text or title_text in seen:
+            continue
+        seen.add(title_text)
+        items.append({"title": title_text, "status": status})
+    return items
+
+
+def _extract_cross_refs(
+    body: str,
+    repo_url: str,
+    *,
+    exclude: set[int] | None = None,
+) -> list[dict]:
+    """Extract Closes / Refs / Blocked-by cross-refs from issue body (#1248).
+
+    Returns a list of canonical ``VBriefReference`` dicts (``{uri, type,
+    title}``) ready to append to ``plan.references[]``. Reference types:
+
+    - ``x-vbrief/closes`` for ``Closes / Fixes / Resolves #N`` (inflected
+      forms ``closed`` / ``fixed`` / ``resolved`` accepted).
+    - ``x-vbrief/blocks`` for ``Blocked by #N`` -- the dependency
+      direction the issue body expresses (this scope is blocked by #N).
+    - ``x-vbrief/refs`` for ``Refs / References / See also / Related #N``.
+
+    Skips matches that fall inside fenced or inline code spans (the
+    body is passed through :func:`_strip_code_blocks` first) and any
+    issue number in ``exclude`` -- callers pass the provenance issue
+    number itself so a self-reference (e.g. ``Closes #1248`` in #1248's
+    own body) does not produce a duplicate reference to the canonical
+    ``x-vbrief/github-issue`` origin.
+
+    Returns an empty list when ``repo_url`` is empty -- the canonical
+    ``VBriefReference`` shape requires ``uri``, and synthesising a
+    URL without a repo handle would be dishonest.
+    """
+    if not body or not repo_url:
+        return []
+    text = _strip_code_blocks(body)
+    refs: list[dict] = []
+    seen: set[tuple[str, int]] = set()
+    excluded = exclude or set()
+    for ref_type, pattern in _CROSS_REF_PATTERNS:
+        for match in pattern.finditer(text):
+            number = int(match.group(1))
+            if number in excluded:
+                continue
+            key = (ref_type, number)
+            if key in seen:
+                continue
+            seen.add(key)
+            refs.append(
+                {
+                    "uri": f"{repo_url}/issues/{number}",
+                    "type": ref_type,
+                    "title": f"Issue #{number}",
+                }
+            )
+    return refs
+
+
+def _provenance_issue_number(data: dict) -> int | None:
+    """Extract the provenance issue number from a vBRIEF data dict (#1096).
+
+    A vBRIEF is the *provenance owner* of issue ``#N`` when its
+    ``plan.narratives.Origin`` (or, as a secondary signal,
+    ``vBRIEFInfo.description``) states it was ingested from ``#N``. Both
+    canonical Origin shapes emitted by :func:`_build_issue_vbrief` are
+    accepted:
+
+    - ``Ingested from https://github.com/<owner>/<repo>/issues/<N>``
+    - ``Ingested from issue #<N>``  (no-URL fallback)
+
+    Returns the provenance issue number or ``None`` when the vBRIEF carries
+    no recognisable ``Ingested from ...`` signal (e.g. a hand-authored
+    kaizen brief that merely references GitHub issues, or a legacy v0.5
+    fixture predating the Origin convention -- the caller's fallback
+    heuristic in :func:`_scan_provenance_refs` handles back-compat).
+    """
+    if not isinstance(data, dict):
+        return None
+    plan = data.get("plan", {})
+    narratives = plan.get("narratives", {}) if isinstance(plan, dict) else {}
+    origin = (
+        narratives.get("Origin", "") if isinstance(narratives, dict) else ""
+    )
+    info = data.get("vBRIEFInfo", {})
+    description = info.get("description", "") if isinstance(info, dict) else ""
+
+    for text in (origin, description):
+        if not isinstance(text, str) or not text:
+            continue
+        m = _ORIGIN_URL_RE.search(text)
+        if m:
+            return int(m.group(1))
+        m = _ORIGIN_BARE_RE.search(text)
+        if m:
+            return int(m.group(1))
+    return None
+
+
+def _scan_provenance_refs(vbrief_dir: Path) -> dict[int, list[str]]:
+    """Scan vBRIEF lifecycle folders and return a provenance-only dedup map (#1096).
+
+    Differentiates *provenance* references (the vBRIEF was actually
+    ingested from issue ``#N`` -- ``plan.narratives.Origin`` confirms it
+    AND a canonical ``x-vbrief/github-issue`` reference points at ``#N``)
+    from *informational* references (companion / sibling / related-plan
+    mentions, even when typed ``x-vbrief/github-issue``). Only the
+    provenance owner of an issue is returned, so ``task issue:ingest --
+    <N>`` no longer false-positives on informational references that
+    merely mention ``#N`` (closes #1096).
+
+    Per-vBRIEF resolution rule:
+
+    1. If ``plan.narratives.Origin`` (or ``vBRIEFInfo.description``)
+       identifies a provenance issue number ``P`` AND any
+       ``x-vbrief/github-issue`` reference points at ``P`` -> that vBRIEF
+       is the provenance owner of ``P`` (only). Other
+       ``x-vbrief/github-issue`` references on the same vBRIEF are
+       treated as informational and contribute nothing to the dedup map.
+    2. If no ``Origin`` provenance signal is present (legacy v0.5
+       fixtures, hand-authored stubs) -> fall back to the FIRST
+       ``x-vbrief/github-issue`` reference as the implied provenance.
+       This preserves dedup for unmigrated trees per the #1096 vBRIEF's
+       out-of-scope clause ("the fix should make new ingest correct
+       without requiring a data-migration sweep first").
+
+    Returns:
+        Mapping of issue_number -> list of vBRIEF file paths (relative to
+        ``vbrief_dir``) where each listed vBRIEF is the *provenance* owner
+        of that issue. The list shape matches
+        :func:`reconcile_issues.scan_vbrief_dir` so callers can swap the
+        two functions transparently.
+    """
+    issue_to_vbriefs: dict[int, list[str]] = {}
+
+    for folder in LIFECYCLE_FOLDERS:
+        folder_path = vbrief_dir / folder
+        if not folder_path.is_dir():
+            continue
+        for vbrief_file in sorted(folder_path.glob("*.vbrief.json")):
+            try:
+                data = json.loads(vbrief_file.read_text(encoding="utf-8"))
+            except (json.JSONDecodeError, OSError):
+                continue
+
+            refs = extract_references_from_vbrief(data)
+            github_refs: list[tuple[dict, int]] = []
+            for ref in refs:
+                if ref.get("type") not in GITHUB_ISSUE_REF_TYPES:
+                    continue
+                num = parse_issue_number(ref)
+                if num is not None:
+                    github_refs.append((ref, num))
+
+            if not github_refs:
+                continue
+
+            provenance_num = _provenance_issue_number(data)
+            if provenance_num is not None:
+                # Origin/description identifies ``provenance_num`` -- only
+                # count the matching github-issue ref. Companion refs to
+                # other issues on the same vBRIEF are informational.
+                if not any(num == provenance_num for _, num in github_refs):
+                    # Origin narrative claims a number not borne out by any
+                    # github-issue reference. Honest behaviour is to skip
+                    # this vBRIEF -- treating the Origin claim alone as
+                    # provenance would re-introduce the false-positive
+                    # surface the legacy-ref fallback below is bounded
+                    # against.
+                    continue
+                owner_num = provenance_num
+            else:
+                # Legacy fallback: first github-issue ref is provenance.
+                owner_num = github_refs[0][1]
+
+            rel_path = f"{folder}/{vbrief_file.name}"
+            issue_to_vbriefs.setdefault(owner_num, []).append(rel_path)
+
+    return issue_to_vbriefs
+
+
+def _build_issue_vbrief(
+    issue: dict, status: str, repo_url: str
+) -> tuple[dict, str]:
+    """Build a scope vBRIEF dict (and the target lifecycle folder) from a GitHub issue dict.
+
+    ``issue`` is the JSON payload returned by ``gh api repos/.../issues/N`` or
+    one element of the ``gh issue list --json number,title,labels,url,body``
+    array.
+
+    Emits canonical vBRIEF v0.6 output (#639 + #988):
+      - ``vBRIEFInfo.version = EMITTED_VBRIEF_VERSION`` (``"0.6"``) -- the
+        canonical schema pin (const ``"0.6"`` in
+        ``vbrief/schemas/vbrief-core.schema.json``).
+      - ``plan.narratives.Overview`` carries the GitHub issue body verbatim
+        when present (#988). This is the contract documented in
+        ``skills/deft-directive-swarm/SKILL.md`` Phase 0 Step 0B; the prior
+        implementation only emitted ``Description`` (= title) and dropped
+        the body, producing stub vBRIEFs that failed every downstream
+        "acceptance criteria present" check. ``narratives.Labels`` is kept
+        for backward compatibility but ``plan.tags`` is now the structured
+        surface for downstream filtering.
+      - ``plan.tags`` is a list of label-name strings when the issue carries
+        labels (#988). The Plan schema's ``tags`` array (line 162 of
+        ``vbrief/schemas/vbrief-core.schema.json``) accepts arbitrary
+        strings; this lets consumers filter without parsing the freeform
+        ``narratives.Labels`` text.
+      - ``plan.references`` uses the canonical
+        ``VBriefReference`` shape ``{uri, type: "x-vbrief/github-issue",
+        title: "Issue #{N}: {title}"}`` documented in
+        ``conventions/references.md`` (matches ``scripts/_vbrief_build.py::
+        create_scope_vbrief``). The legacy bare
+        ``{type: "github-issue", id: "#N", url}`` shape is NEVER emitted.
+      - When no browser URL can be resolved (neither the issue payload's
+        ``url`` nor a non-empty ``repo_url``) the reference is omitted --
+        ``VBriefReference`` requires ``uri``, so we cannot honestly emit
+        one. The caller still has the issue number in ``plan.narratives["Origin"]``.
+    """
+    number = int(issue["number"])
+    title = str(issue.get("title", f"Issue #{number}")) or f"Issue #{number}"
+    url = str(issue.get("url", "")) or (
+        f"{repo_url}/issues/{number}" if repo_url else ""
+    )
+    body = issue.get("body")
+    body_str = str(body) if isinstance(body, str) and body else ""
+    labels = issue.get("labels", []) or []
+    label_names = [
+        (lbl.get("name") if isinstance(lbl, dict) else str(lbl))
+        for lbl in labels
+        if (isinstance(lbl, dict) and lbl.get("name")) or isinstance(lbl, str)
+    ]
+    folder, plan_status = _STATUS_MAP[status]
+
+    narratives: dict[str, str] = {
+        "Description": title,
+        "Origin": f"Ingested from {url}" if url else f"Ingested from issue #{number}",
+    }
+    if body_str:
+        # #988: carry the issue body verbatim to ``narratives.Overview`` so
+        # the swarm Phase 0 "acceptance criteria present" check has source
+        # text to project from. #1248 widens this surface by ALSO emitting
+        # structured ``plan.items[]`` + ``plan.references[]`` cross-refs
+        # derived from the body, so refinement / triage:queue have more
+        # than just an opaque blob to work with.
+        _warn_body_control_characters(number, body_str)
+        narratives["Overview"] = body_str
+    if label_names:
+        narratives["Labels"] = ", ".join(label_names)
+
+    # #1248: derive ``plan.items[]`` from the issue body's task-list /
+    # acceptance-criteria checklist (graceful degradation to ``[]`` when
+    # neither shape is present).
+    plan_items = _extract_plan_items(body_str) if body_str else []
+
+    plan: dict = {
+        "title": title,
+        "status": plan_status,
+        "narratives": narratives,
+        "items": plan_items,
+    }
+    if label_names:
+        # #988: structured-surface mirror of ``narratives.Labels`` so
+        # consumers can filter by tag without parsing the freeform string.
+        plan["tags"] = list(label_names)
+
+    # #639 + #1248: canonical v0.6 VBriefReference shape, with the body-
+    # derived Closes / Refs / Blocked-by cross-refs appended after the
+    # canonical ``x-vbrief/github-issue`` origin. Only emit when we have
+    # a resolvable URL -- the schema requires ``uri`` and we must not
+    # forge one. Matches ``scripts/_vbrief_build.py::create_scope_vbrief``
+    # and ``conventions/references.md``.
+    if url:
+        references: list[dict] = [
+            {
+                "uri": url,
+                "type": "x-vbrief/github-issue",
+                "title": f"Issue #{number}: {title}",
+            }
+        ]
+        if body_str and repo_url:
+            # Use ``repo_url`` (not ``url``) so cross-refs target sibling
+            # issues under the same repo even when ``url`` already
+            # resolves a specific issue; exclude ``number`` so a
+            # self-referencing ``Closes #N`` in the body does not
+            # duplicate the canonical origin reference above.
+            references.extend(
+                _extract_cross_refs(
+                    body_str, repo_url, exclude={number}
+                )
+            )
+        plan["references"] = references
+
+    return {
+        "vBRIEFInfo": {
+            "version": EMITTED_VBRIEF_VERSION,
+            "description": f"Scope vBRIEF ingested from GitHub issue #{number}",
+        },
+        "plan": plan,
+    }, folder
+
+
+def _target_filename(number: int, title: str) -> str:
+    """Build the ``YYYY-MM-DD-<N>-<slug>.vbrief.json`` filename for an issue."""
+    slug = slugify(title) or f"issue-{number}"
+    return f"{TODAY}-{number}-{slug}.vbrief.json"
+
+
+def _fetch_from_cache(
+    repo: str,
+    number: int,
+    *,
+    cache_root: Path | None = None,
+) -> dict | None:
+    """Read the unified cache (#883) for ``(github-issue, repo/number)`` if fresh.
+
+    Returns the parsed ``raw.json`` payload when present and not stale,
+    ``None`` otherwise (cache miss, stale entry, parse failure, or the
+    cache module is not importable). The caller falls back to a live
+    ``gh api`` round-trip via :func:`_fetch_single_issue` on ``None``.
+
+    Cache freshness is delegated to :func:`scripts.cache.cache_get` with
+    ``allow_stale=False`` -- this matches the #883 contract that callers
+    opt in to stale entries explicitly. The unified cache TTL for
+    ``github-issue`` is 7 days (see ``scripts/cache.py::SOURCE_TTL_SECONDS``).
+    """
+    if cache is None:
+        return None
+    key = f"{repo}/{int(number)}"
+    try:
+        result = cache.cache_get(
+            "github-issue", key, cache_root=cache_root, allow_stale=False
+        )
+    except Exception:  # noqa: BLE001 -- any cache error -> live fetch fallback
+        return None
+    raw_path = Path(result.entry_dir) / "raw.json"
+    if not raw_path.exists():
+        return None
+    try:
+        issue: Any = json.loads(raw_path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return None
+    if not isinstance(issue, dict):
+        return None
+    # Mirror the normalisation _fetch_single_issue applies to live ``gh api``
+    # output: prefer ``html_url`` (browser URL) over ``url`` (REST API URL)
+    # when both are present. The cache populated by ``task cache:fetch-all``
+    # uses ``gh issue list --json ...,url`` which already emits the browser
+    # URL, so this branch is a no-op for cached payloads -- but keep it
+    # defensive so a future cache populator using ``gh api`` directly still
+    # produces honest output here.
+    if issue.get("html_url"):
+        issue["url"] = issue["html_url"]
+    return issue
+
+
+def _fetch_issue(
+    repo: str,
+    number: int,
+    *,
+    cwd: Path | None = None,
+    cache_root: Path | None = None,
+) -> dict | None:
+    """Fetch a single issue, preferring the unified cache over live ``gh api``.
+
+    #988: when ``.deft-cache/github-issue/<owner>/<repo>/<N>/raw.json`` is
+    fresh, return the cached payload directly so a Phase 0 walk that
+    pre-populated the cache via ``task cache:fetch-all`` does not re-spend
+    the REST budget per issue. Falls back to live ``gh api`` on cache miss
+    or stale entries (per #883 cache freshness rules).
+    """
+    cached = _fetch_from_cache(repo, number, cache_root=cache_root)
+    if cached is not None:
+        return cached
+    return _fetch_single_issue(repo, number, cwd=cwd)
+
+
+def _fetch_single_issue(
+    repo: str,
+    number: int,
+    *,
+    cwd: Path | None = None,
+) -> dict | None:
+    """Fetch a single issue via ``gh api repos/{repo}/issues/{number}``.
+
+    Routes through :func:`scripts.scm.call` (#1145 / N5) so a future
+    non-GitHub consumer raises a loud ``NotImplementedError`` pointing at
+    #445 / #935 Workstream 6 rather than failing deep in the call stack
+    with ``gh: command not found``. The shim resolves the binary via the
+    #884 ``ghx`` -> ``gh`` preference ladder so cached responses are
+    transparently picked up when ``ghx`` is installed.
+
+    Returns the parsed issue dict on success, ``None`` on error (with the
+    reason printed to stderr).
+    """
+    try:
+        result = scm.call(
+            "github-issue",
+            "api",
+            [f"repos/{repo}/issues/{number}"],
+            timeout=30,
+            cwd=str(cwd) if cwd is not None else None,
+        )
+    except FileNotFoundError:
+        print("Error: gh CLI not found. Install GitHub CLI.", file=sys.stderr)
+        return None
+    except scm.ScmStubError as exc:
+        print(f"Error: gh CLI resolution failed: {exc}", file=sys.stderr)
+        return None
+    except subprocess.TimeoutExpired:
+        print("Error: gh CLI timed out.", file=sys.stderr)
+        return None
+
+    if result.returncode != 0:
+        print(
+            f"Error: gh CLI failed fetching #{number}: {result.stderr.strip()}",
+            file=sys.stderr,
+        )
+        return None
+    try:
+        issue = json.loads(result.stdout)
+    except json.JSONDecodeError:
+        print(
+            f"Error: failed to parse gh CLI output for #{number}.",
+            file=sys.stderr,
+        )
+        return None
+    # #639 follow-up (Greptile P1): ``gh api repos/{repo}/issues/{N}``
+    # ALWAYS returns both ``url`` (REST API URL, ``https://api.github.com/repos/...``)
+    # and ``html_url`` (browser URL, ``https://github.com/{owner}/{repo}/issues/{N}``).
+    # The previous ``"url" not in issue`` guard was therefore always False for
+    # real gh api output, so ``issue["url"]`` leaked through as the REST API
+    # URL and ended up in the canonical ``uri`` field -- contradicting the
+    # ``conventions/references.md`` spec which requires the browser URL.
+    # ``fetch_open_issues`` (``gh issue list --json ...,url``) already returns
+    # ``url`` = browser URL, so unconditionally preferring ``html_url`` when
+    # present aligns the single-issue and bulk paths.
+    if "html_url" in issue and issue.get("html_url"):
+        issue["url"] = issue["html_url"]
+    return issue
+
+
+# --- Core actions -----------------------------------------------------------
+
+
+def ingest_one(
+    issue: dict,
+    *,
+    vbrief_dir: Path,
+    status: str,
+    repo_url: str,
+    dry_run: bool = False,
+    existing_refs: dict[int, list[str]] | None = None,
+) -> tuple[str, Path | None, str]:
+    """Ingest a single issue dict.
+
+    Returns ``(result, path, message)`` where ``result`` is one of ``"created"``,
+    ``"dryrun"``, or ``"duplicate"``. ``path`` is the written (or would-be) file
+    path; for ``duplicate`` it points at the pre-existing vBRIEF that already
+    references this issue.
+    """
+    number = int(issue["number"])
+    # #1096: provenance-aware dedup. Only count vBRIEFs that were actually
+    # ingested from issue #N (Origin-narrative-confirmed) -- companion /
+    # related-plan / sibling-mention references that merely cite #N do NOT
+    # block ingest.
+    refs = (
+        existing_refs
+        if existing_refs is not None
+        else _scan_provenance_refs(vbrief_dir)
+    )
+    if number in refs:
+        existing = refs[number][0]
+        return "duplicate", vbrief_dir / existing, f"#{number} already ingested at {existing}"
+
+    vbrief, folder = _build_issue_vbrief(issue, status, repo_url)
+    filename = _target_filename(number, str(issue.get("title", "")))
+    target = vbrief_dir / folder / filename
+
+    if dry_run:
+        return "dryrun", target, f"DRY-RUN would write {folder}/{filename}"
+
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text(
+        json.dumps(vbrief, indent=2, ensure_ascii=False) + "\n",
+        encoding="utf-8",
+    )
+    return "created", target, f"CREATED {folder}/{filename}"
+
+
+def ingest_bulk(
+    issues: list[dict],
+    *,
+    vbrief_dir: Path,
+    status: str,
+    repo_url: str,
+    label: str | None = None,
+    dry_run: bool = False,
+) -> dict:
+    """Ingest a list of issues.
+
+    Filters by ``label`` first (if provided), then delegates to
+    ``ingest_one`` for each remaining issue. Returns a summary dict:
+    ``{"created": [...], "duplicate": [...], "dryrun": [...], "total": N}``.
+    """
+    if label:
+        filtered = []
+        for issue in issues:
+            for lbl in issue.get("labels", []) or []:
+                name = lbl.get("name") if isinstance(lbl, dict) else str(lbl)
+                if name == label:
+                    filtered.append(issue)
+                    break
+        issues = filtered
+
+    # #1096: provenance-aware dedup. See :func:`_scan_provenance_refs`.
+    refs = _scan_provenance_refs(vbrief_dir)
+
+    # Values are list[str] for the three bucket keys and int for "total",
+    # hence the union annotation.
+    summary: dict[str, list[str] | int] = {"created": [], "duplicate": [], "dryrun": []}
+    for issue in issues:
+        result, path, _msg = ingest_one(
+            issue,
+            vbrief_dir=vbrief_dir,
+            status=status,
+            repo_url=repo_url,
+            dry_run=dry_run,
+            existing_refs=refs,
+        )
+        summary[result].append(str(path.relative_to(vbrief_dir)) if path else "")
+        # After a real write the refs map would now contain this number;
+        # update in place so duplicates inside the same batch are detected.
+        if result == "created":
+            refs.setdefault(int(issue["number"]), []).append(
+                str(path.relative_to(vbrief_dir))
+            )
+
+    summary["total"] = len(issues)
+    return summary
+
+
+# --- CLI --------------------------------------------------------------------
+
+
+def _resolve_repo_url(repo: str) -> str:
+    """Produce a browser URL from an OWNER/REPO pair (or empty if none)."""
+    if not repo:
+        return ""
+    if repo.startswith(("http://", "https://")):
+        return repo.rstrip("/")
+    if re.match(r"^[^/]+/[^/]+$", repo):
+        return f"https://github.com/{repo}"
+    return ""
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        description="Ingest GitHub issues as scope vBRIEFs in vbrief/ lifecycle folders.",
+    )
+    parser.add_argument(
+        "number",
+        nargs="?",
+        type=int,
+        help="GitHub issue number to ingest (single-issue mode)",
+    )
+    parser.add_argument(
+        "--all",
+        action="store_true",
+        help="Bulk mode -- ingest all open issues (optionally filtered by --label)",
+    )
+    parser.add_argument(
+        "--label",
+        default=None,
+        help="Only ingest issues carrying this label (bulk mode)",
+    )
+    parser.add_argument(
+        "--status",
+        default="proposed",
+        choices=INGEST_STATUSES,
+        help="Target lifecycle folder / plan.status (default: proposed)",
+    )
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Print what would be written without creating files",
+    )
+    parser.add_argument(
+        "--vbrief-dir",
+        default="./vbrief",
+        help="Path to vbrief/ directory (default: ./vbrief)",
+    )
+    parser.add_argument(
+        "--repo",
+        default=None,
+        help=(
+            "GitHub repo in OWNER/REPO format. Highest precedence; beats "
+            "$DEFT_PROJECT_REPO and git-remote detection. Without a flag, "
+            "env var, or git remote in the project root the script FAILS "
+            "loudly rather than silently falling back to deft's own remote "
+            "(#538)."
+        ),
+    )
+    parser.add_argument(
+        "--project-root",
+        default=None,
+        help=(
+            "Consumer project root. Used as CWD for git-remote detection "
+            "so ``gh`` / ``git`` queries target the consumer repo, not "
+            "deftai/directive (#538)."
+        ),
+    )
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    if args.number is None and not args.all:
+        parser.error("Provide an issue number or --all")
+
+    if args.number is not None and args.all:
+        parser.error("Use either a single issue number OR --all, not both")
+
+    vbrief_dir = Path(args.vbrief_dir).resolve()
+    if not vbrief_dir.exists():
+        vbrief_dir.mkdir(parents=True, exist_ok=True)
+
+    project_root = resolve_project_root(args.project_root)
+    repo = resolve_project_repo(args.repo, project_root=project_root)
+    # Fall back to the legacy CWD-scoped ``detect_repo`` only when no
+    # project root could be inferred; that path still exists because
+    # some in-process test suites monkeypatch ``detect_repo`` directly.
+    if not repo:
+        repo = detect_repo()
+    if not repo:
+        print(
+            "Error: could not detect repo. "
+            "Pass --repo OWNER/NAME, set $DEFT_PROJECT_REPO, or run from "
+            "a directory tree whose git remote origin is the consumer "
+            "repo (#538).",
+            file=sys.stderr,
+        )
+        return 2
+    repo_url = _resolve_repo_url(repo)
+
+    if args.all:
+        issues = fetch_open_issues(repo, cwd=project_root)
+        if issues is None:
+            return 2
+        summary = ingest_bulk(
+            issues,
+            vbrief_dir=vbrief_dir,
+            status=args.status,
+            repo_url=repo_url,
+            label=args.label,
+            dry_run=args.dry_run,
+        )
+        print(
+            "issue:ingest bulk summary: "
+            f"{len(summary['created'])} created, "
+            f"{len(summary['duplicate'])} duplicate, "
+            f"{len(summary['dryrun'])} dry-run "
+            f"(total considered: {summary['total']})"
+        )
+        for entry in summary["created"]:
+            print(f"  CREATED {entry}")
+        for entry in summary["dryrun"]:
+            print(f"  DRY-RUN {entry}")
+        for entry in summary["duplicate"]:
+            print(f"  SKIP    {entry} (already has scope vBRIEF)")
+        return 0
+
+    # Single-issue mode -- prefer the unified cache (#883/#988) before
+    # falling back to a live ``gh api`` round-trip.
+    issue = _fetch_issue(repo, args.number, cwd=project_root)
+    if issue is None:
+        return 2
+    result, path, msg = ingest_one(
+        issue,
+        vbrief_dir=vbrief_dir,
+        status=args.status,
+        repo_url=repo_url,
+        dry_run=args.dry_run,
+    )
+    print(msg)
+    if result == "duplicate":
+        return 1
+    return 0
+
+
+def ingest_single_for_accept(
+    n: int,
+    repo: str,
+    *,
+    project_root: Path | None = None,
+    status: str = "proposed",
+    cache_root: Path | None = None,
+) -> tuple[str, Path | None]:
+    """Ingest a single issue on behalf of ``triage_actions.accept`` (#985).
+
+    The triage skill's contract is that ``task triage:accept`` delegates the
+    actual vBRIEF authoring to ``task issue:ingest`` so slug / reference /
+    schema rules stay in one place (per ``conventions/references.md`` and
+    ``skills/deft-directive-refinement/SKILL.md`` Phase 0 Tier 3). This is
+    the importable Python entry point that ``scripts/triage_actions.py::accept``
+    calls after the audit-log append succeeds.
+
+    Resolves ``vbrief_dir`` to ``<project_root>/vbrief`` (created on demand)
+    and the ``repo_url`` to the canonical browser URL via
+    :func:`_resolve_repo_url`. Fetches the issue via :func:`_fetch_issue`
+    (cache-first per #988) and writes the vBRIEF via :func:`ingest_one`.
+
+    Returns the ``(result, path)`` tuple from :func:`ingest_one`. Raises
+    :class:`RuntimeError` on fetch failure so the caller (``accept``) can
+    roll the audit-log entry back.
+    """
+    root = (project_root or Path.cwd()).resolve()
+    vbrief_dir = (root / "vbrief").resolve()
+    if not vbrief_dir.exists():
+        vbrief_dir.mkdir(parents=True, exist_ok=True)
+    repo_url = _resolve_repo_url(repo)
+    issue = _fetch_issue(repo, n, cwd=root, cache_root=cache_root)
+    if issue is None:
+        raise RuntimeError(
+            f"failed to fetch GitHub issue #{n} from {repo} "
+            "(unified cache miss + live gh api fetch failed; see stderr)"
+        )
+    result, path, _msg = ingest_one(
+        issue,
+        vbrief_dir=vbrief_dir,
+        status=status,
+        repo_url=repo_url,
+    )
+    return result, path
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())