@deftai/directive-content 0.55.2 → 0.56.0

package/scripts/verify_vbrief_conformance.py

@@ -0,0 +1,478 @@
+#!/usr/bin/env python3
+"""verify_vbrief_conformance.py -- deterministic vBRIEF 0.6 conformance gate (#1620).
+
+directive is the vBRIEF reference implementation, so its own corpus must stay
+conformant to the standard it anchors: every key at document, plan, and item
+level MUST be either (a) a known 0.6 spec-core field, (b) prefixed
+``x-directive/`` (a directive extension), or (c) prefixed ``x-vbrief/`` (a
+vBRIEF extension). A bare key outside those three classes masquerades as
+candidate-core and is exactly what produced the statusreport #34 false-RED.
+
+This gate fails ``task check`` + the pre-commit hook when any tracked
+``vbrief/**/*.vbrief.json`` carries such a bare key. It mirrors the structure
+and UX of ``scripts/verify_encoding.py`` (#798): three-state exit, ``--all`` /
+``--staged`` modes, and an ``--allow-list <path>`` file-glob override.
+
+Core key sets
+-------------
+Built from the canonical vBRIEF 0.6 spec (``deftai/vBRIEF``
+``docs/vbrief-spec-0.6.md`` + ``libvbrief/models.py``) and the in-repo mirror
+``vbrief/schemas/vbrief-core.schema.json``. ``metadata`` is an arbitrary bag
+per 0.6 (Design Goal #5) so the gate does NOT descend into it; likewise it does
+not descend into ``vBRIEFInfo`` or narrative bodies -- only structural keys at
+the document, plan, and item levels are checked.
+
+Temporary Category B allow-list
+-------------------------------
+``plan.policy`` and ``plan.completedNote`` are genuine directive extensions
+that SHOULD live under ``x-directive/`` but cannot be moved until upstream
+vBRIEF #12 ratifies the ``x-<consumer>/`` namespace with round-trip
+preservation. They are carved out via :data:`ALLOW_LIST` (a KEY allow-set,
+distinct from the ``--allow-list`` file-glob override) and tracked by the
+Category B follow-up issue cited below.
+
+Plan-level ``planRef`` is handled specially (value-aware, see
+:func:`_plan_planref_finding`): a PATH-style value is the load-bearing D4
+epic<->story child->parent linkage and is allowed as a TEMPORARY carve-out
+(its references[]-reconciliation + D4 rework is deferred to the same Category B
+follow-up); a ``#``-prefixed value is the misused issue-pointer pattern behind
+the statusreport #34 false-RED and IS flagged.
+
+Exit codes (three-state, mirrors ``scripts/verify_encoding.py``)
+----------------------------------------------------------------
+- ``0`` -- clean: no bare keys detected.
+- ``1`` -- violations: prints per-hit ``path [level] key`` diagnostics.
+- ``2`` -- config error: no ``vbrief/`` directory, ``--allow-list`` path
+  unreadable, ``--staged`` outside a git repo, or unrecognised CLI shape.
+"""
+
+from __future__ import annotations
+
+import argparse
+import fnmatch
+import json
+import sys
+from collections.abc import Iterable
+from pathlib import Path
+
+# Route subprocess capture through the #1366 UTF-8-safe helper. The script
+# lives in scripts/ alongside _safe_subprocess.py; add that dir to sys.path so
+# the import resolves whether the module is run directly or loaded via
+# importlib.spec_from_file_location in tests.
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from _safe_subprocess import run_text  # noqa: E402
+
+#: Document-level (root) spec-core keys.
+DOC_CORE: frozenset[str] = frozenset({"vBRIEFInfo", "plan"})
+
+#: Plan-level spec-core keys (0.6). ``policy`` is DELIBERATELY EXCLUDED -- it is
+#: a Category B directive extension carved out via :data:`ALLOW_LIST` so the
+#: future ``plan.policy`` -> ``x-directive/policy`` migration stays enforceable
+#: once the allow-list is removed.
+PLAN_CORE: frozenset[str] = frozenset(
+    {
+        "id",
+        "uid",
+        "title",
+        "status",
+        "items",
+        "narratives",
+        "architecture",
+        "edges",
+        "tags",
+        "metadata",
+        "created",
+        "updated",
+        "author",
+        "reviewers",
+        "uris",
+        "references",
+        "timezone",
+        "agent",
+        "lastModifiedBy",
+        "changeLog",
+        "sequence",
+        "fork",
+    }
+)
+
+#: Item-level (PlanItem) spec-core keys (0.6). ``planRef`` IS core here (it is a
+#: legitimate item field for referencing plans); only the plan-LEVEL ``planRef``
+#: misuse is non-conformant.
+ITEM_CORE: frozenset[str] = frozenset(
+    {
+        "id",
+        "uid",
+        "title",
+        "status",
+        "narrative",
+        "subItems",
+        "planRef",
+        "tags",
+        "metadata",
+        "created",
+        "updated",
+        "completed",
+        "priority",
+        "dueDate",
+        "startDate",
+        "endDate",
+        "percentComplete",
+        "participants",
+        "location",
+        "uris",
+        "recurrence",
+        "reminders",
+        "classification",
+        "relatedComments",
+        "timezone",
+        "sequence",
+        "lastModifiedBy",
+        "lockedBy",
+        "items",
+    }
+)
+
+#: Accepted extension-namespace prefixes. A key carrying either prefix is
+#: conformant at any level (it is an explicitly-namespaced extension, not a
+#: bare candidate-core key).
+EXTENSION_PREFIXES: tuple[str, ...] = ("x-directive/", "x-vbrief/")
+
+#: TEMPORARY Category B carve-outs (KEY allow-set, ``"<level>.<key>"`` form).
+#: These are genuine directive extensions awaiting the ``x-<consumer>/``
+#: namespace ratified by upstream vBRIEF #12; the migration that moves them to
+#: ``x-directive/*`` and REMOVES this allow-list is tracked by directive #1650
+#: (Category B follow-up to #1620).
+ALLOW_LIST: frozenset[str] = frozenset({"plan.policy", "plan.completedNote"})
+
+
+class Finding:
+    """One bare-key conformance violation record."""
+
+    __slots__ = ("path", "level", "key", "location")
+
+    def __init__(self, path: str, level: str, key: str, location: str) -> None:
+        self.path = path
+        self.level = level
+        self.key = key
+        self.location = location
+
+    def render(self) -> str:
+        return f"  {self.path} [{self.level}] bare key {self.key!r} at {self.location}"
+
+
+def _is_conformant(level: str, key: str, core: frozenset[str]) -> bool:
+    """Return True when ``key`` is core, namespaced, or allow-listed at level."""
+    if key in core:
+        return True
+    if key.startswith(EXTENSION_PREFIXES):
+        return True
+    return f"{level}.{key}" in ALLOW_LIST
+
+
+def _plan_planref_finding(rel_path: str, value: object) -> Finding | None:
+    """Value-aware check for the plan-LEVEL ``planRef`` key.
+
+    Plan-level ``planRef`` is NOT 0.6 spec-core (``planRef`` is core only at the
+    item level). directive carries two distinct shapes here:
+
+    - A PATH-style value (``"completed/...vbrief.json"``) is the epic<->story
+      child->parent linkage that ``scripts/vbrief_validate.py`` D4 validates
+      bidirectionally. It is load-bearing and cannot move to ``references[]``
+      without reworking D4, so it is a TEMPORARY carve-out tracked by the
+      Category B follow-up (#1650) -- allowed (not flagged) here.
+    - A ``#``-prefixed value (``"#1348"`` issue ref, or a stale ``#slug``) is
+      the misused-as-issue-pointer pattern that produced the statusreport #34
+      false-RED. It is FLAGGED so ``scripts/vbrief_migrate_conformance.py``
+      (which routes it to ``references[]`` or deletes the junk) stays enforced.
+    """
+    if isinstance(value, str) and value.strip().startswith("#"):
+        return Finding(
+            rel_path, "plan", "planRef", "plan (issue-style -- migrate to references[])"
+        )
+    return None
+
+
+def _scan_item(rel_path: str, item: dict, location: str) -> list[Finding]:
+    """Scan one PlanItem dict (and its nested items / subItems) for bare keys."""
+    findings: list[Finding] = []
+    for key in item:
+        if not _is_conformant("item", key, ITEM_CORE):
+            findings.append(Finding(rel_path, "item", key, location))
+    for nested_key in ("items", "subItems"):
+        nested = item.get(nested_key)
+        if isinstance(nested, list):
+            for index, child in enumerate(nested):
+                if isinstance(child, dict):
+                    findings.extend(
+                        _scan_item(
+                            rel_path, child, f"{location}.{nested_key}[{index}]"
+                        )
+                    )
+    return findings
+
+
+def scan_vbrief(rel_path: str, data: object) -> list[Finding]:
+    """Scan a parsed vBRIEF document for bare keys at doc / plan / item level.
+
+    ``metadata`` (arbitrary bag), ``vBRIEFInfo``, and narrative bodies are NOT
+    descended into -- only structural keys at the three checked levels.
+    """
+    findings: list[Finding] = []
+    if not isinstance(data, dict):
+        return findings
+
+    for key in data:
+        if not _is_conformant("document", key, DOC_CORE):
+            findings.append(Finding(rel_path, "document", key, "<root>"))
+
+    plan = data.get("plan")
+    if not isinstance(plan, dict):
+        return findings
+
+    for key in plan:
+        if key == "planRef":
+            hit = _plan_planref_finding(rel_path, plan.get("planRef"))
+            if hit is not None:
+                findings.append(hit)
+            continue
+        if not _is_conformant("plan", key, PLAN_CORE):
+            findings.append(Finding(rel_path, "plan", key, "plan"))
+
+    items = plan.get("items")
+    if isinstance(items, list):
+        for index, item in enumerate(items):
+            if isinstance(item, dict):
+                findings.extend(
+                    _scan_item(rel_path, item, f"plan.items[{index}]")
+                )
+    return findings
+
+
+def _load_allow_list(path: Path | None) -> list[str]:
+    """Read newline-separated file-glob patterns; ignore comments / blanks."""
+    if path is None:
+        return []
+    raw = path.read_text(encoding="utf-8", errors="replace")
+    out: list[str] = []
+    for line in raw.splitlines():
+        stripped = line.strip()
+        if not stripped or stripped.startswith("#"):
+            continue
+        out.append(stripped)
+    return out
+
+
+def _is_allow_listed(rel_path: str, patterns: Iterable[str]) -> bool:
+    return any(fnmatch.fnmatchcase(rel_path, pat) for pat in patterns)
+
+
+def _git_files(project_root: Path, *, staged: bool) -> list[str]:
+    """Return tracked (or staged) POSIX-form rel paths via git."""
+    if staged:
+        cmd = ["git", "diff", "--cached", "--name-only", "--diff-filter=ACMR"]
+    else:
+        cmd = ["git", "ls-files"]
+    proc = run_text(cmd, cwd=str(project_root))
+    if proc.returncode != 0:
+        raise RuntimeError(
+            f"{' '.join(cmd)} failed (rc={proc.returncode}): {proc.stderr.strip()}"
+        )
+    return [line for line in proc.stdout.splitlines() if line.strip()]
+
+
+def _is_vbrief_path(posix: str) -> bool:
+    """Return True for the project's root ``vbrief/**/*.vbrief.json`` corpus.
+
+    Anchored at the project-root ``vbrief/`` directory (matching the scan scope
+    of ``scripts/vbrief_migrate_conformance.py``) so the gate and the migration
+    reason about exactly the same file set. This deliberately excludes
+    ``.vbrief.json`` files nested under other directories -- most importantly
+    intentionally-stale migration fixtures under ``tests/fixtures/**`` -- which
+    are test artifacts, not the canonical corpus.
+    """
+    return posix.startswith("vbrief/") and posix.endswith(".vbrief.json")
+
+
+def evaluate(
+    project_root: Path,
+    *,
+    mode: str = "all",
+    allow_list_path: Path | None = None,
+) -> tuple[int, list[Finding], str]:
+    """Pure driver returning ``(exit_code, findings, human_message)``."""
+    if mode not in {"all", "staged"}:
+        return (
+            2,
+            [],
+            f"\u274c verify_vbrief_conformance: unrecognised mode {mode!r} "
+            "(expected 'all' or 'staged').",
+        )
+
+    if not (project_root / "vbrief").is_dir():
+        return (
+            2,
+            [],
+            (
+                "\u274c verify_vbrief_conformance: no vbrief/ directory under "
+                f"{project_root}.\n"
+                "  Recovery: run from a project root that contains vbrief/."
+            ),
+        )
+
+    try:
+        custom_globs = _load_allow_list(allow_list_path)
+    except FileNotFoundError as exc:
+        return (
+            2,
+            [],
+            (
+                f"\u274c verify_vbrief_conformance: --allow-list file not found: {exc}\n"
+                "  Recovery: pass an existing path or omit the flag."
+            ),
+        )
+    except OSError as exc:
+        return (
+            2,
+            [],
+            f"\u274c verify_vbrief_conformance: --allow-list unreadable: {exc}",
+        )
+
+    try:
+        rel_paths = _git_files(project_root, staged=(mode == "staged"))
+    except FileNotFoundError:
+        return (
+            2,
+            [],
+            "\u274c verify_vbrief_conformance: 'git' executable not found on PATH.",
+        )
+    except RuntimeError as exc:
+        return (
+            2,
+            [],
+            (
+                f"\u274c verify_vbrief_conformance: git failed -- {exc}\n"
+                "  Recovery: ensure --project-root points at a git working tree."
+            ),
+        )
+
+    candidates = [
+        posix
+        for posix in (p.replace("\\", "/") for p in rel_paths)
+        if _is_vbrief_path(posix) and not _is_allow_listed(posix, custom_globs)
+    ]
+
+    findings: list[Finding] = []
+    for posix in candidates:
+        full = project_root / posix
+        try:
+            text = full.read_text(encoding="utf-8")
+        except OSError:
+            continue
+        try:
+            data = json.loads(text)
+        except json.JSONDecodeError:
+            # Malformed JSON is owned by vbrief:validate / verify:encoding; the
+            # conformance gate only reasons about parseable documents.
+            continue
+        findings.extend(scan_vbrief(posix, data))
+
+    if findings:
+        header = (
+            f"\u274c verify_vbrief_conformance: detected {len(findings)} bare "
+            f"key(s) across {len({f.path for f in findings})} file(s) (#1620).\n"
+            "  Every vBRIEF key MUST be 0.6 spec-core, x-directive/-namespaced, "
+            "or x-vbrief/-namespaced -- never bare.\n"
+            "  Fix: migrate misused/misspelled core fields to their core home "
+            "(see scripts/vbrief_migrate_conformance.py), or namespace a genuine\n"
+            "  extension under x-directive/. Allow-list a documented file "
+            "exception via --allow-list <path> (newline-separated globs)."
+        )
+        body = "\n".join(f.render() for f in findings[:50])
+        if len(findings) > 50:
+            body += f"\n  ... and {len(findings) - 50} more"
+        return 1, findings, f"{header}\n{body}"
+
+    msg = (
+        f"\u2713 verify_vbrief_conformance: {len(candidates)} vBRIEF file(s) "
+        "clean -- no bare keys (#1620)."
+    )
+    return 0, findings, msg
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="verify_vbrief_conformance.py",
+        description=(
+            "Deterministic vBRIEF 0.6 conformance gate (#1620). Flags any key "
+            "at document/plan/item level that is not 0.6 spec-core, "
+            "x-directive/-namespaced, or x-vbrief/-namespaced."
+        ),
+    )
+    mode = parser.add_mutually_exclusive_group()
+    mode.add_argument(
+        "--all",
+        dest="mode",
+        action="store_const",
+        const="all",
+        help="Scan all tracked files via 'git ls-files' (default).",
+    )
+    mode.add_argument(
+        "--staged",
+        dest="mode",
+        action="store_const",
+        const="staged",
+        help=(
+            "Scan only staged files via 'git diff --cached --name-only' "
+            "(used by .githooks/pre-commit)."
+        ),
+    )
+    parser.set_defaults(mode="all")
+    parser.add_argument(
+        "--project-root",
+        default=".",
+        help="Project root path (default: current working directory).",
+    )
+    parser.add_argument(
+        "--allow-list",
+        default=None,
+        help=(
+            "Path to a file with newline-separated glob patterns of "
+            "documented file exceptions. Lines starting with # are comments."
+        ),
+    )
+    parser.add_argument(
+        "--quiet",
+        action="store_true",
+        help="Suppress the OK message (errors still print).",
+    )
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    # Force UTF-8 stdout/stderr at hook-script entry (mirrors #814).
+    if hasattr(sys.stdout, "reconfigure"):
+        sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+    if hasattr(sys.stderr, "reconfigure"):
+        sys.stderr.reconfigure(encoding="utf-8", errors="replace")
+
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+    project_root = Path(args.project_root).resolve()
+    allow_list_path = Path(args.allow_list).resolve() if args.allow_list else None
+
+    code, _findings, msg = evaluate(
+        project_root,
+        mode=args.mode,
+        allow_list_path=allow_list_path,
+    )
+    if code == 0:
+        if not args.quiet:
+            print(msg)
+    else:
+        print(msg, file=sys.stderr)
+    return code
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/tasks/architecture.yml

