@deftai/directive-content 0.110.0 → 0.112.0

package/skills/deft-directive-swarm/references/host-grok-build.md

@@ -15,7 +15,7 @@ Minimal runtime contract for the Grok Build dispatch-provider path (one supporte
 - One isolated git worktree per agent (identical to the Warp path — see Phase 2)
 - Workers launched via `spawn_subagent` dispatch (Phase 3 Step 2d)
 - Monitor coordination via worktree-state polling (`git status`, `git log`) and `get_command_or_subagent_output`
-- Review-cycle sub-agents spawned via `spawn_subagent` (not `start_agent`)
+- Review-cycle **sibling** monitors spawned via `spawn_subagent` by the **parent/orchestrator** (not `start_agent`). Implementation leaves MUST NOT nested-spawn a review-monitor -- see Nested spawn_subagent boundary below.
 
 This path became first-class in #1342 (platform adapter slices 1-3) and is fully documented in Phase 3 Step 2d and Phase 4. Grok Build + Windows users should also see #1353 (§3.5 in `templates/agent-prompt-preamble.md`) for shell output capture limitations that affect `get_command_or_subagent_output` in PowerShell 5.1 contexts. Refs #1342, #1331.
 
@@ -23,17 +23,33 @@ This path became first-class in #1342 (platform adapter slices 1-3) and is fully
 
 ### Step 2d: Grok Build Launch (spawn_subagent available)
 
-! When the platform descriptor is `grok-build` (spawn_subagent detected, no start_agent, no WARP_*, no Cursor `Task`, no OpenClaw `sessions_spawn`), dispatch each worker via `spawn_subagent` with:
+! When the platform descriptor is `grok-build` (spawn_subagent detected, no start_agent, no WARP_*, no Cursor `Task`, no OpenClaw `sessions_spawn`, no Grok Bot unique signals), dispatch each worker via `spawn_subagent` with:
 0. Create `<worktree>/.deft-scratch/subagent-status/` before spawn if launch/pre-dispatch did not already, and instruct the worker to heartbeat + commit early (#3730).
 1. The canonical `templates/agent-prompt-preamble.md` content as the preamble
 2. The standard worktree prompt (STEP 1-6 from the Prompt Template below), adapted to use `get_command_or_subagent_output` for polling rather than `start_agent` lifecycle events
-3. The worktree path set to the agent's isolated git worktree
+3. `tool_input.cwd` set to the agent's reserved linked worktree. Grok implement dest is `cwd` only. Do not pass `worktree_path`, `worktreePath`, `worktree`, or `isolation=worktree`.
+
+! **Parent ritual HEAD-discontinuous / dest occupancy deny class (#4215).** Native `spawn_subagent` with `cwd` to a dest-proven reserved linked worktree must not require a live parent primary ritual. Occupancy-refused on the contended primary is why `session:start --rearm` on master is the wrong recovery, not a spawn skip. If native spawn is denied, record that deny text in the handback. CLI `grok --cwd` is last-resort after that deny, not a habit after the first failure. Do not dual-launch CLI and `spawn_subagent` on the same unit. Do not document CLI as the real Grok Build launch path.
 
 ~ This is the first-class non-Warp path. Workers use worktree state polling (`git status`, `git log`) and `get_command_or_subagent_output` as their coordination channel instead of Warp tab state.
 
 ! Design-critique N≥3 other-family seats are not `spawn_subagent` Grok catalog rows. When `claude` / `codex` resolve on PATH, CLI-spawn those seats (`content/docs/grok-build-subscription-setup.md`). Paste-ready is fallback. Normative stop: `content/contracts/design-critique.md` Envelope and ceiling (#4067).
 
 
+## Nested spawn_subagent boundary (#4130 / #2797 analogue)
+
+! Nested `spawn_subagent` (implementation leaf spawning leaf) is unsupported for an Approach 1 review-monitor. Nested spawn does not report to the parent, and the parent cannot re-prompt a live child (`resume_from` requires terminal). A Grok Build **implementation leaf** MUST NOT nested-spawn a second-level review-monitor via `spawn_subagent`. Prefer either:
+
+- (a) a `drive-to: merge-ready` leaf that owns a blocking dual-invoke `pr:watch` (`deft pr:watch` then `task deft:pr:watch`) in its own process, then `pr:merge-ready` / merge in the same loop, or
+- (b) `stop-at: pr-open` with the dispatcher (parent that owns `spawn_subagent`) launching a sibling monitor and registering it via dual-invoke `review-monitor:register -- --platform-primitive spawn_subagent`.
+
+! Top-level parents/orchestrators that own `spawn_subagent` MAY Approach-1 background a review-monitor.
+
+⊗ An implementation leaf backgrounds a nested `spawn_subagent` poller and exits claiming monitoring is active.
+⊗ Invent mid-flight message-later on grok-build as a substitute for this boundary.
+
+If the leaf needs another agent, it stops and reports `BLOCKED`. The parent owns the next spawn.
+
 ## Monitor notes
 
 ! Heartbeat liveness on the Grok Build hybrid path is required — see `references/core-phase-4.md` Heartbeat liveness check (#1365) and `docs/subagent-heartbeat.md`.

package/skills/deft-directive-swarm/references/host-grokbot.md

@@ -0,0 +1,151 @@
+# Host adapter: Grok Bot
+
+Legend (RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
+
+Descriptor: `grok-bot`. Grok Bot is **not** Grok Build. Register primitive: `grok-bot-executor` (`task review-monitor:register -- --platform-primitive grok-bot-executor`).
+
+Load this file only after detect selects Grok Bot. Do not load other host adapters (#2928).
+
+## Detection spike (ordered matrix placement) — #4201
+
+! Grok Bot MUST be classified with **Grok-Bot-unique** signals. Probe those signals **before** probe 7 (`spawn_subagent` → `grok-build`). Same class as Claude-before-Task (#3134) and OpenClaw-before-grok-build (#2875).
+
+⊗ Classify Grok Bot from bare `spawn_subagent` alone — that misclassifies as `grok-build`.
+⊗ Classify Grok Bot from bare `Task` alone — that misclassifies as `cursor-composer`.
+
+### Skill-side ordered probe (tool set + env)
+
+Probe order (must match engine `probeMonitoringTier` / `resolveDispatchProvider`):
+
+1. `start_agent` → `warp-orchestrated`
+2. `WARP_*` → `warp-manual`
+3. Cursor `Task` **with Cursor signals** (`CURSOR_COMPOSER` / `CURSOR_AGENT` or Cursor-only Task surface) → `cursor-composer` / `cursor-cloud-agent`
+4. Claude Code (Claude-unique signals) → `claude-code`
+5. OpenClaw `sessions_spawn` → `openclaw`
+6. **Grok Bot** (this descriptor) — unique signals below → `grok-bot`
+7. `spawn_subagent` → `grok-build`
+8. else → `generic-terminal` (Tier 3)
+
+### Grok-Bot-unique signals (any one is sufficient when earlier probes are absent)
+
+| Signal | Notes |
+|--------|--------|
+| Question widgets | Operator-gate UI (`ask_user_question` / host widgets). Phase 0 / mid-scope / dual-stop map here. |
+| Task / executor / CloudAgent | Worker spawn surface — **not** Cursor `Task` (requires `CURSOR_*`) and **not** Grok Build `spawn_subagent` |
+| Routines | Grok Bot scheduled / routine surface |
+| Short main-chat beats | Parent consolidate on the main chat (not a subagent pane) |
+| `DEFT_PROBE_GROK_BOT` / `DEFT_HAS_GROK_BOT_WIDGETS` / `DEFT_HAS_GROK_BOT_EXECUTOR` | Explicit framework probe / override |
+| `DEFT_AGENT_RUNTIME=grok-bot` (or `grokbot`) | Explicit runtime stamp |
+| `GROK_BOT` | Host stamp |
+
+! When both Cursor and Grok Bot signals could appear, **Cursor probes win** (earlier in the chain).
+! When both OpenClaw and Grok Bot signals could appear, **OpenClaw probes win** (earlier in the chain).
+! When Grok Bot unique signals are present **and** `spawn_subagent` is also present, **Grok Bot wins**. That is the misclassification this adapter exists to close.
+
+! Engine env probe is env-centric (same pattern as Claude `CLAUDECODE` / Cursor `CURSOR_*`); skill prose names the tool fingerprint for agents that can see the tool set.
+
+## Operator gates — widgets keep Discuss and Back (#1470 / #1563)
+
+! Phase 0 / mid-scope / dual-stop operator gates on this host MUST use question widgets (or a numbered chat menu) that **visibly preserve** canonical numbered options, with the final two labels `Discuss` and `Back` in that order.
+
+! Widget labels MUST include the canonical number (for example `1. Accept`). Agents accept fallback chat replies only when they match the displayed number or the exact displayed option text.
+
+⊗ Drop `Discuss` / `Back` because the host widget UI has an `Other` affordance or alphabetic shortcuts — those do not satisfy [`../../../contracts/deterministic-questions.md`](../../../contracts/deterministic-questions.md) Host-UI portability (#1563).
+
+## Consumer facade — three verbs (Phases 0–6 stay internal)
+
+Expose **propose / launch / status**. Keep swarm Phases 0–6 as lazy-loaded depth. Do not load all host adapters just in case (#2928).
+
+| Verb | Operator meaning | Depth (load on demand) |
+|------|------------------|------------------------|
+| **propose** | Name the cohort (stories / xBRIEFs), file-overlap, worktree plan. Does not spawn. | [`core-phase-0.md`](core-phase-0.md) then [`core-phase-1-2.md`](core-phase-1-2.md) |
+| **launch** | Emit the C2 launch-manifest (`task swarm:launch`) then spawn via this adapter. Worktree isolation MUST before parallel spawn. | [`core-phase-3.md`](core-phase-3.md) + this file |
+| **status** | Heartbeats, worktree git, PR/review state. Parent consolidate as **short main-chat beats**. | [`core-phase-4.md`](core-phase-4.md) |
+
+! Human decision: one clear ask, then stop. Do not auto-dispatch arcs without operator consent (#3578 / #1702).
+
+## Thin skill pack (Grok Bot consumers)
+
+Discovery set — **thin routers only**. Each item points at the existing Directive skill. ⊗ Put normative contract bodies in these routers.
+
+| Router | Points at |
+|--------|-----------|
+| setup | `skills/deft-directive-setup/SKILL.md` |
+| xbrief | `skills/deft-directive-xbrief/SKILL.md` |
+| triage | `skills/deft-directive-triage/SKILL.md` (work selection: `plan-sequence:current` then `triage:queue`) |
+| swarm (facade) | this adapter + `skills/deft-directive-swarm/SKILL.md` (propose / launch / status above) |
+| build | `skills/deft-directive-build/SKILL.md` |
+| **arc** | Companion **#4202** — do not implement the design-critique thin arc router here |
+
+## Doctor / cold-start (one happy path)
+
+! One narratable path: `npx @deftai/directive doctor` → follow its one `Next command:` → optional agent-driven setup (`skills/deft-directive-setup/SKILL.md`).
+
+! Hide package-manager and offline forks behind doctor. Do not invent a second Grok Bot install ladder. Category: Grok Bot is a **coding host**; Directive remains the repo practice layer (`docs/CATEGORY.md`).
+
+## GitHub connector preference
+
+! Prefer GitHub MCP / connector tools when the host exposes them. Fall back to `gh` / `ghx` (REST) when the connector is absent.
+
+⊗ Invent a Grok-Bot-only GitHub client. The SCM contract stays `content/scm/github.md`.
+
+## Launch — Step 2h
+
+### Step 2h: Grok Bot Launch (unique signals detected) — #4201
+
+! When the platform descriptor is `grok-bot` (Grok-Bot-unique signals detected; no `start_agent`, no `WARP_*`, no Cursor classification, no Claude Code, no OpenClaw `sessions_spawn`), dispatch each **leaf worker** via Task / executor / CloudAgent with:
+
+1. The canonical `templates/agent-prompt-preamble.md` content as the preamble.
+2. The standard worktree prompt (STEP 1–6 from the Prompt Template in `references/core-ops.md`).
+3. The worktree path set to the agent's isolated git worktree.
+4. ! **Worktree isolation MUST before parallel spawn** (Phase 2 / #4066). Fail loud if a parallel cohort would share the repo root.
+5. ! **Background / non-blocking spawn** for any worker or poller whose loop runs longer than a short task (~3 min) so the parent main-chat stays interactive (#1880 Gap D).
+6. ! **Deliberate model routing (#1739):** resolve `(dispatch_provider=grok-bot, worker_role)` via `task verify:routing` / `task swarm:routing-set`. Grok Bot is harness-bound — record `--harness-default`; `resolved_model` stays null.
+
+! Parent consolidate → **short main-chat beats** (not a second worker pane dump). Human decision → one clear ask then stop.
+
+~ This is the first-class Grok Bot path. It is **Tier 1 → Approach 1**. It MUST NOT be misclassified as `grok-build` via bare `spawn_subagent` or as `cursor-composer` via bare `Task`.
+
+! Long pollers MUST honour the sub-agent heartbeat contract (`docs/subagent-heartbeat.md`, #1166).
+
+## Nested executor boundary
+
+! Nested Task / executor / CloudAgent (implementation leaf spawning leaf) is unsupported for an Approach 1 review-monitor. A Grok Bot **implementation leaf** MUST NOT nested-spawn a second-level review-monitor. Prefer either:
+
+- (a) a `drive-to: merge-ready` leaf that owns a blocking dual-invoke `pr:watch` (`deft pr:watch` then `task deft:pr:watch`) in its own process, or
+- (b) `stop-at: pr-open` with the dispatcher (parent that owns the executor primitive) launching a sibling monitor and registering it via dual-invoke `review-monitor:register -- --platform-primitive grok-bot-executor`.
+
+! Top-level parents/orchestrators that own the executor primitive MAY Approach-1 background a review-monitor.
+
+⊗ An implementation leaf backgrounds a nested executor poller and exits claiming monitoring is active.
+
+If the leaf needs another agent, it stops and reports `BLOCKED`. The parent owns the next spawn.
+
+## Babysit / review-monitor
+
+! Babysit / PR shepherd on Grok Bot is **Approach 1** via executor / CloudAgent (`skills/deft-directive-review-cycle/SKILL.md`). Register with `--platform-primitive grok-bot-executor`.
+
+! Long review-monitor ownership (>~3 min) MUST NOT block the parent main chat — background executor + parent yield (#1880 Gap D); heartbeats per #1166.
+
+⊗ Fall through to Approach 3 blocking `sleep` poll when Grok Bot executor spawn is available.
+⊗ Misclassify Grok Bot as `grok-build` because `spawn_subagent` is also on the tool list (#4201).
+⊗ Misclassify Grok Bot as `cursor-composer` because a Task-like tool exists without Cursor signals (#4201).
+
+## Monitor / completion channel
+
+! Completion is host completion / parent main-chat announce for the Grok Bot executor path. Do not poll via Grok Build `get_command_or_subagent_output` unless that primitive is actually present under descriptor `grok-build`.
+
+! Long pollers MUST honour on-disk heartbeats (`docs/subagent-heartbeat.md`, #1166).
+
+! Pre-spawn verification and Duplicate-Agent rules in `references/core-phase-4.md` apply.
+
+## Retained / continue-by-id (#3158)
+
+! **Default one-shot after executor completion:** Grok Bot executor leaves that exit are typically terminal — prefer **split-dispatch** for mid-scope user-approval gates (#954) unless the host documents continue/resume of the same agent id.
+? When the host supports re-attach or re-prompt of a still-live executor with context intact, treat as **retain-capable** for message-later / steer-mid-flight.
+! Nested-executor boundary above still forbids implementation leaves from retaining a second-level review-monitor.
+~ Stance: orchestration only (#3164). Grok Bot stays the coding host / CoS cockpit. Directive does not own Slack/calendar/bot roster orchestration.
+
+## Phase handoff (see also core #2934)
+
+! After coding cohort complete, same-turn next-phase tool dispatch or explicit terminal status — see `references/core-phase-5-6.md` and the thin SKILL MUST block. ⊗ End the turn with only narrative “I will spawn…”.

package/tasks/docs.yml

@@ -1,5 +1,8 @@
 version: '3'
 
+vars:
+  DEFT_ROOT: '{{joinPath .TASKFILE_DIR ".."}}'
+
 # Maintainer documentation tasks.
 #
 # docs:rule-map renders the Rule Map: a maintainer-facing view of how the
@@ -35,3 +38,19 @@ tasks:
       - task: :engine:invoke
         vars:
           ENGINE_CMD: 'rule-map --project-root "{{.USER_WORKING_DIR}}" --check'
+
+  capability-map:
+    desc: "Generate content/docs/capabilities.md from the capability overlay (#4099)"
+    dir: '{{.USER_WORKING_DIR}}'
+    deps:
+      - task: :engine:_ts-build
+    cmds:
+      - node "{{.DEFT_ROOT}}/packages/core/dist/docs/capability-map.js" --project-root "{{.USER_WORKING_DIR}}" {{.CLI_ARGS}}
+
+  capability-map:check:
+    desc: "Fail if committed content/docs/capabilities.md is stale or the overlay disagrees with registries (#4099)"
+    dir: '{{.USER_WORKING_DIR}}'
+    deps:
+      - task: :engine:_ts-build
+    cmds:
+      - node "{{.DEFT_ROOT}}/packages/core/dist/docs/capability-map.js" --project-root "{{.USER_WORKING_DIR}}" --check

package/tasks/migrate.yml

@@ -23,7 +23,9 @@ tasks:
           ENGINE_CMD: 'migrate-preflight --project-root "{{.USER_WORKING_DIR}}" --deft-root "{{.DEFT_ROOT}}" {{.CLI_ARGS}}'
 
   xbrief:
-    desc: "Migrate consumer vbrief/ layout to xbrief/ with semantic v0.6->v0.8 transforms (#2110 / #2034)."
+    # Hop 2 on current npm (#4092). Hop 1 (`migrate:vbrief`) is frozen on the
+    # v0.59.0 tag only — current deposits must not ship that target.
+    desc: "Migrate consumer vbrief/ layout to xbrief/ with semantic v0.6->v0.8 transforms (#2110 / #2034). Hop 2 of the frozen two-hop path (#4092)."
     dir: '{{.USER_WORKING_DIR}}'
     deps:
       - task: :engine:_ts-build

package/tasks/policy.yml

@@ -21,8 +21,8 @@ tasks:
     #   --format=text|json    -- machine-stable scripting envelope
     #   --changed-only         -- drop default-source rows
     #   --field=<name>         -- single-field isolation
-    # The legacy `python -m scripts.policy show` CLI continues to work for
-    # any scripts that called it directly (back-compat for #746 consumers).
+    # Inspect via engine:invoke / packages/cli/dist (policy:show). The
+    # retired `python -m scripts.policy` launcher is gone.
     desc: "Inspect every registered typed-policy field on vbrief/PROJECT-DEFINITION.vbrief.json (#1148 / N8). -- task policy:show [-- --format=json] [--changed-only] [--field=<name>]"
     dir: '{{.USER_WORKING_DIR}}'
     deps:

package/tasks/scm.yml

@@ -14,6 +14,7 @@ version: '3'
 #   - scm:issue:close   (thin wrapper over `ghx|gh issue close`)
 #   - scm:issue:edit    (thin wrapper over `ghx|gh issue edit`)
 #   - scm:issue:design-critique-chip (#3642 closed catalog remaining-set)
+#   - scm:issue:work-claim (#4200 same-issue busy flag)
 #   - scm:body:*        (#1555 safe Markdown body posting via github-body TS CLI)
 #
 # Each command is a thin pass-through to `ghx <verb>` (when ghx is on PATH)
@@ -92,7 +93,7 @@ tasks:
           ENGINE_CMD: 'scm issue edit {{.CLI_ARGS}}'
 
   issue:design-critique-chip:
-    desc: "[#3642] Exclusive design-critique catalog chip -- task scm:issue:design-critique-chip -- --issue N --chip triage-ready|mechanism-shaped [--repo OWNER/NAME]"
+    desc: "[#3642] Exclusive design-critique catalog chip -- task scm:issue:design-critique-chip -- --issue N --chip triage-ready|mechanism-shaped|recut-needed [--repo OWNER/NAME]"
     dir: '{{.USER_WORKING_DIR}}'
     deps:
       - task: :engine:_ts-build
@@ -101,6 +102,16 @@ tasks:
         vars:
           ENGINE_CMD: 'scm issue design-critique-chip {{.CLI_ARGS}}'
 
+  issue:work-claim:
+    desc: "[#4200] Same-issue busy flag -- task scm:issue:work-claim -- claim|show|release --issue N [--repo OWNER/NAME] [--json]"
+    dir: '{{.USER_WORKING_DIR}}'
+    deps:
+      - task: :engine:_ts-build
+    cmds:
+      - task: :engine:invoke
+        vars:
+          ENGINE_CMD: 'scm issue work-claim {{.CLI_ARGS}}'
+
   body:issue:create:
     desc: "[#1555] Safely create an issue body from --body-file without shell Markdown interpolation"
     dir: '{{.USER_WORKING_DIR}}'

package/tasks/scope.yml

@@ -5,33 +5,24 @@ vars:
 
 # scope lifecycle tasks.
 #
-# IMPORTANT: every task sets ``dir: '{{.USER_WORKING_DIR}}'`` so the Python
-# script's CWD is the consumer project root, NOT ``deft/``. The script path
-# is resolved via ``{{.DEFT_ROOT}}/scripts/`` (DEFT_ROOT is defined locally
-# in this file's `vars:` block via ``{{joinPath .TASKFILE_DIR ".."}}`` --
-# see ../Taskfile.yml for why root-level definition is avoided) so it
-# still points at ``deft/scripts/scope_lifecycle.py`` after the dir switch.
-# The previous ``{{.TASKFILE_DIR}}/../scripts/`` form broke on Windows
-# under `uv --project "{{.DEFT_ROOT}}" run python` (#566) because mixed-separator traversal
-# normalizes incorrectly and drops the deft/ prefix.
+# IMPORTANT: every task sets ``dir: '{{.USER_WORKING_DIR}}'`` so
+# engine:invoke CWD is the consumer project root, NOT the framework tree.
+# DEFT_ROOT is defined locally in this file's `vars:` block via
+# ``{{joinPath .TASKFILE_DIR ".."}}`` -- see ../Taskfile.yml for why
+# root-level definition is avoided.
 #
-# CLI_ARGS: passed to the script raw / unquoted. go-task shell-escapes
-# CLI_ARGS with single quotes on its own, so wrapping the interpolation
-# in Taskfile-level double quotes produces ``"'path'"`` at dispatch time
-# on Windows (pwsh/cmd preserve nested quotes verbatim), and Python's
-# argv receives a literal single-quote-prefixed filename that fails to
-# open (#577). All seven scope:* commands therefore forward
-# ``{{.CLI_ARGS}}`` bare -- matching migrate.yml / prd.yml / issue.yml /
-# reconcile.yml.  ``scope_lifecycle.py`` handles both absolute and
-# relative values via ``_resolve_file_path`` + ``resolve_project_root``
-# -- the script owns path resolution, the task just forwards
-# ``--project-root`` so detection never silently falls back to deft's
-# own tree (#535). Relative paths resolve against the consumer root
-# thanks to ``--project-root``; absolute paths are used as-is.
+# Handler: packages/cli/src/scope-lifecycle.ts via engine:invoke
+# (packages/cli/dist). Help registry:
+# packages/core/src/triage/help/registry-data.ts (edit in place).
 #
-# ``env: PYTHONUTF8: "1"`` is set per-task as a belt-and-suspenders guard
-# for Windows (cp1252 default crashes on -- / -> / x / !); the top-level
-# Taskfile.yml also sets this (#540).
+# CLI_ARGS: passed raw / unquoted. go-task shell-escapes CLI_ARGS with
+# single quotes on its own, so wrapping the interpolation in
+# Taskfile-level double quotes produces ``"'path'"`` at dispatch time
+# on Windows (#577). All scope:* commands therefore forward
+# ``{{.CLI_ARGS}}`` bare -- matching migrate.yml / prd.yml / issue.yml /
+# reconcile.yml. The TypeScript handler owns path resolution; the task
+# forwards ``--project-root`` so detection never silently falls back to
+# the framework tree (#535).
 
 tasks:
 

package/tasks/triage-actions.yml

@@ -20,10 +20,9 @@ version: '3'
 # (#74), `task pr:check-protected-issues` (#702), and `task verify:encoding`
 # (#798).
 #
-# Companion script: scripts/triage_actions.py
-# Companion tests:  tests/test_triage_actions.py
-# Upstream contracts (frozen): scripts/candidates_log.py (#845 Story 2 audit log),
-#                              scripts/cache.py          (#883 Story 2 unified cache).
+# Handler: packages/cli/src/triage-actions.ts via engine:invoke (packages/cli/dist).
+# Help registry: packages/core/src/triage/help/registry-data.ts (edit in place).
+# Audit/cache contracts live in packages/core (candidates log + unified cache).
 
 vars:
   DEFT_ROOT: '{{joinPath .TASKFILE_DIR ".."}}'

package/tasks/triage-bootstrap.yml

@@ -15,8 +15,8 @@ version: '3'
 #   tasks/triage-bulk.yml       (Story 4 -- bulk ops + freshness)
 #   tasks/triage-bootstrap.yml  (Story 6 -- this file)
 #
-# Companion script: scripts/triage_bootstrap.py
-# Companion test:   tests/test_triage_bootstrap.py
+# Handler: packages/cli/src/triage-bootstrap.ts via engine:invoke (packages/cli/dist).
+# Help registry: packages/core/src/triage/help/registry-data.ts (edit in place).
 #
 # Per `conventions/task-caching.md` (#574): NO `sources:` / `generates:`
 # declarations on this task because user-facing recovery flags

package/tasks/triage-bulk.yml

@@ -11,13 +11,12 @@ version: '3'
 # are hidden from `task -l`.
 #
 # The disable-gate `cmds:` blocks introduced by PR #916 (#915 hot-fix) were
-# REVERSED once scripts/triage_bulk.py was rewritten to walk the local
-# cache instead of live `gh issue list`. As of #883 Story 3 the cache walk
-# consumes the unified `cache:get` surface
-# (`.deft-cache/github-issue/<owner>/<repo>/<N>/`); the four `bulk-*`
-# targets continue to invoke triage_bulk.py directly. The cache-empty
-# hard-fail (exit 2) and Tier-2 audit-log short-circuit are enforced
-# inside triage_bulk.py itself (#915 fix).
+# reversed once bulk ops walked the local cache instead of live `gh issue
+# list`. As of #883 Story 3 the cache walk consumes the unified `cache:get`
+# surface (`.deft-cache/github-issue/<owner>/<repo>/<N>/`); the four
+# `bulk-*` targets invoke packages/cli/src/triage-bulk.ts via engine:invoke.
+# The cache-empty hard-fail (exit 2) and Tier-2 audit-log short-circuit are
+# enforced inside that handler (#915 fix).
 #
 # Per `conventions/task-caching.md` (#574): every target here accepts user
 # flags via `{{.CLI_ARGS}}` (--label, --author, --age-days, --cluster,

package/tasks/triage-classify.yml

@@ -13,8 +13,8 @@ version: '3'
 # `--validate`, `--project-root`) are forwarded via {{.CLI_ARGS}} and
 # go-task's incremental-build cache layer would silently swallow them.
 #
-# Companion script: scripts/triage_classify.py (+ scripts/_triage_classify_cli.py)
-# Companion tests:  tests/test_triage_classify.py
+# Handler: packages/cli/src/triage-classify.ts via engine:invoke (packages/cli/dist).
+# Help registry: packages/core/src/triage/help/registry-data.ts (edit in place).
 # Current Shape:    https://github.com/deftai/directive/issues/1129#issuecomment-4471901622
 
 vars:

package/tasks/triage-queue.yml

@@ -17,8 +17,8 @@ version: '3'
 # `--project-root`, `--cache-root`, `--audit-log`) via {{.CLI_ARGS}} and
 # go-task's incremental-build cache layer would silently swallow them.
 #
-# Companion script: scripts/triage_queue.py (+ scripts/_triage_queue_cli.py)
-# Companion tests:  tests/test_triage_queue.py
+# Handler: packages/cli/src/triage-queue.ts via engine:invoke (packages/cli/dist).
+# Help registry: packages/core/src/triage/help/registry-data.ts (edit in place).
 # Current Shape:    https://github.com/deftai/directive/issues/1128#issuecomment-4471272093
 
 vars:

package/tasks/triage-reconcile.yml

@@ -12,8 +12,8 @@ version: '3'
 # `--project-root`) are forwarded via {{.CLI_ARGS}} and go-task's
 # incremental-build cache layer would silently swallow them.
 #
-# Companion script: scripts/triage_reconcile.py
-# Companion tests:  tests/test_triage_reconcile.py
+# Handler: packages/cli/src/triage-reconcile.ts via engine:invoke (packages/cli/dist).
+# Help registry: packages/core/src/triage/help/registry-data.ts (edit in place).
 # Pattern reference: tasks/triage-bootstrap.yml (#845 Story 6).
 
 vars:

package/tasks/triage-scope-drift.yml

@@ -13,8 +13,8 @@ version: '3'
 # {{.CLI_ARGS}} and go-task's incremental-build cache layer would silently
 # swallow them.
 #
-# Companion script: scripts/triage_scope_drift.py (+ shims).
-# Companion tests:  tests/test_triage_scope_drift.py.
+# Handler: packages/cli/src/triage-scope-drift.ts via engine:invoke (packages/cli/dist).
+# Help registry: packages/core/src/triage/help/registry-data.ts (edit in place).
 
 vars:
   DEFT_ROOT: '{{joinPath .TASKFILE_DIR ".."}}'

package/tasks/triage-scope.yml

@@ -14,8 +14,8 @@ version: '3'
 # via {{.CLI_ARGS}} and go-task's incremental-build cache layer would
 # silently swallow them.
 #
-# Companion script: scripts/triage_scope.py (+ scripts/_triage_scope_cli.py)
-# Companion tests:  tests/test_triage_scope.py
+# Handler: packages/cli/src/triage-scope.ts via engine:invoke (packages/cli/dist).
+# Help registry: packages/core/src/triage/help/registry-data.ts (edit in place).
 # Current Shape:    https://github.com/deftai/directive/issues/1131#issuecomment-4471901494
 
 vars:

package/tasks/triage-smoketest.yml

@@ -13,9 +13,9 @@ version: '3'
 # `--cache-only`, `--fixture`) are forwarded via {{.CLI_ARGS}} and
 # go-task's incremental-build cache layer would silently swallow them.
 #
-# Companion script:   scripts/triage_smoketest.py (+ scripts/_triage_smoketest_stages.py)
-# Companion fixture:  tests/fixtures/triage_smoketest/
-# Companion tests:    tests/test_triage_smoketest.py + tests/test_triage_smoketest_fixture.py
+# Handler: packages/cli/src/triage-smoketest.ts via engine:invoke (packages/cli/dist).
+# Help registry: packages/core/src/triage/help/registry-data.ts (edit in place).
+# Fixture: tests/fixtures/triage_smoketest/
 # Pattern reference:  tasks/triage-summary.yml (D2 / #1122).
 
 vars:

package/tasks/triage-subscribe.yml

@@ -12,8 +12,8 @@ version: '3'
 # declarations -- user-facing flags (`--label`, `--milestone`, `--issue`,
 # `--issue-note`, `--actor`) are forwarded via {{.CLI_ARGS}}.
 #
-# Companion script: scripts/triage_subscribe.py (+ shim).
-# Companion tests:  tests/test_triage_subscribe.py.
+# Handler: packages/cli/src/triage-subscribe.ts via engine:invoke (packages/cli/dist).
+# Help registry: packages/core/src/triage/help/registry-data.ts (edit in place).
 
 vars:
   DEFT_ROOT: '{{joinPath .TASKFILE_DIR ".."}}'

package/tasks/triage-summary.yml

@@ -12,8 +12,8 @@ version: '3'
 # `--no-history`, `--json`) are forwarded via {{.CLI_ARGS}} and go-task's
 # incremental-build cache layer would silently swallow them.
 #
-# Companion script: scripts/triage_summary.py
-# Companion tests:  tests/test_triage_summary.py
+# Handler: packages/cli/src/triage-summary.ts via engine:invoke (packages/cli/dist).
+# Help registry: packages/core/src/triage/help/registry-data.ts (edit in place).
 # Pattern reference: tasks/triage-scope.yml (D12 / #1131 / merged via #1190).
 
 vars:

package/tasks/triage-welcome.yml

@@ -13,8 +13,8 @@ version: '3'
 # `--no-subprocess`) are forwarded via {{.CLI_ARGS}} and go-task's
 # incremental-build cache layer would silently swallow them.
 #
-# Companion script: scripts/triage_welcome.py (+ scripts/_triage_welcome_cli.py)
-# Companion tests:  tests/test_triage_welcome.py
+# Handler: packages/cli/src/triage-welcome.ts via engine:invoke (packages/cli/dist).
+# Help registry: packages/core/src/triage/help/registry-data.ts (edit in place).
 # Pattern reference: tasks/triage-summary.yml (D2 / #1122).
 
 vars:

package/tasks/verify.yml

@@ -107,6 +107,14 @@ tasks:
         vars:
           ENGINE_CMD: 'verify-closing-keywords {{.CLI_ARGS}}'
 
+  docs-impact:
+    desc: "Declared-versus-touched documentation-impact check (#4099). --pr uses REST; --body-file for local. Fork PRs stay read-only."
+    deps:
+      - task: :engine:_ts-build
+    dir: '{{.USER_WORKING_DIR}}'
+    cmds:
+      - node "{{.DEFT_ROOT}}/packages/core/dist/docs/docs-impact.js" --project-root "{{.USER_WORKING_DIR}}" {{.CLI_ARGS}}
+
   license-sync:
     desc: "Drift guard for root LICENSE ↔ content/LICENSE.md and published package.json license fields (#2902). Three-state exit (0 clean / 1 drift / 2 config). Framework-source only."
     # Framework-source-only gate: reads THIS repo's LICENSE + package manifests.
@@ -369,6 +377,27 @@ tasks:
         vars:
           ENGINE_CMD: 'codebase-map-fresh --project-root "{{.USER_WORKING_DIR}}" {{.CLI_ARGS}}'
 
+
+  spec-prd-fresh:
+    desc: "Fail-closed SPECIFICATION.md / PRD.md render-freshness gate (#4086). Re-renders to a buffer and fails on banner or projection diff. Banner canon and full projection freshness are separate assertions. Modeled on verify:codebase-map-fresh."
+    dir: '{{.USER_WORKING_DIR}}'
+    deps:
+      - task: :engine:_ts-build
+    # Per conventions/task-caching.md: no sources/generates because this gate
+    # forwards project-root through CLI_ARGS.
+    cmds:
+      - task: :engine:invoke
+        vars:
+          ENGINE_CMD: 'verify:spec-prd-fresh --project-root "{{.USER_WORKING_DIR}}" {{.CLI_ARGS}}'
+
+  rule-map-fresh:
+    desc: "Fail-closed docs/RULE-MAP.md renderer freshness (#4095). Alias for docs:rule-map:check. Asserts byte-identical renderer output, filled grouping purposes, pack entries from named arrays, and Taskfile declaration counts. Not a consumer gate."
+    dir: '{{.USER_WORKING_DIR}}'
+    deps:
+      - task: :engine:_ts-build
+    cmds:
+      - task: :docs:rule-map:check
+
   session-ritual:
     desc: "Fail-closed session ritual verifier (#1348). Flags: --tier quick|gated / --json. Set DEFT_SESSION_RITUAL_SKIP=1 for headless workers and CI."
     dir: '{{.USER_WORKING_DIR}}'
@@ -401,7 +430,7 @@ tasks:
           ENGINE_CMD: 'verify:tools {{.CLI_ARGS}}'
 
   scm-boundary:
-    desc: "Detection-bound gate against raw `gh` / `ghx` subprocess calls outside `scripts/scm.py` (#1145 / N5). Scans verb-layer Python files (`scripts/triage_*.py`, `scripts/scope_*.py`, `scripts/slice_*.py`, `scripts/_triage_*.py`, `scripts/_scope_*.py`, `scripts/resume_conditions.py`, `scripts/issue_ingest.py`) and fails loud when any of them invoke `gh` directly instead of going through `scm.call(source, verb, args)`. Three-state exit (0 clean / 1 violations / 2 config error). Document an exception via `--allow-list <path>` (file with newline-separated glob patterns)."
+    desc: "Detection-bound gate against raw `gh` / `ghx` subprocess calls (#1145 / N5). TypeScript verbs route through packages/core/src/scm/call.ts. The scanner still globs retired scripts/triage_*.py paths (vacuous; owner packages/core/src/verify-source/scm-boundary.ts SCOPE_GLOBS). Three-state exit (0 clean / 1 violations / 2 config error). Document an exception via `--allow-list <path>`."
     dir: '{{.USER_WORKING_DIR}}'
     deps:
       - task: :engine:_ts-build

package/templates/PULL_REQUEST_TEMPLATE.md

@@ -13,6 +13,18 @@
 - `vbrief/pending/YYYY-MM-DD-slug.vbrief.json`
 -->
 
+## Documentation impact
+
+<!-- Closed enum. Rationale is quoted data and is never a gate input.
+     change_class: add | change | withdraw | none
+     surfaces: none OR comma-separated command:<id> | skill-trigger:<id> | help:<id> | docs-site:<page>
+     `no user-doc impact` is refused when a registered command, skill, help key,
+     or public docs-site page is added or removed. Same-PR rule: coding/docs.md (#447). -->
+
+change_class: none
+surfaces: none
+rationale: "Replace this quoted sentence with the actual documentation-impact rationale."
+
 ## Checklist
 
 - [ ] `task check` passes locally (validate + lint + test; see `coding/testing.md`)