@deftai/directive-content 0.66.2 → 0.67.0

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
@@ -360,6 +361,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
@@ -479,7 +481,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

@@ -56,6 +56,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:

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