@@ -0,0 +1,13 @@
+version: '3'
+
+vars:
+  DEFT_ROOT: '{{joinPath .TASKFILE_DIR ".."}}'
+
+tasks:
+  sor-preflight:
+    desc: "System-of-record architecture preflight. Run before stateful implementation: task architecture:sor-preflight -- --story-path <path>"
+    dir: '{{.USER_WORKING_DIR}}'
+    # Per conventions/task-caching.md: no sources/generates because this target
+    # forwards user-supplied story paths and flags via CLI_ARGS.
+    cmds:
+      - node "{{.DEFT_ROOT}}/packages/cli/dist/bin.js" architecture-preflight-sor {{.CLI_ARGS}}

package/tasks/cache.yml

@@ -0,0 +1,69 @@
+version: '3'
+
+# ---------------------------------------------------------------------------
+# cache.yml -- unified content cache + quarantine layer (#883 Story 2).
+#
+# Five-command surface (per the v1_scope.cache_commands list in
+# vbrief/active/2026-05-05-883-deft-cache-quarantine-v1.vbrief.json):
+#
+#   - cache:put         (cache one (source, key) entry from a raw JSON file)
+#   - cache:get         (print content.md path + meta.json contents)
+#   - cache:invalidate  (delete the entry directory + append audit)
+#   - cache:fetch-all   (orchestrate scm:* to bulk-populate a repo)
+#   - cache:prune       (drop entries older than the threshold)
+#
+# Storage layout: .deft-cache/<source>/<key>/{raw.json, content.md, meta.json}
+# plus the global .deft-cache/quarantine-audit.jsonl audit log. v1 ships
+# the github-issue source only; 5 additional sources (github-pr,
+# github-review, url, email, file) are deferred to v2 per the epic
+# deferred_to_v2 list.
+#
+# Per `conventions/task-caching.md` (#574): every task here forwards
+# `{{.CLI_ARGS}}` to a Python script, so NONE may declare `sources:` /
+# `generates:` -- a go-task short-circuit would silently drop user-facing
+# recovery flags (--force, --dry-run, --no-stale, etc.).
+# ---------------------------------------------------------------------------
+
+vars:
+  DEFT_ROOT: '{{joinPath .TASKFILE_DIR ".."}}'
+
+tasks:
+  put:
+    desc: "Cache an entry -- task cache:put -- <source> <key> --raw-file PATH [--ttl-seconds N]"
+    dir: '{{.USER_WORKING_DIR}}'
+    deps:
+      - task: :ts:build
+    cmds:
+      - node "{{.DEFT_ROOT}}/packages/cli/dist/bin.js" cache put {{.CLI_ARGS}}
+
+  get:
+    desc: "Read an entry -- task cache:get -- <source> <key> [--allow-stale | --no-stale]"
+    dir: '{{.USER_WORKING_DIR}}'
+    deps:
+      - task: :ts:build
+    cmds:
+      - node "{{.DEFT_ROOT}}/packages/cli/dist/bin.js" cache get {{.CLI_ARGS}}
+
+  invalidate:
+    desc: "Drop an entry -- task cache:invalidate -- <source> <key> [--reason TEXT]"
+    dir: '{{.USER_WORKING_DIR}}'
+    deps:
+      - task: :ts:build
+    cmds:
+      - node "{{.DEFT_ROOT}}/packages/cli/dist/bin.js" cache invalidate {{.CLI_ARGS}}
+
+  fetch-all:
+    desc: "Bulk populate -- task cache:fetch-all -- --source github-issue --repo OWNER/NAME [--batch-size N] [--delay-ms N] [--ttl-seconds N] [--no-refresh-closed to skip open→closed reconcile]"
+    dir: '{{.USER_WORKING_DIR}}'
+    deps:
+      - task: :ts:build
+    cmds:
+      - node "{{.DEFT_ROOT}}/packages/cli/dist/bin.js" cache fetch-all {{.CLI_ARGS}}
+
+  prune:
+    desc: "Drop expired or LRU-evict -- task cache:prune -- [--older-than-days 30] [--source github-issue] [--dry-run] [--to-cap]"
+    dir: '{{.USER_WORKING_DIR}}'
+    deps:
+      - task: :ts:build
+    cmds:
+      - node "{{.DEFT_ROOT}}/packages/cli/dist/bin.js" cache prune {{.CLI_ARGS}}

