@deftai/directive-content 0.77.0 → 0.78.0

package/Taskfile.yml

@@ -390,6 +390,7 @@ tasks:
       - verify-wip-cap-framework-self-check
       - verify:agents-md-budget
       - verify-eval-health-relocation-framework-check
+      - verify-eval-triggers-relocation-framework-check
       - vbrief:validate
       - codebase:validate-structure
       - verify:codebase-map-fresh
@@ -438,6 +439,15 @@ tasks:
         vars:
           CLI_ARGS: "--base-ref origin/master"
 
+  verify-eval-triggers-relocation-framework-check:
+    internal: true
+    desc: "Framework self-check shim for verify:eval-triggers-relocation (#1586)."
+    dir: '{{.USER_WORKING_DIR}}'
+    cmds:
+      - task: verify:eval-triggers-relocation
+        vars:
+          CLI_ARGS: "--base-ref origin/master"
+
   # s2-deterministic-gate (#1166): deterministic validation gate for strategy
   # output shape. Runs on every `task check` (including CI). Implemented in
   # scripts/validate_strategy_output.py. Respects Grok Build Windows rules

package/commands.md

@@ -173,7 +173,7 @@ Current status: the validation, extractor, provider, registry, generated MAP, an
 - `task check:slow` -- slower/full checks.
 - `task verify:session-ritual` -- validate session-start ritual state.
 - `task verify:branch` -- enforce default-branch protection.
-- `task verify:hooks-installed` -- ensure local hooks are configured.
+- `task verify:hooks-installed` -- ensure local git hooks are configured; use `deft verify:hooks-installed --scope=agent` for agent-host hooks.
 - `task verify:encoding` -- detect mojibake and BOM issues.
 - `task verify:xbrief-conformance` -- validate xBRIEF conformance surfaces.
 - `task verify:cache-fresh` -- validate cache freshness where required.
@@ -181,6 +181,14 @@ Current status: the validation, extractor, provider, registry, generated MAP, an
 
 Use `task --list` for the exact current verify namespace.
 
