@deftai/directive-content 0.83.0 → 0.85.0

package/Taskfile.yml

@@ -69,6 +69,9 @@ env:
   UV_PROJECT: '{{.TASKFILE_DIR}}'
 
 includes:
+  docs:
+    taskfile: ./tasks/docs.yml
+    optional: true
   ts:
     taskfile: ./tasks/ts.yml
     optional: true
@@ -93,6 +96,9 @@ includes:
   review-monitor:
     taskfile: ./tasks/review-monitor.yml
     optional: true
+  agent:
+    taskfile: ./tasks/agent.yml
+    optional: true
   architecture:
     taskfile: ./tasks/architecture.yml
     optional: true
@@ -380,6 +386,13 @@ tasks:
     cmds:
       - task: ts:test
 
+  check:merge:
+    desc: "Merge chokepoint gate — explicit alias for check:framework-source (#1704). CI and PR gates SHOULD invoke this (or task check) as the single SoT so discrete workflow steps cannot drift."
+    deps:
+      - task: engine:_ts-build
+    cmds:
+      - task: check:framework-source
+
   check:framework-source:
     desc: "Run all framework source-repo pre-commit checks (TS-only after #1860). Sole wired consumer of maintainer-only core:build / core:clean."
     deps:

package/UPGRADING.md

@@ -80,6 +80,49 @@ From v0.55.1 onwards `@deftai/directive` is published on npm. The canonical cons
 
    Ensure pnpm's global bin directory is on your `PATH` (`pnpm setup` configures `PNPM_HOME`). A project-local `pnpm add -D @deftai/directive@latest` (run via `pnpm exec directive …`) is equivalent for pnpm-managed repos that avoid global installs. `deft update` / `deft migrate` / `deft doctor` all work identically regardless of which package manager installed the engine.
 
