@deftai/directive-content 0.69.0 → 0.71.0

package/.agents/skills/deft-directive-feedback/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: deft-directive-feedback
+description: >-
+  Batched session-end gap escalation for directive consumers. Collects
+  friction/gap reports, drafts deduped framework-gap issues against
+  deftai/directive, and files upstream only after explicit operator
+  confirmation.
+---
+
+Read and follow: skills/deft-directive-feedback/SKILL.md

package/Taskfile.yml

@@ -248,6 +248,12 @@ includes:
   triage-smoketest:
     taskfile: ./tasks/triage-smoketest.yml
     optional: true
+  # D17 (#1709): `task triage:metrics` trend readout from summary-history.jsonl.
+  # Inner task `metrics` is exposed as the user-facing alias `task triage:metrics`
+  # in the alias block below.
+  triage-metrics:
+    taskfile: ./tasks/triage-metrics.yml
+    optional: true
   # Windows maintainer onboarding fragment (#902). Exposes the inner task
   # `toolchain` as `task setup:toolchain`. Note: the root-level `setup` task
   # below (git-hooks bootstrap) coexists with `setup:toolchain` because
@@ -295,6 +301,21 @@ includes:
   capacity:
     taskfile: ./tasks/capacity.yml
     optional: true
+  # Tier 0 framework-eval surface (#1703). Exposes `task eval:health` --
+  # aggregates static self-consistency gates into a versioned health score.
+  eval:
+    taskfile: ./tasks/eval.yml
+    optional: true
+  # Gap escalation upstream filing (#1709 child 5). Exposes `task feedback:file` --
+  # confirmation-gated, deduped framework-gap issues for consumer projects.
+  feedback:
+    taskfile: ./tasks/feedback.yml
+    optional: true
+  # Pull-based value-awareness readbacks (#1709). Inner task `show` is exposed as
+  # `task value:show` via the include namespace key.
+  value:
+    taskfile: ./tasks/value.yml
+    optional: true
   # Pack-slicing surface (#1283 design, #1294 pilot, ADR-001 Layer B). Exposes
   # `task packs:slice` (named-slice API), `task packs:render` (regenerate the
   # meta/lessons.md projection), and `task packs:verify-drift` (the drift gate,
@@ -854,6 +875,13 @@ tasks:
         vars:
           CLI_ARGS: "{{.CLI_ARGS}}"
 
+  triage:metrics:
+    desc: "Trend lines from summary-history.jsonl (#1709 / D17). -- task triage:metrics -- [--window=7d|30d] [--format=text|json]"
+    cmds:
+      - task: triage-metrics:metrics
+        vars:
+          CLI_ARGS: "{{.CLI_ARGS}}"
+
   triage:queue:
     desc: "Print the ranked triage queue (#1128 / D11). -- task triage:queue [-- --repo OWNER/NAME] [--limit N]"
     cmds:

package/UPGRADING.md