package/tasks/capacity.yml

@@ -0,0 +1,38 @@
+version: '3'
+
+vars:
+  DEFT_ROOT: '{{joinPath .TASKFILE_DIR ".."}}'
+
+# Capacity allocation accounting surface (#1419 Delivery Slice 4).
+#
+# `task capacity:show` derives per-bucket target-vs-actual mix from the vBRIEF
+# lifecycle folders (filesystem-truth, offline) with outcome (rework) and cost
+# overlays, and renders advisory mode when classified completions are below
+# minSampleSize. It is a DISPLAY surface and always exits 0 on a valid project
+# root (the companion `task verify:capacity` in tasks/verify.yml is the
+# three-state advisory gate).
+#
+# Conventions (mirroring tasks/scope.yml / tasks/verify.yml):
+#  * `dir: '{{.USER_WORKING_DIR}}'` so the script's CWD is the consumer project
+#    root, not deft/.
+#  * `DEFT_ROOT` defined locally via joinPath so the script path resolves on
+#    Windows (#566).
+#  * `{{.CLI_ARGS}}` forwarded bare (no double quotes, #577) and NO `sources:` /
+#    `generates:` so go-task does not swallow flags (#574 / conventions/
+#    task-caching.md).
+tasks:
+  show:
+    desc: "Capacity allocation target-vs-actual mix (advisory, offline). task capacity:show [-- --project-root <path>]"
+    dir: '{{.USER_WORKING_DIR}}'
+    deps:
+      - task: :ts:build
+    cmds:
+      - node "{{.DEFT_ROOT}}/packages/cli/dist/bin.js" capacity-show --project-root "{{.USER_WORKING_DIR}}" {{.CLI_ARGS}}
+
+  backfill:
+    desc: "One-time capacity-bucket backfill for completed vBRIEFs (#1606): infer capacityBucket from origin-issue labels + stamp completedAt from git. Dry-run by default; idempotent; never touches cost. -- task capacity:backfill [-- --apply] [--window-only] [--cache-dir <path>] [--json]"
+    dir: '{{.USER_WORKING_DIR}}'
+    deps:
+      - task: :ts:build
+    cmds:
+      - node "{{.DEFT_ROOT}}/packages/cli/dist/bin.js" capacity-backfill --project-root "{{.USER_WORKING_DIR}}" {{.CLI_ARGS}}