+### Corporate or mirrored npm registry
+
+Corporate npm proxies can lag the public registry. The visible failure may be an
+`E404` / `ETARGET`, or it may fail silently: `@latest` resolves successfully
+but installs an older Directive release.
+
+Check npm's effective routing without contacting a registry:
+
+```bash
+npm config get @deftai:registry
+npm config get registry
+```
+
+The scoped value wins when `@deftai:registry` is set; otherwise npm uses the
+default `registry`. If either effective value is not
+`https://registry.npmjs.org/`, choose a recovery path allowed by your
+organization policy:
+
+- **One command:** request the required release directly from public npm:
+
+  ```bash
+  npm i -g @deftai/directive@<version> --registry=https://registry.npmjs.org/
+  ```
+
+- **Durable scoped routing:** add this line to the user or project `.npmrc` so
+  only the `@deftai` scope bypasses the default mirror:
+
+  ```ini
+  @deftai:registry=https://registry.npmjs.org/
+  ```
+
+If direct public-registry access is prohibited, do not bypass the policy. Ask
+IT or the registry administrator to synchronize all Directive packages:
+`@deftai/directive`, `@deftai/directive-core`,
+`@deftai/directive-content`, and `@deftai/directive-types`.
+
+`directive doctor` checks this routing with offline `npm config get` reads. A
+non-public effective registry produces an advisory warning but does not make
+doctor fail; configured registry URLs are not printed because they can contain
+internal hostnames or credentials. With `--network`, the release-availability
+probe always queries the canonical public registry explicitly, independent of
+the configured mirror.
+
 2. **Refresh the project deposit** from your project root:
 
    ```bash

package/commands.md

@@ -170,10 +170,22 @@ Current status: the validation, extractor, provider, registry, generated MAP, an
 
 ## Quality And Verification Commands
 
-- `task check` -- primary directive repo pre-commit gate.
+- `task check` -- primary directive repo pre-commit gate (merge chokepoint — #1704).
+- `task check:merge` -- explicit merge-chokepoint alias for `check:framework-source` in the framework source repo (#1704).
 - `task check:framework-source` -- framework-source lane.
 - `task check:consumer` -- consumer-shape lane.
 - `task check:slow` -- slower/full checks.
+
+### Gate throughput — iteration fast lane (#1704)
+
+> **Invariant:** every change MUST pass the full gate at least once before merge.
+
+- ! **Iteration lane (agents + humans):** during implementation, use affected/static gates — targeted tests on changed paths, relevant static `verify:*` gates, `task coverage:hotspots` / `task verify:forward-coverage` — not full `task check` on every commit.
+- ! **Merge chokepoint:** full `task check` (or `task check:merge` in framework source) before push/PR and in CI via the monolith merge-gate job (`.github/workflows/ci.yml` runs `check:merge`, not cached `deft check`, until `#1713` can invoke internal Taskfile shims).
+- ! **Escape-rate safety:** consume `#1703` Tier-1 telemetry (`helped/crud-metrics.jsonl`) and `task eval:health` (Tier 0) before tightening fast-lane defaults — do not invent a separate metric surface.
+- ~ **In-engine incrementality (#1713):** content-hash cache + runner-delegated affected selection are delivered separately.
+- ~ **Merge queue:** deferred — GitHub merge queue adoption waits until the CI monolith + escape-rate signal are stable; batch merge throughput is the next lever after `#1713` cache lands (#1704 ROI order).
+- ⊗ Skip the merge chokepoint because the iteration lane passed.
 - `task verify:session-ritual` -- validate session-start ritual state.
 - `task verify:branch` -- enforce default-branch protection.
 - `task verify:hooks-installed` -- ensure local git hooks are configured; use `deft verify:hooks-installed --scope=agent` for agent-host hooks.
@@ -185,17 +197,25 @@ Current status: the validation, extractor, provider, registry, generated MAP, an
 
 Use `task --list` for the exact current verify namespace.
 
+### Review-monitor ownership on Cursor (#2797 / #2814)
+
+Use `task pr:watch -- <N>` as the blocking terminal-verdict wait for a `drive-to: merge-ready` Cursor `Task` leaf. A Cursor leaf cannot reliably spawn a nested `Task` review-monitor; do not replace the blocking wait with a background shell process or claim that it is monitoring.
+
+When the workflow needs an Approach 1 monitor, scope the Cursor leaf `stop-at: pr-open`. The orchestrator that owns the Task primitive must spawn the sibling review-monitor and claim the PR-anchored lease with `task review-monitor:register -- --pr <N> --monitor-agent-id <id> --platform-primitive cursor-task`; `task verify:review-monitor -- --pr <N>` remains the fail-closed proof of active GitHub ownership (sticky `<!-- deft:review-owner -->` comment — not local JSON). Release with `task review-monitor:release -- --pr <N>` when done. See `skills/deft-directive-review-cycle/SKILL.md` Review Monitoring and `skills/deft-directive-swarm/SKILL.md` Phase 3.
+
+**Worker liveness (#2824):** For in-flight `drive-to: merge*` Cursor leaves, monitors run `task verify:subagent-alive -- --require-agent <agent-id> [--scratch-dir <worktree>/.deft-scratch/subagent-status]` each poll iteration. Exit `1` prints `REDISPATCH_OK` — authorize takeover when the host still reports running but heartbeats are missing/STALE. Raw heartbeat sweep: `task agent:monitor`. See `docs/subagent-heartbeat.md` § Cursor false-alive.
+
 ### Agent-host direct-write hooks (#2438, #2596)
 
-`directive init` and `deft update` idempotently merge Directive-owned entries into `.claude/settings.json`, `.grok/hooks/deft.json`, `.cursor/hooks.json`, and `.codex/hooks.json` while preserving unrelated settings. `SessionStart` refreshes resume bookkeeping on a non-blocking path. `PreToolUse` covers direct edit/write tools and denies them until both existing gates pass: a fresh gated session ritual and an active/running xBRIEF accepted by canonical preflight. Cursor `preToolUse` deposits set `failClosed: true`, so allow decisions emit `{"permission":"allow"}` — empty stdout is treated as hook failure and would block Write tools. A second `PreToolUse` matcher covers spawn/Task tools (`Task`, `SubagentStart`, `spawn_subagent`, `start_agent`, `CreateAgent`) with the same pre-`start_agent` gate stack; explore spawns (`subagent_type: explore`) pass without implementation gates.
+`directive init` and `deft update` idempotently merge Directive-owned entries into `.claude/settings.json`, `.grok/hooks/deft.json`, `.cursor/hooks.json`, and `.codex/hooks.json` while preserving unrelated settings. `SessionStart` refreshes resume bookkeeping on a non-blocking path. `PreToolUse` uses the lightweight `deft-hook` entrypoint rather than booting the full CLI router, reducing cold hook latency while retaining the same fail-closed ritual, scope, and runtime-authority decisions. Cursor `ApplyPatch` shares the direct-write registration, so each matched edit invokes one hook process. Cursor `preToolUse` deposits set `failClosed: true`, so allow decisions emit `{"permission":"allow"}` — empty stdout is treated as hook failure and would block Write tools. A second `PreToolUse` matcher covers spawn/Task tools (`Task`, `SubagentStart`, `spawn_subagent`, `start_agent`, `CreateAgent`) with the same pre-`start_agent` gate stack; explore spawns (`subagent_type: explore`) pass without implementation gates.
 
 - **Read-only explore (#1185):** Prefer Grok role deposit `default_capability_mode = "read-only"` (see [issue #1185](https://github.com/deftai/directive/issues/1185)). Hooks also deny direct writes when `DEFT_HOOK_READ_ONLY=1` or the host payload signals read-only capability. Implementation spawns remain blocked in read-only posture unless explicitly marked explore.
 
 - Verify registration: `deft verify:hooks-installed --scope=agent` (or `--scope=all` for git + agent hooks).
 - Repair missing/drifted entries: `deft update`.
-- **Opt-out (#2752):** Set `plan.policy.hostHooks.<host>` to `false` in `xbrief/PROJECT-DEFINITION.xbrief.json` for any of the four deposited hosts (`claude`, `cursor`, `grok`, `codex`). Unset or `true` keeps the current fail-closed deposit. When a host is opted out, `deft update` / `directive init` skip creating or re-merging Directive-managed hook entries for that host; if a prior deposit left managed entries in the file, the next update strips only those entries and preserves unrelated settings. Inspect with `deft policy:show --field=hostHooks`. Doctor and `verify:hooks-installed --scope=agent` treat opted-out hosts as healthy — they do not recommend `deft update` to repair them.
+- **Refresh and opt-out (#2790, #2752):** Upgrade `@deftai/directive`, then run `deft update` to refresh all four deposits to the fast path; do not hand-edit host hook files. Set `plan.policy.hostHooks.<host>` to `false` only when you deliberately need to disable a host's Tier-1 enforcement — it is not the performance fix. When a host is opted out, `deft update` / `directive init` skip creating or re-merging Directive-managed hook entries for that host; if a prior deposit left managed entries in the file, the next update strips only those entries and preserves unrelated settings. Inspect with `deft policy:show --field=hostHooks`. Doctor and `verify:hooks-installed --scope=agent` treat opted-out hosts as healthy — they do not recommend `deft update` to repair them.
 - **Claude matcher scope:** Once `.claude/settings.json` hooks are loaded, Claude's `PreToolUse` matcher keys on tool names (`Edit`, `Write`, …), not target paths — matched tools can be gated for the whole session, including writes outside the project tree. Opt out of Claude hook deposit when that posture is unwanted.
-- **Compact re-arm (#2113):** Cursor `preCompact` and Claude/Grok `PreCompact`/`PostCompact` call `deft hook:dispatch --event session.compact` to mark the gated session ritual stale after context compaction/resume; the existing PreToolUse gate then denies direct writes until `deft session:start` and `deft verify:session-ritual -- --tier=gated`. Codex has no native compact hook — operators must re-run the mutation ritual manually after compaction.
+- **Compact re-arm (#2113):** Cursor `preCompact` and Claude/Grok `PreCompact`/`PostCompact` call `deft-hook --event session.compact` to mark the gated session ritual stale after context compaction/resume; the existing PreToolUse gate then denies direct writes until `deft session:start` and `deft verify:session-ritual -- --tier=gated`. Codex has no native compact hook — operators must re-run the mutation ritual manually after compaction.
 - Codex project hooks are trust-gated by Codex. Directive verifies only that the registrations are structurally current; after an install or changed hook hash, open `/hooks` in Codex and review/approve the project hook commands. Runtime trust cannot be inferred from the file alone.
 - Directive writes only `.codex/hooks.json`; it does not parse or modify `.codex/config.toml`. Codex can also load inline hooks from `config.toml`, so avoid defining duplicate Directive commands there or they may run more than once. See the [Codex hooks documentation](https://learn.chatgpt.com/docs/hooks).
 - The P0 hook slice does not classify shell-mediated writes, MCP mutations, richer unified-exec calls, or WebSearch by default. **Runtime authority (#1394)** adds opt-in path allow/deny lists and graduated `scopes` (`edits`, `push`, `merge`) under `plan.policy.runtimeAuthority` — inspect with `deft policy:show --field=runtimeAuthority`. When `enabled: true`, PreToolUse denies classifiable direct-write targets outside `allowPaths` or matching `denyPaths` after ritual/scope/read-only gates; `scopes.edits` gates all direct writes. `push` / `merge` scopes are schema-only until Shell/MCP matchers land (host gap — TODO).

package/docs/product-signal.md

@@ -4,9 +4,12 @@ Phase 1 consented product-improvement signal under epic #2603 (#2693). Defaults
 
 ## Enable (project)
 
+Trusted-org repos (`deftai/*`, plus `DEFT_VALUE_AUTOENABLE_ORGS`) receive a **one-time** install/upgrade force-on (#2822): local value feedback and product-signal enable flip ON on the next `directive update`, with a durable `.deft-cache/org-force-on-v2822.json` marker so later intentional opt-out is not fought forever. Outbound product signal still requires personal consent (D17).
+
 ```bash
 task product-signal:enable -- --confirm
 task policy:show -- --field=productSignal
+task policy:clear-value-feedback   # remove typed valueFeedback key → org-auto resolution
 ```
 
 Capability-cost disclosure prints before `--confirm` applies `plan.policy.productSignal.enabled=true`.

package/docs/task-cache.md

@@ -0,0 +1,37 @@
+# In-engine content-hash task cache (#1713)
+
+Legend (from RFC2119): !=MUST, ~=SHOULD, ⊗=MUST NOT.
+
+**See also**: [Issue #1713](https://github.com/deftai/directive/issues/1713) | [Issue #1704](https://github.com/deftai/directive/issues/1704) (process face) | [Issue #2784](https://github.com/deftai/directive/issues/2784) (public types follow-up)
+
+## Overview
+
+`deft check` can skip unchanged cacheable gates by replaying prior exit-0 results from a local content-hash cache. The cache ships inside the CLI — zero extra install for consumers — and directive dogfoods the same layer for its own gate stack.
+
+Cache entries live under `.deft/cache/task/` (gitignored, local-only).
+
+## Correctness guards
+
+- ! Cache only passes (exit `0`). Failures always re-run.
+- ! `codeVersion` (installed directive version) is part of every cache key.
+- ! Volatile gates opt out via `cacheable: false` on the internal registry.
+- ! Fail open to running when inputs cannot be enumerated — never fail open to passing.
+- Escape hatches: `deft check --no-cache`, `deft cache:clear`.
+
+## Runner affected-test delegation
+
+Affected-test **selection** stays with the consumer test runner. Directive detects the runner and documents the fast-lane convention; the merge gate still runs the full suite (#1704).
+
+| Runner | Detection | Fast-lane convention |
+| --- | --- | --- |
+| vitest | `package.json` lists `vitest`, or `plan.policy.testRunner = vitest` | `vitest --changed` |
+| jest | `package.json` lists `jest` / `@jest/core`, or policy override | `jest --onlyChanged` |
+| go | `go.mod` present, or policy override | `go test` (native package cache) |
+| pytest | `pytest.ini` / `pyproject.toml` / `requirements.txt`, or policy override | `pytest --testmon` |
+| none | No match after config + heuristics | Full suite at merge gate |
+
+Override: set `plan.policy.testRunner` in `PROJECT-DEFINITION.xbrief.json` to `vitest`, `jest`, `go`, `pytest`, or `none`.
+
+## Internal registry (v1)
+
+Gate contracts (`inputs`, `outputs`, `cacheable`, `codeVersion`) are **internal** to `@deftai/directive-core` until #2784 promotes a public `@deft/types` shape. Under-declaration lint runs over known read sets; incomplete enumeration disables caching for that task.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deftai/directive-content",
-  "version": "0.83.0",
+  "version": "0.85.0",
   "description": "Shippable Directive framework content in the consumer .deft/core/ layout (C1 flatten), plus the engine surfaces (.githooks/, Taskfile.yml, tasks/) the deposit wires. Python-free per #2022 Phase 3. Refs #11, #1669, #1967.",
   "type": "module",
   "files": [