@@ -137,16 +137,21 @@ These commands are unrelated — do not confuse them:
 
 Current `@deftai/directive` npm releases no longer ship `task migrate:vbrief` or `scripts/migrate_vbrief.py` on the consumer deposit path (#2022 Phase 3). If your project still uses the pre-v0.20 flat document model (authoritative root `SPECIFICATION.md` / `PROJECT.md` without vBRIEF lifecycle folders), migrate **once** on a pinned release that still bundles the Python migrator, then join the normal npm upgrade path.
 
+> **Durability & support horizon (#2297).** This is a **best-effort** path for a document model that predates v0.20. The permanence anchor is the **`v0.59.0` git tag** — GitHub serves a source tarball for any tag on demand (`https://github.com/deftai/directive/archive/refs/tags/v0.59.0.tar.gz`), so recovery does **not** depend on any uploaded release asset staying attached. As long as the tag exists, the migrator is reachable. If you cannot reach the frozen payload at all, use the **[Fresh-start fallback](#fresh-start-fallback-2297)** below.
+
 **Applies when:** `deft doctor` reports `Pre-cutover: migration needed`, or `task migrate:preflight` exits non-zero with a `document-model` FAIL line.
 
-**Pinned release:** `v0.59.0` (last release before the Python-free npm deposit; includes `scripts/migrate_vbrief.py`).
+**Pinned tag:** `v0.59.0` — the last release before the Python-free npm deposit; the tagged tree includes `scripts/migrate_vbrief.py`.
+
+**This is a two-hop chain.** The pre-v0.20 flat model does not migrate straight to the current layout: hop 1 is `task migrate:vbrief` on **v0.59.0** (flat → vBRIEF v0.6); hop 2 is `deft migrate:xbrief` on **current npm** (vBRIEF v0.6 → xBRIEF v0.8). Steps 5–6 below cover hop 2.
 
 **Steps:**
 
 1. Install **Python 3.11+** and **[uv](https://docs.astral.sh/uv/)** on the migration machine.
-2. Deposit framework **v0.59.0** using one of:
-   - **Frozen Go installer** at [GitHub Releases tag v0.59.0](https://github.com/deftai/directive/releases/tag/v0.59.0) (layout migration + full source tarball under `.deft/core/`), or
-   - **Git submodule / clone:** `git checkout v0.59.0` in your framework checkout.
+2. Deposit framework **v0.59.0** using one of (git-tag methods first — they survive even if release assets are removed):
+   - **Source tarball from the tag:** `curl -fsSL https://github.com/deftai/directive/archive/refs/tags/v0.59.0.tar.gz | tar xz` (full source tree including the migrator), or
+   - **Git clone / submodule:** `git checkout v0.59.0` in your framework checkout, or
+   - **Frozen Go installer** at [GitHub Releases tag v0.59.0](https://github.com/deftai/directive/releases/tag/v0.59.0) (legacy bridge; relies on the uploaded asset, so prefer a git-tag method above for durability).
 3. From the project root, preview then apply:
    ```bash
    task migrate:preflight
@@ -160,6 +165,16 @@ Current `@deftai/directive` npm releases no longer ship `task migrate:vbrief` or
 
 ⊗ Run `npm i -g @deftai/directive@latest` / `deft update` on a project that still has authoritative pre-v0.20 root docs — the current deposit cannot run the migrator; follow the frozen path first.
 
+#### Fresh-start fallback (#2297)
+
+The automated migrator is a convenience, not the only route. If the `v0.59.0` payload is genuinely unreachable (tag deleted, no network, Python/uv unavailable, or the migrator errors on an unusual legacy shape), you are **not** stranded — port forward manually:
+
+1. On **current npm**, scaffold a clean project beside the old one: `directive init` (or `npx @deftai/directive init`). This produces the current xBRIEF layout directly, skipping both hops.
+2. Hand-port your content: copy the substance of the old `SPECIFICATION.md` / `PROJECT.md` into the new project definition and scope xBRIEFs the setup flow creates. Your prose is the source of truth; only the container format changed.
+3. Keep the old tree read-only for reference until the new project's `deft doctor` is green, then archive it.
+
+This is lossless for content (you re-author the container, not the substance) and depends on nothing but current npm — so it is the guaranteed floor under the best-effort automated path.
+
 See [docs/BROWNFIELD.md](./docs/BROWNFIELD.md) for what migration produces and how content is preserved.
 
 ### One-time migration from the Go installer (legacy → npm)
@@ -175,6 +190,8 @@ If your current install uses the frozen Go installer (`deft-install`), migrate o
 
 The frozen Go installer remains available at [GitHub Releases](https://github.com/deftai/directive/releases) as a legacy / offline bridge but receives no further updates (#1912); Node ≥ 20 is still required to run Deft afterward. After this one-time step, the four-step npm path above is all you need for every future upgrade.
 
+> **Security (#2305): only run the migration bridge against a repository you trust.** A malicious repo can commit `.deft` / `.deft/core` (or a parent) as a symlink that escapes the tree, causing the deposit to write framework content outside the project directory under your account. The canonical npm CLI now refuses a symlink-escaping deposit boundary, but the **frozen Go installer** (`cmd/deft-install/upgrade.go`) is **not** patched — it is explicitly won't-fix / risk-accepted (no further Go releases, #1912). Run it only on repositories you control or trust.
+
 ---
 
 ## Legacy layout refused by the npm CLI (#1912)
@@ -186,6 +203,8 @@ legacy layout; the frozen final Go installer is the one-and-only migration
 bridge. This is the run-from-npm, use-time gate that backs the one-time
 migration above.
 
+> **Security (#2305): trust the repo before running the frozen migration bridge.** The npm CLI refuses a deposit whose `.deft` / `.deft/core` (or a parent) is a symlink escaping the resolved project tree, so a malicious repo cannot redirect the deposit to an arbitrary location under your account. The one residual exposure the npm gate cannot cover is running the **frozen Go bridge** against an untrusted repo during legacy migration (the Go binary acts before npm ever runs); it is explicitly won't-fix / risk-accepted (#1912). Only run the migration bridge against a repository you trust.
+
 **Legacy layouts the npm CLI refuses:**
 
 - a git-clone or git-submodule deposit of the framework;

package/events/README.md

@@ -14,7 +14,7 @@ data-file-convention check follow-up
 
 - `registry.json` — single source of truth for every event name, category,
   payload contract, detector / emission pointer, and consumer pointers.
-  Lists 5 `detection-bound` events and 4 `behavioral` events (9 total).
+  Lists 5 `detection-bound` events and 9 `behavioral` events (14 total).
 - `registry.schema.json` — schema validating the registry's shape, including
   the required `category` enum (`detection-bound` | `behavioral`).
 - `event-record.schema.json` — schema for individual emitted event records.

package/events/registry.json

@@ -161,6 +161,83 @@
         "scripts/migrate_vbrief.py -- wires the emitter into all three _emit_legacy_artifacts call sites (SPECIFICATION / PROJECT / PRD captures)",
         "(deferred -- no downstream handler in this PR; future migrate:vbrief audit reporting and consumer-facing legacy-handling skills will subscribe by name)"
       ]
+    },
+    {
+      "name": "value:gate-catch",
+      "category": "behavioral",
+      "description": "A detection-bound gate refused an action (branch protection, session ritual, encoding, etc.) while value feedback is enabled. Powers attributed value readbacks (#1709).",
+      "trigger": "packages/core/src/events/attribution-ledger.ts::recordGateCatch when verify:branch (or other wired gate) returns a blocking exit and plan.policy.valueFeedback.emitEvents is allowed.",
+      "payload": {
+        "signal_class": "string enum -- always `value` for this event name",
+        "source": "string -- canonical gate id (e.g. verify:branch)",
+        "detail": "string -- one-line human context for the catch"
+      },
+      "consumers": [
+        "packages/core/src/events/attribution-ledger.ts -- emit helper gated on valueFeedback",
+        "(deferred) skills/deft-directive-sync -- budgeted session readback (#1709 child 4)"
+      ]
+    },
+    {
+      "name": "value:wip-cap-protect",
+      "category": "behavioral",
+      "description": "verify:wip-cap refused a merge/promote because pending+active count exceeds plan.policy.wipCap (#1124).",
+      "trigger": "packages/core/src/wip-cap/evaluate.ts when count >= cap without --allow-over-cap and valueFeedback emitEvents is allowed.",
+      "payload": {
+        "signal_class": "string enum -- always `value`",
+        "source": "string -- verify:wip-cap",
+        "count": "integer -- in-flight scope count",
+        "cap": "integer -- resolved wipCap"
+      },
+      "consumers": [
+        "packages/core/src/events/attribution-ledger.ts::recordWipCapProtect",
+        "(deferred) task deft:value:show trend readout (#1709 child 4)"
+      ]
+    },
+    {
+      "name": "bypass:off-flow",
+      "category": "behavioral",
+      "description": "Consumer went off-flow (skipped checks, wrote code without active vBRIEF, skipped pre-PR, etc.) while value feedback is enabled.",
+      "trigger": "packages/core/src/events/attribution-ledger.ts::recordBypassSignal from wired bypass detectors (initial taxonomy entry; sources land in follow-up stories).",
+      "payload": {
+        "signal_class": "string enum -- always `bypass`",
+        "source": "string -- detector id",
+        "detail": "string -- one-line context"
+      },
+      "consumers": [
+        "packages/core/src/events/attribution-ledger.ts",
+        "(deferred) boundary-awareness readback (#1709 child 4)"
+      ]
+    },
+    {
+      "name": "adoption:unused-capability",
+      "category": "behavioral",
+      "description": "Directive capability was applicable to the current work but unused (decompose, cost, pre-PR, etc.).",
+      "trigger": "packages/core/src/events/attribution-ledger.ts::recordAdoptionSignal and future adoption-registry module (#1709 child 3).",
+      "payload": {
+        "signal_class": "string enum -- always `adoption`",
+        "source": "string -- registry module id",
+        "capability": "string -- capability slug (e.g. decompose, pre-pr)",
+        "detail": "string -- one-line applicability context"
+      },
+      "consumers": [
+        "packages/core/src/events/attribution-ledger.ts",
+        "(deferred) packages/core/src/value/adoption-registry.ts (#1709 child 3)"
+      ]
+    },
+    {
+      "name": "friction:directive-gap",
+      "category": "behavioral",
+      "description": "Directive fell short (improvised workflow, gate false-positive, ambiguous rule) and may warrant upstream feedback.",
+      "trigger": "packages/core/src/events/attribution-ledger.ts::recordFrictionSignal from friction detectors and gap-escalation skill (#1709 child 5).",
+      "payload": {
+        "signal_class": "string enum -- always `friction`",
+        "source": "string -- detector id",
+        "detail": "string -- one-line gap description"
+      },
+      "consumers": [
+        "packages/core/src/events/attribution-ledger.ts",
+        "(deferred) task deft:feedback:file / deft-directive-feedback skill (#1709 child 5)"
+      ]
     }
   ]
 }

package/package.json

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