package/tasks/change.yml

@@ -0,0 +1,46 @@
+version: '3'
+
+vars:
+  # Per ../Taskfile.yml header: joinPath is evaluated eagerly by go-task
+  # templating and yields a native-separator absolute path so {{.DEFT_ROOT}}
+  # resolves correctly under uv on Windows (#566). Used here to pin
+  # `uv --project` against ancestor pyproject.toml leakage (#1011).
+  DEFT_ROOT: '{{joinPath .TASKFILE_DIR ".."}}'
+
+tasks:
+  changelog:check:
+    desc: Verify CHANGELOG.md has an [Unreleased] section with at least one entry
+    env:
+      PYTHONUTF8: "1"
+    cmds:
+      - cmd: >-
+          uv --project "{{.DEFT_ROOT}}" run python -c
+          "import sys, pathlib, re;
+          p = pathlib.Path('CHANGELOG.md');
+          (not p.exists()) and (print('FAIL: CHANGELOG.md not found'), sys.exit(1));
+          text = p.read_text('utf-8');
+          m = re.search(r'## \[Unreleased\][ \t]*\n(.*?)(?=\n## \[|$)', text, re.DOTALL);
+          (m is None) and (print('FAIL: No [Unreleased] section found in CHANGELOG.md'), sys.exit(1));
+          body = m.group(1);
+          entries = [l for l in body.splitlines() if l.strip().startswith('- ')];
+          (len(entries) == 0) and (print('FAIL: [Unreleased] section has no entries (no lines starting with \"- \")'), sys.exit(1));
+          print(f'OK: CHANGELOG.md [Unreleased] section has {len(entries)} entries')"
+
+  change:init:
+    desc: Create a new change proposal directory structure in history/changes/<name>/
+    cmds:
+      - cmd: >-
+          uv --project "{{.DEFT_ROOT}}" run python -c
+          "import sys, pathlib, json, re;
+          name = '{{.CLI_ARGS}}'.strip();
+          (not name) and (print('FAIL: Usage: task change:init -- <name>'), sys.exit(1));
+          (not re.match(r'^[\w][\w-]*$', name)) and (print('FAIL: Name must contain only alphanumeric characters, underscores, and hyphens'), sys.exit(1));
+          base = pathlib.Path('history/changes') / name;
+          base.exists() and (print(f'FAIL: {base} already exists'), sys.exit(1));
+          (base / 'specs').mkdir(parents=True, exist_ok=True);
+          proposal = {'vBRIEFInfo': {'version': '0.5'}, 'plan': {'title': name, 'status': 'draft', 'narratives': {'Problem': 'What is wrong or missing.', 'Change': 'What this proposal does about it.', 'Scope': 'In scope: ...  Out of scope: ...', 'Impact': 'What existing code/specs are affected.', 'Risks': 'What could go wrong.', 'Approach': 'How to implement the change.', 'Alternatives': 'What else was considered and why not.', 'Dependencies': 'What must exist before this works.'}}};
+          (base / 'proposal.vbrief.json').write_text(json.dumps(proposal, indent=2) + chr(10), encoding='utf-8');
+          tasks = {'vBRIEFInfo': {'version': '0.5'}, 'plan': {'title': name, 'status': 'draft', 'items': [], 'edges': []}};
+          (base / 'tasks.vbrief.json').write_text(json.dumps(tasks, indent=2) + chr(10), encoding='utf-8');
+          print(f'OK: Created change proposal at {base}/');
+          [print(f'  - {f}') for f in ['proposal.vbrief.json', 'tasks.vbrief.json', 'specs/']]"