+### Agent-host direct-write hooks (#2438)
+
+`directive init` and `deft update` idempotently merge Directive-owned entries into `.claude/settings.json`, `.grok/hooks/deft.json`, and `.cursor/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.
+
+- Verify registration: `deft verify:hooks-installed --scope=agent` (or `--scope=all` for git + agent hooks).
+- Repair missing/drifted entries: `deft update`.
+- The P0 hook slice does not classify shell-mediated writes, MCP mutations, compact re-arm, or subagent routing; those remain owned by their dedicated follow-up issues.
+
 ## Session-start ritual (#1149)
 
 Full always-on contract for the interactive session-start ritual and its gated verifier (#1149 / #1348). Read-only posture (#2176) defers this ceremony until mutation intent — see `.deft/core/commands.md` § Session routing.

package/docs/agent-docs.md

@@ -39,6 +39,10 @@ These are the specific blocks the study measured *hurting* agent quality — tre
 - ⊗ Do **not** accumulate 15+ unpaired warnings. Past that threshold the agent over-explores instead of acting.
 - ≉ Avoid stacking dozens of domain-specific gotchas. Domain rules help when specific and enforceable; they stop helping when piled up. Prefer a deterministic gate over prose where one exists (the gate is platform-correct by construction and travels with the repo).
 
+## Skill pins for process-critical workflows (#2508)
+
+When a workflow skill must not be skipped on trigger miss (implementation, pre-PR, review-cycle, swarm), name it in AGENTS.md as an **always-pin** — not by pasting the skill body. Tier definitions, default pin list, and anti-patterns (do not pin entire language packs): [`skill-pin-policy.md`](./skill-pin-policy.md).
+
 ## Relationship to directive's own dogfooding
 
 Directive holds its own AGENTS.md to this bar via the `verify:agents-md-budget` ratchet (#645) and the consumer-side advisory signal (`agentsMdAdvisory`, #2155). The doc-sprawl awareness step in the `deft-directive-sync` skill (#647) surfaces reachable-doc-volume drift before it silently degrades agent quality. This doc is the "how to structure it well" companion to those "keep it from bloating" guards.

package/docs/skill-pin-policy.md

@@ -0,0 +1,77 @@
+# Skill pin policy (#2508)
+
+Legend (RFC2119): `!`=MUST, `~`=SHOULD, `≉`=SHOULD NOT, `⊗`=MUST NOT, `?`=MAY.
+
+## Why pins exist
+
+AGENTS.md always loads; on-demand skills load only when trigger matching succeeds. Empirical and practitioner guidance (antfu/skills FAQ; directive #2484 progressive disclosure) show **false negatives** — the agent never opens a process-critical skill because no trigger matched. Pins mitigate that by naming must-apply skills directly in the always-loaded AGENTS.md surface.
+
+Pins are for **false-negative-sensitive process gates**, not for copying entire framework corpora into context.
+
+## Pin tiers
+
+| Tier | Meaning | How the agent discovers it |
+|---|---|---|
+| **always-pin** | Named in AGENTS.md (managed or consumer unmanaged header) as a required `SKILL.md` load when a matching work type starts | Always-loaded AGENTS.md |
+| **on-demand** | Routed via Skills Index triggers in `REFERENCES.md` — scan Level-0, read Level-1 on match | Skills Index → `SKILL.md` |
+| **reference-only** | External, rare, or maintainer-only corpora; no standing trigger routing | Explicit doc pointer only |
+
+### Criteria for always-pin
+
+A skill belongs in the always-pin tier when **all** of the following hold:
+
+1. **Process gate** — skipping it breaks lifecycle, quality, or safety (implementation intent, pre-PR, review-cycle, swarm dispatch).
+2. **False-negative risk** — trigger keywords alone are insufficient because work starts without an obvious keyword (`drive-to: merge-ready`, silent PR open, cohort dispatch).
+3. **Bounded body** — the skill is a workflow gate, not a language/deployment manual (those stay on-demand behind task/trigger gates per #644).
+
+### Criteria for on-demand
+
+Default for indexed directive skills: triggers in the Skills Index table are sufficient when the user or task surface names the workflow (`build`, `pre-pr`, `swarm`, `triage`, etc.).
+
+### Criteria for reference-only
+
+External packs, archived lessons, maintainer-only release tooling, or docs reached only through explicit `packs:slice` / task-based loading pointers.
+
+## Default always-pin set (directive)
+
+These four process skills are the **default always-pin list** for directive development and for consumer projects using the framework lifecycle:
+
+| Skill | Load when |
+|---|---|
+| `deft-directive-build` | Code mutation / implementation against an active scope xBRIEF (#810) |
+| `deft-directive-pre-pr` | Before opening or pushing a PR |
+| `deft-directive-review-cycle` | Greptile/bot review response until merge-ready (#2308) |
+| `deft-directive-swarm` | Parallel agent dispatch / cohort orchestration |
+
+Consumer installs mirror the same four paths under `.deft/core/.agents/skills/`. Maintainer checkouts use `content/skills/<name>/SKILL.md`.
+
+`deft-directive-setup` stays **on-demand** (explicit `setup` / `bootstrap` triggers). `deft-directive-sync` stays **on-demand** (session-start `sync` trigger and managed AGENTS pointers).
+
+## How to pin (AGENTS.md)
+
+Always-pin skills are referenced by **id + path pointer**, not by pasting skill bodies into AGENTS.md:
+
+```markdown
+! Before code mutation: read `deft-directive-build` (`content/skills/deft-directive-build/SKILL.md`).
+! Before PR: read `deft-directive-pre-pr`; review: `deft-directive-review-cycle`; swarm: `deft-directive-swarm`.
+```
+
+The managed AGENTS.md section `## Skill pin policy (#2508)` carries the framework default list; consumer projects MAY copy the same four ids into their **unmanaged** AGENTS header when they want the mitigation without editing the managed block.
+
+## Anti-patterns
+
+- ⊗ **Pin entire language or deployment packs** (`languages/`, `deployments/`, full `coding/` tree) into AGENTS.md — those corpora are thousands of lines and defeat the #645 budget / #644 reference-chain gating.
+- ⊗ **Paste full SKILL.md bodies** into AGENTS.md instead of id + path pointers.
+- ⊗ **Always-pin convenience skills** (glossary, article-review, gh-slice) that are not lifecycle gates — triggers are enough.
+- ⊗ **Rely on triggers alone** for review-cycle or pre-PR when dispatch envelopes use action verbs without review keywords (the #1862 / #2508 recurrence class) -- includes Cursor product actions such as **babysit-pull-request-in-cloud** that share the babysit name with the global host skill (#2261).
+
+## Catalog convention (optional)
+
+Skills-pack entries (`content/packs/skills/skills-pack-0.1.json`) MAY record `"alwaysPin": true` on metadata-only rows so slice tooling and future gates can list pins without parsing AGENTS.md. The authoritative runtime list for agents remains the AGENTS.md pin section; the catalog field is advisory for tooling (#1535).
+
+## Related
+
+- Skills Index: `REFERENCES.md` § Skills Index
+- Progressive disclosure: #2484
+- Trigger coverage evals: #1586
+- Review-surface precedence: #2308 / `deft-directive-review-cycle`

package/package.json

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