@deftai/directive-content 0.84.0 → 0.86.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

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

@@ -197,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deftai/directive-content",
-  "version": "0.84.0",
+  "version": "0.86.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": [

package/packs/lessons/lessons-pack-0.1.json

@@ -566,6 +566,24 @@
       "source": "Issue #1102. On 2026-05-12 a refinement session (PR #1098) filed #1099 proposing to add .github/dependabot.yml without checking master -- the file already existed (landed via #1070 / v0.29.1). #1099 closed as a stale duplicate the same day; #1100 re-filed as the additive-delta scope.",
       "body": "**Source:** Issue #1102. On 2026-05-12 a refinement session (PR #1098) filed #1099 proposing to add `.github/dependabot.yml` without checking master -- the file already existed (landed via #1070 / v0.29.1). #1099 closed as a stale duplicate the same day; #1100 was re-filed as the additive-delta scope.\n\n**Key insight:** A one-second `git ls-tree origin/master -- <path>` (or `gh api repos/{owner}/{repo}/contents/{path}` without a clone) existence check before filing an add-a-file issue prevents this whole close-and-refile class. If the path already exists, the issue must be scoped to the DELTA vs the on-master state, not the original 'deposit this file' framing.\n\n**Canonical encoding (strongest-applicable layer):** the `!` MUST rule + `\u2297` anti-pattern live in the canonical issue-filing skill `skills/deft-directive-gh-slice/SKILL.md` (Step 5 + Anti-Patterns), cross-referenced from `skills/deft-directive-refinement/SKILL.md` Phase 1. Deterministic shape-coverage: `packages/core/src/content-contracts/skills/gh_slice_prefiling_master_diff.test.ts`.\n\n**Cross-references:** #1070 (`.github/dependabot.yml` originally landed), #1099 (stale-duplicate filing, closed), #1100 (corrected additive-scope refile), PR #1098 (refinement session that surfaced the pattern)."
     },
+    {
+      "id": "monitor-as-implementer-after-false-done-2026-07",
+      "title": "Swarm monitor must not self-implement after false DONE (2026-07)",
+      "date": "2026-07",
+      "issue_refs": [
+        "#2843",
+        "#1880",
+        "#2824"
+      ],
+      "tags": [
+        "agent-experience",
+        "harness",
+        "agent-safety",
+        "swarm"
+      ],
+      "source": "Issue #2843. Recurrence in cohort-2026-07-26-hooks-appsec-coverage after #2839 PR #2842: a drive-to:merge-ready Cursor leaf exited DONE while Greptile P1 still blocked merge-ready, pulling the cohort monitor into inline fix batches and pr:watch.",
+      "body": "**Source:** Issue #2843. Recurrence in cohort-2026-07-26-hooks-appsec-coverage after #2839 PR #2842.\n\n**Failure mode:** A `drive-to: merge-ready` leaf emits `DONE` before `task pr:merge-ready` passes. The host reports terminal success; the swarm monitor reads Phase 5 \"monitor MAY run review-cycle itself\" and starts inline Greptile fixes — violating Gap D (monitor conversation no longer interactive) and Gap C (lifecycle ownership splits mid-cycle).\n\n**Rule:** Preamble §11 reserves `DONE` for merge-ready on `drive-to: merge-ready` envelopes; mid-cycle exits MUST be `BLOCKED` with PR, HEAD SHA, blocker class, worktree path, and `REDISPATCH_OK`. Swarm Phase 5 + review-cycle skill require Tier 1 monitors to background-dispatch ONE continuation leaf instead of self-implementing.\n\n**Canonical encoding:** `templates/agent-prompt-preamble.md` §11; `skills/deft-directive-swarm/SKILL.md` Phase 5 blocked-leaf continuation + completion-notification decision tree; `skills/deft-directive-review-cycle/SKILL.md` Review Monitoring.\n\n**Cross-references:** #1880 (Gap C/D doctrine), #2824 (REDISPATCH_OK / false-alive), #2843."
+    },
     {
       "id": "win32-ps-safe-multiline-git-gh-bodies-2026-07",
       "title": "Windows PowerShell: safe multi-line git/gh bodies (2026-07)",
@@ -583,6 +601,39 @@
       ],
       "source": "Issue #2646 (absorbs #1417). Dogfood on Cursor + Windows PowerShell 2026-07-19 while filing/updating the issue.",
       "body": "**Source:** Issue #2646 (absorbs #1417). On Windows PowerShell, agents fail when authoring multi-line git/gh payloads via bash heredocs, `<<<` redirection, inline multi-line `--body` flags, or multi-line PS here-strings in the agent command box. Host/agent shell wrappers can also rewrite shell-embedded commit/issue prose before PowerShell executes.\n\n**Failure modes:** (1) Bash heredoc / `<<<` under PowerShell -- parse abort before any gh call. (2) Long inline `gh issue create` / `gh pr create --body` -- argument splitting, angle-bracket parse errors, silent truncation (#1417). (3) Host wrapper injection into shell-embedded git/gh prose (Co-authored-by / Made-with fragments) corrupting PATCH payloads. (4) Partial fixes (escaping, backtick-n, PS here-strings) reintroduce #240 or #798 damage.\n\n**Rule:** never put multi-line markdown inline in a PowerShell agent command. Write a UTF-8 (no BOM) temp file in the OS temp directory via editor/Write/Node (outside the shell), then pass `git commit -F`, `gh --body-file`, or `gh api --input`. Verify posted bodies after PATCH when wrappers may have corrupted earlier attempts.\n\n**Canonical encoding (strongest-applicable layer):** rule body in `content/scm/github.md` \u00a7 Windows PowerShell: safe multi-line git/gh bodies (#2646); agent pointer in `templates/agent-prompt-preamble.md` \u00a7 3.9 and `templates/agents-entry.md` Contextual guardrails lazy-load trigger.\n\n**Cross-references:** #240 (Warp here-string splitting), #798 (PS 5.1 encoding safe write path), #1417 (long gh --body quoting, closed duplicate), #2646."
