@deftai/directive-content 0.66.2 → 0.68.0

package/.githooks/_deft-run.sh

@@ -1,14 +1,47 @@
-# Shared deft CLI resolver for .githooks/* (#2067).
+# Shared deft CLI resolver for .githooks/* (#2067, #2248).
 # REPO_ROOT must be set before sourcing.
+#
+# Resolution order:
+#   1. DEFT_HOOKS_PREFER_GLOBAL=1 forces the global `deft` (escape hatch, #2248).
+#   2. Framework-source (monorepo) checkout: prefer the freshly-built LOCAL CLI
+#      (packages/cli/dist/bin.js) over a possibly-stale global `deft`, so a
+#      newly-added-and-wired verb is not unknown to the global and does not
+#      block commits/pushes (#2248). Detected via the built local CLI existing
+#      under $REPO_ROOT together with a monorepo sentinel (pnpm-workspace.yaml).
+#   3. Consumer install (vendored .deft/core, no local build): resolve the
+#      global `deft` exactly as before -- consumers have no local CLI to prefer.
+#   4. Local build present without the monorepo sentinel: fall back to it.
+#   5. Nothing resolvable: fail with an install hint.
 
 run_deft() {
+    _deft_local="$REPO_ROOT/packages/cli/dist/bin.js"
+
+    # (1) Escape hatch: force the global even in a monorepo.
+    if [ "${DEFT_HOOKS_PREFER_GLOBAL:-}" = "1" ] && command -v deft >/dev/null 2>&1; then
+        deft "$@"
+        return $?
+    fi
+
+    # (2) Framework-source checkout: the local build is authoritative for verbs.
+    if [ -f "$_deft_local" ] && [ -f "$REPO_ROOT/pnpm-workspace.yaml" ]; then
+        node "$_deft_local" "$@"
+        return $?
+    fi
+
+    # (3) Consumer install: resolve the global `deft` exactly as today.
     if command -v deft >/dev/null 2>&1; then
         deft "$@"
-    elif [ -f "$REPO_ROOT/packages/cli/dist/bin.js" ]; then
-        node "$REPO_ROOT/packages/cli/dist/bin.js" "$@"
-    else
-        echo "deft hooks: 'deft' not found on PATH and no local CLI at packages/cli/dist/bin.js." >&2
-        echo "  Install: npm i -g @deftai/directive" >&2
-        exit 1
+        return $?
+    fi
+
+    # (4) Local build present without the monorepo sentinel.
+    if [ -f "$_deft_local" ]; then
+        node "$_deft_local" "$@"
+        return $?
     fi
+
+    # (5) Nothing resolvable.
+    echo "deft hooks: 'deft' not found on PATH and no local CLI at packages/cli/dist/bin.js." >&2
+    echo "  Install: npm i -g @deftai/directive" >&2
+    exit 1
 }

package/.githooks/pre-commit

@@ -17,6 +17,8 @@ run_deft verify:branch --project-root "$REPO_ROOT" || exit $?
 
 run_deft verify:encoding --staged --project-root "$REPO_ROOT" || exit $?
 
+run_deft verify:forward-coverage --staged --project-root "$REPO_ROOT" || exit $?
+
 if [ -d "$REPO_ROOT/xbrief" ] || [ -d "$REPO_ROOT/vbrief" ]; then
     run_deft verify:vbrief-conformance --staged --project-root "$REPO_ROOT" || exit $?
 fi

package/Taskfile.yml

@@ -345,6 +345,7 @@ tasks:
       - verify:stubs
       - verify:links
       - verify:rule-ownership
+      - verify:biome-config
       - verify:content-manifest
       - verify:contract-drift
       - verify:cursor-tier1
@@ -352,6 +353,7 @@ tasks:
       - verify:bridge-drift
       - verify:branch
       - verify:encoding
+      - verify:forward-coverage
       - verify:vbrief-conformance
       - verify:destructive-gh-verbs
       - verify:scm-boundary
@@ -360,6 +362,7 @@ tasks:
       - verify:cache-fresh
       - verify:pack-drift
       - verify-wip-cap-framework-self-check
+      - verify:agents-md-budget
       - vbrief:validate
       - codebase:validate-structure
       - verify:codebase-map-fresh
@@ -458,12 +461,14 @@ tasks:
     cmds:
       - task: install:uninstall
   # User-facing upgrade entrypoint (#1061). Aliases the install:upgrade
-  # wrapper that delegates to the native deft-ts install-upgrade handler. Cited by the doctor's
-  # failure prose and docs/install-manifest.md as the canonical
-  # post-drift repair entrypoint for the AGENTS.md / manifest /
-  # .deft-version triple.
+  # wrapper. As of #2064 the native deft-ts install-upgrade handler is a thin
+  # redirect onto `directive update` -- the single canonical upgrade verb that
+  # file-swaps the vendored .deft/core payload, rewrites the install manifest,
+  # and regenerates .deft-version. Prefer `deft update` directly; this alias is
+  # retained for compatibility. Cited by the doctor's failure prose and
+  # docs/install-manifest.md as the post-drift repair entrypoint.
   upgrade:
-    desc: "Upgrade deft framework -- refresh AGENTS.md + write install manifest + regenerate .deft-version (alias for install:upgrade, #1061)"
+    desc: "Upgrade deft framework -- redirects to `deft update` (the canonical verb: refresh payload + AGENTS.md + install manifest + .deft-version; alias for install:upgrade, #1061/#2064)"
     cmds:
       - task: install:upgrade
 
@@ -479,7 +484,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]. Uses vendored bin.js in source checkouts or global deft on npm consumer deposits (#2022 Phase 3)."
+    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)."
     dir: '{{.USER_WORKING_DIR}}'
     cmds:
       - task: engine:invoke

package/UPGRADING.md

@@ -30,6 +30,8 @@ From v0.55.1 onwards `@deftai/directive` is published on npm. The canonical cons
 
    This re-copies the vendored `.deft/core/` payload and refreshes project-root `.githooks/` (#2049).
 
+   > **`deft update` is the single canonical upgrade verb (#2064).** The older `deft install-upgrade` (and its `task upgrade` maintainer alias) now print a one-line notice and delegate to this exact `deft update` path — they no longer have their own semantics. Previously `install-upgrade` only rewrote the marker/manifest without swapping the payload, so on a stale deposit it reported a false "Project already at X. Nothing to do." Use `deft update`; there is nothing `install-upgrade` does that `deft update` does not.
+
 3. **Stamp npm provenance (one-time, idempotent):**
 
    ```bash
@@ -56,6 +58,26 @@ deft migrate:xbrief
 
 (or `task migrate:xbrief` from a maintainer checkout). The command requires a clean working tree unless you pass `--force`. Legacy `vbrief/` paths and `x-vbrief/` tokens remain **read-accepted** until this migration runs; `deft update` may signpost the same guidance on non-patch upgrades.
 
+Post-migration behavior check (#2149): on xbrief-only projects (`vbrief/` removed), `task issue:ingest -- <N>` now emits `xbrief/proposed/*.xbrief.json` with `xBRIEFInfo.version` from `xbrief/PROJECT-DEFINITION.xbrief.json` (fallback `0.8`), while legacy `vbrief/` projects keep `.vbrief.json` + `vBRIEFInfo.version: "0.6"` until migrated. `task project:render` / `project-render` also stays on `xbrief/PROJECT-DEFINITION.xbrief.json` and no longer recreates `vbrief/` in migrated trees.
+
+### AGENTS.md: managed vs unmanaged header (#2154)
+
+`migrate:xbrief` touches your `AGENTS.md` in two distinct regions:
+
+- **Managed section** (between the `<!-- deft:managed-section ... -->` / `<!-- /deft:managed-section -->` markers): regenerated wholesale by `agents:refresh`, so it always reflects the current framework layout. This region is rendered from the framework template — do not hand-edit it.
+- **Unmanaged header/tail** (everything outside those markers — your project-specific `Session orientation`, `Lifecycle` examples, `Local dev` notes): preserved verbatim across upgrades so your consumer notes survive. Because it is preserved, a rename migration would otherwise leave stale `vbrief/` path literals here. `migrate:xbrief` now applies a **bounded, idempotent** rewrite over the unmanaged region only, replacing the known crossover tokens (`vbrief/` → `xbrief/`, `*.vbrief.json` → `*.xbrief.json`, `vbrief:preflight` → `xbrief:preflight`) while leaving freeform prose untouched. It prints a summary of the replacements.
+
+If you upgraded before this fix landed and your header still points at `vbrief/`, `deft doctor` now emits an `AGENTS.md header drift:` signpost. Re-run `deft migrate:xbrief` (idempotent) to patch the header, or hand-edit the offending path literals.
+
+**Option A (canonical, #2065):** new installs scaffold a **bounded** unmanaged header only — a project one-liner plus a **Session orientation** pointer at the canonical sources below. Do **not** add freeform `Status`, `Next:`, or `Known Issues` blocks; they are retired because the framework preserves the header verbatim while `deft doctor` only checks the managed section (#794, #1308). Session orientation comes from:
+
+- `xbrief/PROJECT-DEFINITION.xbrief.json` (project identity)
+- `xbrief/` lifecycle folders (scoped work)
+- `deft triage:queue` / `deft triage:welcome` (ranked queue)
+- GitHub issues (tracked bugs)
+
+If your header still carries `Status` / `Known Issues` from an older handoff, replace them with the Session orientation pointer (reference implementation: [deftai/cartograph#75](https://github.com/deftai/cartograph/pull/75)). Ephemeral shell quirks MAY stay under a `Local dev` heading only.
+
 ## Public contract layer — `@deftai/directive-types` (#1799)
 
 Downstream TypeScript projects can import the canonical xBRIEF/policy contract instead of hand-mirroring JSON shapes:
@@ -348,6 +370,8 @@ The transition is one-way -- v0.28 has no shim back to the bare-only marker. To
 <!-- 1061: AGENTS.md drift repair via task upgrade BEGIN -->
 ## From drifted AGENTS.md -> current install (`task upgrade` repair path, #1061)
 
+> **Consolidation note (#2064):** `deft install-upgrade` and its `task upgrade` maintainer alias now delegate to the single canonical `deft update` path (see [Canonical upgrade — npm](#canonical-upgrade--npm-v0551)). The legacy `.deft/VERSION` retirement described below (backed up as `.deft/VERSION.premigrate`) is folded into `deft update`, so the drift-repair steps here still apply verbatim — the doctor now names `deft update` as the fix.
+
 - **Applies when:** `task framework:doctor` reports drift on any of the four checks (`quick-start-resolves`, `skill-paths-resolve`, `manifest-agreement`, `install-path-consistency`). Common causes: a canonical-reinstall over a pre-v0.27 AGENTS.md (the #1060 recurrence pattern), a marker-version mismatch where AGENTS.md still carries the v1 / v2 managed-section sentinel after a framework bump, or an install-path-consistency mismatch detected via the new `install_root` manifest field that #1062 added to `<install>/VERSION` (the doctor reads the manifest's `install_root` first, then falls back to the AGENTS.md install-root parse, and FAILs when the resolved directory does not exist on disk).
 - **Safe to auto-run:** Yes. `task upgrade` is the canonical user-facing entrypoint added in #1061; it wraps `run upgrade` and is idempotent on re-run (a second invocation against a current manifest + AGENTS.md is a no-op). The wrapper: (1) re-pulls the framework version marker by writing / refreshing `.deft-version`; (2) re-writes the canonical install manifest at `<install>/VERSION` (`ref` / `sha` / `tag` / `install_root` / `fetched_at` / `fetched_by`); (3) refreshes AGENTS.md to the current marker version (v3 sentinel with sha / refreshed / session attributes) via `cmd_agents_refresh`. Pre-v0.27 AGENTS.md files (no managed-section markers, or v1 markers) are migrated in place: content above and below the bracketed block is preserved verbatim, only the framework-owned managed section is rewritten.
 - **Restart required:** Recommended. The agent's current session may still hold stale AGENTS.md / skill references from the pre-upgrade marker. After `task upgrade` completes, start a new agent session so the refreshed prose loads from a clean context.

package/docs/agent-docs.md

@@ -0,0 +1,44 @@
+# Authoring agent docs (AGENTS.md) for a project
+
+Guidance for structuring the AGENTS.md (and its reference docs) of a project directive creates or maintains. Unlike most style advice, the patterns here are **empirically measured**, not opinion: Augment Code's April 2026 AuggieBench study ran real PRs with and without each pattern and scored the agent's output against the human-reviewed golden PR. Full write-up: [good-agents-md.md](./good-agents-md.md).
+
+Legend (RFC2119): `!`=MUST, `~`=SHOULD, `≉`=SHOULD NOT, `⊗`=MUST NOT, `?`=MAY.
+
+> The headline finding: a good AGENTS.md gave the agent a quality jump equivalent to a model upgrade; a bad one made output **worse than no AGENTS.md at all**. The same file boosted `best_practices` +25% on a routine bug fix and dropped `completeness` -30% on a complex feature in the same module. Structure is the difference.
+
+## The pattern (what the study measured)
+
+| Pattern | Measured effect |
+|---|---|
+| 100–150 line main file + a handful of focused reference files | Top performers; **10–15%** improvement across all metrics in mid-size modules. Gains **reverse** once the main file grows past ~150 lines. |
+| Numbered procedural workflows for multi-step tasks | Missing-wiring PRs **40% → 10%**; correctness **+25%**, completeness **+20%**. |
+| Decision tables for common ambiguities (2–3 reasonable options) | **+25%** best-practices adherence — resolves the choice before the agent writes a line. |
+| 3–10 line snippets from the **real** codebase | Improved reuse and pattern adherence. More than a few, and the agent pattern-matches on the wrong thing. |
+| Paired don't/do rules | Warning-only docs underperform; **15+ unpaired don'ts** measurably cause overexploration. |
+| Module-level files over a root cross-cutting file | Root-level cross-cutting AGENTS.md underperforms module-scoped files. |
+
+## How to structure a project's AGENTS.md
+
+1. ! Keep the always-loaded AGENTS.md to **~100–150 lines**. It is a map (what exists, where to look, the few load-bearing rules), not a manual.
+2. ! Push detail into **focused reference files** the agent loads on demand, each with a clear "load when…" scope. See the reference-chain contract below.
+3. ~ Express multi-step tasks (deploy an integration, add a migration, wire a new endpoint) as **numbered workflows**, not prose. Keep branching cases in reference files.
+4. ~ For each recurring "which of these two approaches?" ambiguity, add a **decision table** that forces the choice up front.
+5. ~ Include a few **short, real** code snippets (3–10 lines) for the patterns you most want reused. Do not paste large or duplicative examples.
+6. ! Write rules as **paired don't/do**, not lone warnings — an unpaired "don't" leaves the agent to guess the "do", and a pile of them triggers overexploration.
+7. ~ Prefer **module-level** agent docs (scoped to the package/app the agent is working in) over one root file that tries to cover everything.
+
+## The reference-chain contract
+
+The discovery-rate principle that governs *what to reference* is named in `REFERENCES.md` ("The reference-chain contract", #644) — read it there rather than duplicating it here. In one line: **if a rule must be followed, it must be reachable in the reference chain; orphan docs (<10% discovery) are effectively invisible, and reachable-but-unreferenced docs are still found and still cost context.**
+
+## The overexploration trap (measured failure modes, not style)
+
+These are the specific blocks the study measured *hurting* agent quality — treat them as defects, not taste:
+
+- ⊗ Do **not** add an "architecture overview" / broad-context section to an always-loaded agent file. On complex tasks it pulls the agent into the reference section to verify its approach against every guideline, producing unnecessary abstractions and incomplete solutions (the measured -30% completeness case).
+- ⊗ 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).
+
+## 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/package.json

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

@@ -548,6 +548,23 @@
       ],
       "source": "Issue #696. Observed 2026-04-27: a returning session emitted the alignment confirmation, ran `Test-Path` on USER.md (-> True), declared all config present, and addressed the user by a name injected via a Warp Drive notebook instead of the name in USER.md. USER.md was never read; its `Personal (always wins)` precedence rule was never applied because that rule lives inside the file the agent skipped.",
       "body": "**Source:** Issue #696. Observed 2026-04-27: a returning session emitted the alignment confirmation, ran `Test-Path` on USER.md (-> True), declared all config present, and addressed the user by a name injected via a Warp Drive notebook instead of the name in USER.md. USER.md was never read; its `Personal (always wins)` precedence rule was never applied because that rule lives inside the file the agent skipped.\n\n**Key insight:** A presence / existence check on USER.md is NOT a content read. An alignment confirmation that can be emitted without reading USER.md leaves a substitution gap: when external context (Warp Drive notebooks, MCP server outputs, prompt-injected preferences) defines the same fields as USER.md, the agent silently adopts the external value. External context sits OUTSIDE deft's precedence hierarchy -- USER.md `Personal (always wins)` must win, but only a real content read can apply that rule.\n\n**Rule:** The alignment confirmation MUST include data drawn from USER.md content -- specifically the addressing-name -- so the read is unfakeable (`Deft Directive active -- AGENTS.md loaded. Addressing you as: {Name}.`). Returning Sessions is promoted from unmarked prose to an enforced `!`/`\u2297` rule with an ordered read list (main.md -> USER.md -> PROJECT-DEFINITION) and an inline external-context precedence rule. A `Test-Path` substitution for a content read is an explicit anti-pattern.\n\n**Canonical encoding (strongest-applicable layer):** the rule body lives in `AGENTS.md` + `templates/agents-entry.md` (`## Returning Sessions` + `### Deft Alignment Confirmation`), propagated to the consumer managed-section via `task agents:refresh` (#1309). Deterministic shape-coverage: `tests/content/test_agents_md.py` (must-marker, Test-Path anti-pattern, name-echo, external-context precedence wording). The behavioral eval that actually catches the substitution failure class (conflicting USER.md vs external-context names) is deferred to its own issue (Fix D); the greet-skill structural cleanup is Fix E.\n\n**Cross-references:** `AGENTS.md` / `templates/agents-entry.md` `## Returning Sessions` + `### Deft Alignment Confirmation` (rule body); `tests/content/test_agents_md.py` (shape coverage); #163 (CLI gate parity, complementary); #258 (Warp Drive inventory, documentation half of the same root cause); #78 (adjacent bootstrap-update offer)."
+    },
+    {
+      "id": "prefiling-master-diff-check-2026-07",
+      "title": "Pre-filing master-diff check before proposing to add a file (2026-07)",
+      "date": "2026-07",
+      "issue_refs": [
+        "#1102",
+        "#1099",
+        "#1100",
+        "#1070"
+      ],
+      "tags": [
+        "scm",
+        "skills"
+      ],
+      "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)."
     }
   ]
 }