package/tasks/changelog.yml

@@ -0,0 +1,24 @@
+version: '3'
+
+vars:
+  DEFT_ROOT: '{{joinPath .TASKFILE_DIR ".."}}'
+
+# Surface for the CHANGELOG.md union-merge helper (#911).
+#
+# Wraps scripts/resolve_changelog_unreleased.py, the canonical swarm-cascade
+# Phase 6 Step 1 helper that replaces the older HEAD-take-and-discard pattern
+# silently dropping rebasing-branch CHANGELOG entries on every cascade rebase.
+# See skills/deft-directive-swarm/SKILL.md Phase 6 Step 1 for the manual-
+# fallback contract -- this task is the canonical-path alternative.
+#
+# Per `conventions/task-caching.md` (#574): no `sources:` / `generates:`
+# because the task forwards user-facing flags via {{.CLI_ARGS}} (notably
+# --changelog-path / --dry-run / --quiet). The cached `cmds:` skip would
+# silently discard a recovery flag, and the helper is fast enough that a
+# real-time invocation does not need incremental-build caching.
+tasks:
+  resolve-unreleased:
+    desc: "Union-merge CHANGELOG.md [Unreleased] conflicts (#911) -- task changelog:resolve-unreleased [-- --changelog-path PATH] [--dry-run]"
+    dir: '{{.USER_WORKING_DIR}}'
+    cmds:
+      - node "{{.DEFT_ROOT}}/packages/cli/dist/bin.js" changelog-resolve-unreleased {{.CLI_ARGS}}