+    },
+    {
+      "id": "release-check-failure-file-and-merge-2026-07",
+      "title": "Release Phase 1 check failure \u2014 file-and-merge, not inline hotfix (2026-07)",
+      "date": "2026-07",
+      "issue_refs": [
+        "#2859",
+        "#2858"
+      ],
+      "tags": [
+        "agent-experience",
+        "release",
+        "documentation"
+      ],
+      "source": "Issue #2859. During v0.86.0 Phase 1, task check failed on #2858-class hang; orchestrator led with inline hotfix / skip-ci instead of file \u2192 PR \u2192 merge \u2192 resume.",
+      "body": "**Source:** Issue #2859 (recurrence during v0.86.0 cut; concrete hang #2858).\n\n**Failure mode:** Release Phase 1 `task check` / `ci:local` fails on a fixable defect. Agent offers inline hotfix, timeout tweaks, or untracked `--skip-ci` before filing a tracked issue and driving merge-ready.\n\n**Rule:** Pause the cut. File GitHub issue \u2192 xBRIEF \u2192 feature branch \u2192 PR \u2192 merge \u2192 confirm check green \u2192 resume Phase 1. `--allow-skip-ci=#N` stays incident-only with a tracked issue (Phase 4); never the first suggestion for a shippable bug.\n\n**AGENTS.md bulk rejected:** Always-pin expansion in AGENTS.md / agents-entry for this reminder was considered and rejected (#2859).\n\n**Canonical encoding:** `skills/deft-directive-release/SKILL.md` \u00a7 Fixable check failure \u2014 file-and-merge before resume (#2859); `docs/RELEASING.md` \u00a7 Fixable check failure during release."
+    },
+    {
+      "id": "release-coverage-debt-hatch-2026-07",
+      "title": "Release Step 5 coverage hairline \u2014 open-issue ledger hatch (2026-07)",
+      "date": "2026-07",
+      "issue_refs": [
+        "#2866",
+        "#2573",
+        "#2618"
+      ],
+      "tags": [
+        "agent-experience",
+        "release",
+        "documentation"
+      ],
+      "source": "Issue #2866. Hairline branch-coverage misses at release Step 5 repeatedly interrupted cuts; operator approved file-#N-then-hatch when no open debt issue exists.",
+      "body": "**Source:** Issue #2866 (operator-approved 2026-07-27).\n\n**Failure mode:** `task release` Step 5 fails on Vitest branch coverage below 85% (hairline miss). Agent treats it like a #2859 file-and-merge product defect or attempts consecutive `--allow-coverage-debt` soft-passes while a prior hatch debt issue is still open.\n\n**Rule (release-scoped only):** Hatch applies only when branches is the sole metric below 85%. Query open issues via `coverage-debt in:title,body` and `allow-coverage-debt in:body`; file new debt with title prefix `coverage-debt:` and both markers in body. If no open debt \u2192 file `#N`, continue with `--allow-coverage-debt=#N` (PowerShell: `N` or `\"#N\"`). If open debt from prior hatch \u2192 restore all four metrics \u2265 85% before reusing hatch. Multi-metric misses, hangs, and failing tests stay under #2859 file-and-merge.\n\n**Canonical encoding:** `skills/deft-directive-release/SKILL.md` \u00a7 Step 5 branch-coverage threshold \u2014 open-issue ledger hatch (#2866); `docs/RELEASING.md` \u00a7 Coverage debt hatch during release."
     }
   ]
 }