@deftai/directive-content 0.76.0 → 0.78.0

package/Taskfile.yml

@@ -152,6 +152,9 @@ includes:
   session:
     taskfile: ./tasks/session.yml
     optional: true
+  plan-sequence:
+    taskfile: ./tasks/plan-sequence.yml
+    optional: true
   # #883 Story 1 stub include. The fragment exposes its inner tasks
   # (`issue:list` / `issue:view` / `issue:close` / `issue:edit`) under the
   # `scm` namespace key, producing the canonical `scm:issue:*` surface in
@@ -387,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
@@ -435,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
@@ -517,7 +530,7 @@ tasks:
   # in ``tasks/framework.yml`` now prints a redaction notice pointing
   # the operator at this surface.
   doctor:
-    desc: "Canonical doctor surface (#1272) -- task doctor [-- --session | --fix | --json | --quiet | --network]. Uses vendored bin.js in source checkouts or global deft on npm consumer deposits (#2022 Phase 3). --network is required to run the payload-staleness check (git remote, then npm registry fallback); it is offline (skipped) by default and discloses the tool + registry class before contacting either (#2182)."
+    desc: "Canonical doctor surface (#1272) -- task doctor [-- --session | --fix | --json | --quiet | --network]. Uses vendored bin.js in source checkouts or global deft on npm consumer deposits (#2022 Phase 3). --network is required to run the payload-staleness check (git verifies the pin; npm compares stable release availability); it is offline (skipped) by default and discloses the tool + registry class before contacting either (#2182)."
     dir: '{{.USER_WORKING_DIR}}'
     cmds:
       - task: engine:invoke

package/UPGRADING.md

@@ -12,6 +12,30 @@ Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
 
 ---
 
