@deftai/directive-content 0.55.1 → 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/skills/deft-directive-swarm/SKILL.md

@@ -140,34 +140,15 @@ Loop body, per candidate (top-of-queue first):
 
 #### Phase 0d -- Cohort dispatch
 
-- ! After the promote-fill loop exits (cap reached, queue empty, or operator `stop`), `vbrief/pending/` now holds the cohort. On the interactive path, Phase 0e below captures the intended sub-agent backend before Step 0.5 hardens lifecycle state. Then the existing Step 0.5 (Lifecycle Bridge -- Promote and Activate Proposed Scope vBRIEFs, #1025) moves the cohort `pending/ -> active/`, and Steps 1-5 (readiness report, blockers, allocation, present, approval) proceed against the activated set. Existing swarm Phase 1+ (Select, Setup, Launch, Monitor, Review, Close) proceeds unchanged.
+- ! After the promote-fill loop exits (cap reached, queue empty, or operator `stop`), `vbrief/pending/` now holds the cohort. Phase 0e below is now deprecated (#1891) -- per-role operator model routing (`task swarm:routing-set`, #1739) supersedes the sub-agent backend enum; `task verify:routing -- --advise` is the session-start disclosure surface. The existing Step 0.5 (Lifecycle Bridge -- Promote and Activate Proposed Scope vBRIEFs, #1025) moves the cohort `pending/ -> active/`, and Steps 1-5 (readiness report, blockers, allocation, present, approval) proceed against the activated set. Existing swarm Phase 1+ (Select, Setup, Launch, Monitor, Review, Close) proceeds unchanged.
 
-#### Phase 0e -- Interactive sub-agent backend selection (#1568)
+#### Phase 0e -- Interactive sub-agent backend selection (DEPRECATED -- #1568 / superseded by #1739)
 
-! On the **interactive** swarm path, before Step 0.5 hardens lifecycle state and before any `task swarm:launch` / headless launch-manifest handoff is attempted, run `task policy:subagent-backends` and inspect `plan.policy.swarmSubagentBackend`.
+> **This phase is superseded.** Per-role operator model routing (`.deft/routing.local.json`, #1739) is the current mechanism for recording which model each worker role uses. Run `task verify:routing -- --advise` at session start and `task swarm:routing-set` to configure routing decisions. The `plan.policy.swarmSubagentBackend` enum and `task policy:subagent-backend(s)` surface are still present but deprecated (#1891); do not consult them for new work.
 
-! If `plan.policy.swarmSubagentBackend` is unset, ask the operator which subagent backend they intend to use. This question captures operator preference; probe availability is supporting evidence only. Display all stable backend choices with their probed status, but do NOT rank the menu by availability and do NOT imply `cursor-cloud` is the default just because it is probe-available.
+~ If `plan.policy.swarmSubagentBackend` is already set in the project policy and no `.deft/routing.local.json` is present, surface a one-line nudge asking the operator to run `task swarm:routing-set` to migrate to the routing surface before dispatch.
 
-Render the backend-selection prompt as a deterministic numbered menu in chat (or via a host UI that visibly preserves the same numeric option labels and exact displayed option text) with `Discuss` and `Back` final per [`../../contracts/deterministic-questions.md`](../../contracts/deterministic-questions.md):
-
-1. Local Composer/Cursor subagents (`composer`) -- intended local Composer-class coding agents; probe status: `<available|unavailable|unknown>`.
-2. Cursor cloud agents (`cursor-cloud`) -- intended remote/cloud agents; probe status: `<available|unavailable|unknown>`.
-3. Grok Build subagents (`grok-build`) -- intended `spawn_subagent` workers; probe status: `<available|unavailable|unknown>`.
-4. Discuss
-5. Back
-
-! After the operator selects a backend, ask whether to persist it to project policy with `task policy:subagent-backend -- <id>` or record it as a per-run launch-context choice for this swarm only. Render the persistence/per-run follow-up as a deterministic numbered menu with `Discuss` and `Back` as the final two options:
-
-1. Persist backend to project policy with `task policy:subagent-backend -- <id>` -- use this backend for future swarms.
-2. Record backend as a per-run launch-context choice for this swarm only -- do not change project policy.
-3. Discuss
-4. Back
-
-! If the operator chooses a backend whose probe status is unavailable or unknown, surface the remediation or uncertainty for that backend (for example, switch runtime, enable `spawn_subagent`, inject cloud credentials, or rerun the probe in the target environment) and stop before launch planning unless the operator explicitly records a per-run launch-context choice for a later environment where that backend will be available or verifiable.
-
-⊗ Treat probe availability as operator intent. A single probe-available backend is not a recommendation, default, or consent token; the operator must choose the intended backend in the interactive path when policy is unset.
-
-⊗ Add an interactive prompt to the headless / autonomous `task swarm:launch` path. Autonomous/headless launch remains fail-closed when neither `plan.policy.swarmSubagentBackend` nor an explicit launch-context backend choice is present; `scripts/swarm_launch.py` is the guardrail, not a prompt surface.
+⊗ Prompt the operator to select or persist a `swarmSubagentBackend` enum value for new work -- the routing surface (#1739) supersedes the enum; using the enum steers agents into a dead configuration path.
 
 #### Phase 0f -- Greenfield swarm-ready bootstrap (#1053)
 
@@ -429,9 +410,9 @@ Cross-references: `scripts/platform_capabilities.py` (#1557a), `scripts/github_a
 
 ! **Supported backend examples (none mandatory):** Composer-class coding agents, Grok Build `spawn_subagent` workers, Cursor/cloud agents, and future adapters are all first-class examples. No single backend is required — Grok Build is one implementation of provider-neutral routing, not the only target.
 
-~ **Policy surface (#1531a):** `plan.policy.swarmSubagentBackend` (set via `task policy:subagent-backend`) records the operator's preferred coding sub-agent provider for leaf workers; `task policy:subagent-backends` probes stable provider IDs and role capabilities. The policy complements — does not replace — per-dispatch provider selection at launch time.
+! **Operator model routing (#1739):** the concrete per-role model lives in the gitignored, per-machine `.deft/routing.local.json`, keyed by `(dispatch_provider, worker_role)`. Record a decision with `task swarm:routing-set -- --role <role> (--model <slug> | --harness-default)`. `task swarm:launch` resolves the active provider's route and stamps `resolved_model` + `model_source` into each C2 manifest record. When `resolved_model` is non-null, the monitor MUST pass it as the **model argument of the actual dispatch primitive** (e.g. the Task tool's `model` field for a Cursor sub-agent) — stamping the manifest is prep; a recorded model that never reaches the spawn call is the bug #1739 closes. Run `task verify:routing` before dispatching a cohort (pre-dispatch hard gate; fails when a dispatched role is undecided) and `task verify:routing -- --advise` at session start (non-blocking disclosure). For harness-bound providers (e.g. `grok`) only `--harness-default` is recordable and `resolved_model` stays null.
 
-! **Operator model routing (#1739, supersedes the swarmSubagentBackend enum):** the concrete per-role model lives in the gitignored, per-machine `.deft/routing.local.json`, keyed by `(dispatch_provider, worker_role)`. Record a decision with `task swarm:routing-set -- --role <role> (--model <slug> | --harness-default)`. `task swarm:launch` resolves the active provider's route and stamps `resolved_model` + `model_source` into each C2 manifest record. When `resolved_model` is non-null, the monitor MUST pass it as the **model argument of the actual dispatch primitive** (e.g. the Task tool's `model` field for a Cursor sub-agent) — stamping the manifest is prep; a recorded model that never reaches the spawn call is the bug #1739 closes. Run `task verify:routing` before dispatching a cohort (pre-dispatch hard gate; fails when a dispatched role is undecided) and `task verify:routing -- --advise` at session start (non-blocking disclosure). For harness-bound providers (e.g. `grok`) only `--harness-default` is recordable and `resolved_model` stays null.
+~ **DEPRECATED — Policy surface (#1531a / #1891):** `plan.policy.swarmSubagentBackend` (set via `task policy:subagent-backend`) was the previous mechanism for recording the operator's preferred coding sub-agent provider. It is superseded by per-role operator model routing above (#1739). The enum and associated `task policy:subagent-backend(s)` tasks remain functional but deprecated; hard deletion is tracked by #1860. Use `task swarm:routing-set` instead.
 
 ! **Role boundaries for cheaper leaf agents:** Cheaper, high-context leaf agents are appropriate for **leaf implementation** work in isolated worktrees when vBRIEF scope is tight and gates (`task check`, Greptile review cycle) hold. The following roles MUST remain on strong, review-capable agents regardless of backend availability:
 

package/skills/deft-directive-sync/SKILL.md

@@ -20,7 +20,7 @@ triggers:
 
 Session-start framework sync -- pull latest deft submodule updates, validate vBRIEF lifecycle structure, and detect stale origins.
 
-> **Canonical bootstrap / update path (post #1334 Epic, #1409):** Use the published Go installer binary (`deft-install` / platform-specific `install-*` from releases) to (re)bootstrap or update the framework payload. The canonical headless one-command refresh for an existing install is `deft-install --yes --upgrade --repo-root . --json` (drop `--json` for human-readable output) -- it actually replaces the framework payload in `.deft/core/` plus the manifest and AGENTS.md. After install the canonical `scripts/doctor.py --session --json` (or `task doctor`) runs automatically and, when the manifest sha shows the payload is stale, recommends that exact command. Legacy `run upgrade` / `task upgrade` are metadata-only acknowledgment (they do NOT replace the payload); git-submodule / `task framework:doctor` paths are back-compat only. See UPGRADING.md and the installer-doctor handoff in #1339/#1340.
+> **Canonical bootstrap / update path (#761 npm cutover):** Install and upgrade via npm: `npm i -g @deftai/directive` (install) or `npm i -g @deftai/directive@latest` (upgrade); Node >= 20 is required. For machines without Node, the frozen legacy Go installer (`deft-install` / platform-specific `install-*` from GitHub Releases) is a no-Node bootstrap bridge (#1912) -- migrate to npm once Node is available. After a session start the canonical `scripts/doctor.py --session --json` (`deft doctor` / `task doctor`) reports install + payload state and, when the manifest sha shows the payload is stale, recommends `npm i -g @deftai/directive@latest`. Legacy `run upgrade` / `task upgrade` are metadata-only acknowledgment (they do NOT replace the payload), and git-submodule / `task framework:doctor` paths are back-compat only -- the submodule sync in Phases 1-2 below is the legacy update flow, de-emphasized in UPGRADING.md / README. See UPGRADING.md and #761 / #1912.
 
 Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
 

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}}