+## Helped + health metrics relocation (#2545)
+
+- **Applies when:** any project that upgraded to a release shipping #2545 and still has append logs under `<lifecycle-root>/.eval/results/crud-metrics.jsonl` or `health-history.jsonl` inside the git worktree.
+- **Safe to auto-run:** Yes. New runs write to the resolved user-data metrics root; no manual migration of historical rows is required (lost worktree copies are acceptable).
+- **Restart required:** No for the filesystem change. Start a **new agent session** after upgrade if agents still cite the old `xbrief/.eval/results/` paths.
+- **Commands:**
+  - `deft eval:health` (persists to the resolved metrics home on success)
+  - Inspect platform default: `%APPDATA%\deft\metrics\` (Windows) or `~/.config/deft/metrics/` (Unix)
+  - Headless / CI: set `DEFT_METRICS_HOME` (or `DEFT_EVAL_HOME`) to a job artifact directory
+
+### What changed
+
+- **Helped + health ledgers moved out of the project tree.** `crud-metrics.jsonl` (value / "how we helped") and `health-history.jsonl` (`eval:health` history) now resolve under a shared metrics home with `helped/` and `health/` subdirectories.
+- **Resolve ladder:** `DEFT_METRICS_HOME` / `DEFT_EVAL_HOME` override → optional workspace-local `<project>/.deft/metrics/` when `DEFT_METRICS_PROJECT_LOCAL=1` → platform user-data (`%APPDATA%\deft\metrics` / `~/.config/deft/metrics`). No fallback to `xbrief/.eval/results/`.
+- **Soft-disable:** when no writable metrics home exists, persistence is skipped (metrics-disabled) instead of dirtying the worktree.
+- **Golden-run eval artifacts** (`golden-runs.jsonl`, committed `eval-health-baseline.json`) remain under `<lifecycle-root>/.eval/results/`.
+
+### References
+
+- [#2545](https://github.com/deftai/directive/issues/2545) — metrics relocation.
+- [`packages/core/src/metrics/resolve-metrics-home.ts`](../packages/core/src/metrics/resolve-metrics-home.ts) — shared resolver.
+
+---
+
 ## Which command do I run? (three-command model)
 
 Directive is driven by three commands, and upgrading is one of them. Route by situation to exactly one:
@@ -99,12 +123,12 @@ Consumer AGENTS.md stays pointer-thin — scan `.deft/core/REFERENCES.md` Skills
 - **Harness skill frontmatter** bytes (Cursor `<agent_skill>` shape; advisory unless `skillFrontmatterMaxBytes` is set)
 - **Bootstrap hooks** bytes (0 until #2438 ships)
 
-The north-star target is **≤8192 B / ~2k tok combined**. On Cursor with all skills injected, managed AGENTS.md (~16.8 KB) plus skill frontmatter (~7.7 KB) still exceeds that target — remediation paths:
+The north-star target is **≤8192 B / ~2k tok for the managed section** (Phase-2) and **≤9216 B / ~2.3k tok combined** (managed + DD-3 + hooks; Phase-3 closeout #2531). On Cursor with all skills injected, managed AGENTS.md plus skill frontmatter can still exceed the combined bar — remediation paths:
 
 1. **Tier skills** — install only the daily-core six (`setup`, `sync`, `build`, `pre-pr`, `review-cycle`, `triage`) via OpenPackage; set `plan.policy.agentsMdBudget.skillFrontmatterTier` to `daily-core` or export `DEFT_AGENTS_MD_BUDGET_SKILL_TIER=daily-core`.
 2. **Thin managed AGENTS.md** — continue epic #2369 relocation; push bulk to `commands.md`, `scm/github.md`, and skills.
 3. **Shorten SKILL.md descriptions** — advanced-tier skills (`release`, `swarm`, `debug`, `article-review`, …) are the largest frontmatter offenders.
-4. **Optional ratchet** — seed `plan.policy.agentsMdBudget.skillFrontmatterMaxBytes` at the measured tier size when you want fail-closed DD-3 growth control.
+4. **Optional ratchet** — seed `plan.policy.agentsMdBudget.skillFrontmatterMaxBytes` at the measured tier size when you want fail-closed DD-3 growth control. The directive framework tree itself seeds this at daily-core **2080 B** (with `skillFrontmatterTier: daily-core`) as Phase-3 insurance (#2532 / #2531); consumers remain advisory until they opt in.
 
 Non-native-skill harnesses (Codex CLI, OpenCode) report 0 B frontmatter; set `harnessProfile: none` in policy when appropriate.
 

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.
@@ -188,6 +196,7 @@ Full always-on contract for the interactive session-start ritual and its gated v
 ### Session routing (#2176)
 
 - ! Default interactive sessions to **read-only posture** until mutation or implementation intent (questions, research, Plan Mode, ticket-shaping). Load AGENTS.md / main.md / USER.md / PROJECT-DEFINITION; confirm alignment with addressing-name; ⊗ do not write `.deft/ritual-state.json`, run install/build side effects, or emit triage welcome, branch-policy, default-branch sync, sync-skill lifecycle checks, or eval/value readback writes unless the operator asks or the task is implementation-ready.
+- ! **USER.md path (#2544):** resolve via `deft session:start` output (`USER.md resolved …`); default platform paths: Windows `%APPDATA%\deft\USER.md`, Unix `~/.config/deft/USER.md`; override `$DEFT_USER_PATH`; workspace `<project>/.deft/USER.md`. ⊗ Invent or search `~/.config/deft` on Windows — AppData Roaming is canonical.
 - ! At mutation boundaries (code-writing, scope lifecycle moves, `start_agent`, commits, pushes, PR-from-local-changes, release work): run the mutable quick tier then gated verifier below before proceeding.
 - ? Explicit read-only alignment only: `deft session:start -- --read-only` (no ritual-state write).
 - ~ Operators MAY still explicitly request full `deft session:start`, `deft triage:welcome`, sync, or doctor in read-only sessions.
@@ -222,6 +231,7 @@ User-facing surface for the Phase 0 triage workflow and the unified content cach
 
 - `task triage:bootstrap -- [--repo OWNER/NAME] [--limit N] [--state {open|closed|all}] [--batch-size N] [--delay-ms N]` -- seed the local triage cache and audit layer.
 - `task triage:queue --limit=10` -- show ranked candidate work from cache-backed state.
+- **Ordered-plan precedence (#2402):** when `.deft/plan-sequence.json` is active, bare "what's next?" / "next PR" / "proceed" bind to the current sequence entry via `task plan-sequence:current` — they do **not** authorize `triage:queue` or adjacent backlog picks. Use `task verify:plan-sequence -- --target-kind <kind> --target <id>` before opening a PR/branch/story/sub-agent. Sequence exhaustion fails closed until the operator names a new target or explicitly asks for queue/backlog selection ("what's the queue?", "build a cohort"). Set a sequence with `task plan-sequence:set -- --file <json>`; advance with `task plan-sequence:advance`; clear with `task plan-sequence:clear`. Do not reuse triage queue `continuationNumbers` / `continuationOrder` for this state.
 - `task triage:accept -- <issue>` -- accept a candidate and ingest it as a proposed scope xBRIEF.
 - `task triage:reject -- <issue> [--reason "why"]` -- reject a candidate, audit the decision, and update upstream issue state.
 - `task triage:defer -- <issue>` -- defer a candidate without terminal rejection.

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.76.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": [