@deftai/directive-content 0.66.1 → 0.67.0

package/scm/github.md

@@ -149,6 +149,29 @@ PowerShell 5.x (Windows default) uses UTF-16LE internally and may inject a BOM o
 
 - ! Never paste multi-line PowerShell string literals (here-strings `@" ... "@`) directly into the Warp agent input box -- Warp splits multi-line input across separate command blocks, causing syntax errors or silent truncation. Always write multi-line PS content to a temp file first (e.g. `[System.IO.File]::WriteAllText($tmpFile, $content, [System.Text.UTF8Encoding]::new($false))`), then use the temp file path in subsequent commands
 
+## PowerShell platform-conditional rules for agents (#798 / #1353)
+
+These runtime-specific rules are lazy-loaded here rather than shipped in the always-loaded AGENTS.md, so they don't crowd context for sessions that can't trigger them (#2157 / #1882). Load this section **before** the risky operation when your session matches one of the triggers below.
+
+### PS 5.1 non-ASCII file edits (#798) -- gate-enforced by `verify:encoding`
+
+The corruption happens on the **read** side: `Get-Content -Raw` decodes via the active Windows codepage (cp1252 / cp437) BEFORE any safe write can preserve the bytes, so a correct UTF-8 write of already-corrupted text just persists the mojibake. PowerShell 7+ (`pwsh`), bash, and zsh handle UTF-8 correctly and are exempt.
+
+- ! On PS 5.1, use Python `pathlib` (`Path.read_text(encoding="utf-8")` / `write_text(text, encoding="utf-8")`) for ALL file edits touching non-ASCII glyphs (em dashes, arrows, ⊗, ✓, …, smart quotes) -- never `Get-Content -Raw` / `Set-Content` / inline `-replace` / backtick-n interpolation.
+- ! When writing files from PS 7+ where unavoidable, use `New-Object System.Text.UTF8Encoding $false` -- never `[System.Text.Encoding]::UTF8` (writes a BOM).
+- ⊗ Round-trip a file containing non-ASCII content through PS 5.1 commands (`Get-Content` → `-replace` → `Set-Content`, string-concat → `WriteAllText`, here-strings interpolating non-ASCII) -- the read-side decode corrupts the bytes regardless of the write encoding.
+
+The deterministic `verify:encoding` gate (wired into `task check` and the pre-commit hook) enforces this at commit time by scanning for U+FFFD, the CP1252 / CP437-as-UTF-8 mojibake bigram set, and unexpected BOMs. Because the gate travels with the repo and fires only on the corrupting op, it is the authoritative form of the rule (#798).
+
+### Grok Build Windows + pwsh 7+ shell capture (#1353) -- runtime-detect
+
+When running under the Grok Build runtime on Windows + pwsh 7+, `run_terminal_command` leaks internal wrapper text (Get-Content and redirection fragments) whenever the command string contains `|`, `2>&1`, `| cat`, `>`, or similar metacharacters. Non-piped commands execute cleanly.
+
+- ! Never emit commands containing pipes or redirections through the agent shell tool on this runtime. For anything needing a pipe, use one of: Python one-liners with `pathlib` / `subprocess.run(capture_output=True)` (preferred -- bypasses the wrapper at the OS level), run the operation in the user's native terminal and paste the result back, or isolate the work in a dedicated worktree and mark the step "user shell required".
+- ! Applies to the Grok Build runtime (pwsh 7+) only; Warp + Claude (PTY-based) is not affected by this wrapper leakage.
+
+Refs #798, #1353 (root-cause audit), #2157.
+
 ## Windows / ASCII Conventions for Machine-Editable Sections
 
 Agent `edit_files` operations can fail when structured file sections contain Unicode characters that do not round-trip cleanly through Windows toolchains (xref warpdotdev/warp#9022). The following rules apply to **machine-editable structured sections**: ROADMAP.md phase bodies, CHANGELOG.md entries, and Open Issues Index rows.

package/skills/deft-directive-pre-pr/SKILL.md

@@ -102,6 +102,7 @@ git --no-pager diff master
 - ! Confirm no unintended whitespace-only changes or formatting drift
 - ! **Run `task pr:check-closing-keywords -- --pr <N>` (or pass `--body-file` / `--commits-file` for offline checking) before opening the PR; refuse to push if findings (#737)**. The lint scans both the PR body AND every commit message for closing-keyword tokens (`close|closes|closed|fix|fixes|fixed|resolve|resolves|resolved`) followed by `#\d+` in negation / quotation / example / code-block contexts. The recurrence record is the Layer 1 / Layer 2 / Layer 3 stack: #167 (post-merge close-verify), #697 / #698 (negation-context substring match), #401 / #700 (persistent `closingIssuesReferences` link), #735 (squash body containing `DOES NOT CLOSE #734` auto-closed #734). When the lint surfaces a known-safe occurrence (e.g. test fixtures that legitimately exercise the trigger token), pass `--allow-known-false-positives <issue-numbers>` to suppress -- DO NOT silently delete the lint invocation
 - ~ Verify the diff tells a coherent story -- a reviewer reading it top-to-bottom should understand the change
+- ~ If the PR adds or moves any documentation, verify each new doc is reachable from the AGENTS.md reference chain -- an orphan doc is discovered <10% of the time yet still costs context when found (the reference-chain contract, #644 / #647). Add a pointer or fold it in rather than leaving it stranded.
 
 ### Phase 5 -- Loop
 

package/skills/deft-directive-sync/SKILL.md

@@ -34,6 +34,15 @@ Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
 - Beginning of a new session where framework updates may be available
 - After a known upstream deft release
 
+
+
+## Session orientation — unmanaged header (#2065)
+
+! The region of AGENTS.md **above** the `<!-- deft:managed-section ... -->` marker is project-owned, preserved verbatim on refresh, and **not** freshness-checked by `deft doctor`.
+
+- ! Do NOT treat that unmanaged header as the work queue — consult `deft triage:queue`, `xbrief/` lifecycle, GitHub issues, and `PROJECT-DEFINITION.xbrief.json` instead (#1149, #2065 Option A).
+- ⊗ Do NOT add or revive `Status`, `Next:`, or `Known Issues` blocks in AGENTS.md — they duplicate authoritative sources and rot silently while the managed section stays current.
+
 ## Framework Events Emitted Here
 
 ! When this skill responds to a context-window shift or an explicit "are you using Deft?" probe (per AGENTS.md Deft Alignment Confirmation), emit the paired `session:interrupted` -> `session:resumed` framework events via `scripts/_events.py` so observability of agent-runtime state transitions is structural, not prose-only:
@@ -210,6 +219,7 @@ After structure validation, sync framework-level assets.
 1. ~ Diff the structure (section headings, key rules) rather than expecting byte-identical content
 2. ~ Report any new sections or rules added upstream that are missing locally
 3. ~ Do NOT auto-overwrite -- present differences and let the user decide
+4. ~ If the unmanaged header still carries `Status`, `Next:`, or `Known Issues`, recommend replacing them with the **Session orientation** pointer at `xbrief/` + triage + issues (#2065 Option A) -- do NOT treat that header prose as the work queue
 
 ### 6b: Check codebase MAP freshness
 
@@ -256,6 +266,18 @@ After structure validation, sync framework-level assets.
 - ⊗ Drop a legacy section without explicit user confirmation (even if the section looks obviously stale).
 - ⊗ Silently delete sidecar files under `xbrief/legacy/` -- they are referenced from `LegacyArtifacts` and are part of the audit trail.
 
+## Phase 6e -- Doc-sprawl awareness (advisory, #647)
+
+Doc sprawl is a project-health concern, not just a human-experience one: a lean, well-written AGENTS.md sitting on top of a large reachable doc corpus does **not** stop agents from discovering and loading those docs (Augment Code study, `content/docs/good-agents-md.md`). It degrades agent quality silently until measured. This step **surfaces** the risk; it is ADVISORY and MUST NOT block or fail the sync.
+
+1. ~ Scan the project's reachable documentation footprint: the top-level `docs/` / `_docs/` directories, nested `README.md` files, and any `architecture` / `design` docs.
+2. ~ Flag, as a non-blocking nudge, when any of these appear:
+   - A large `docs/` (or `_docs/`) directory that is **not referenced** from the AGENTS.md reference chain (orphan docs are discovered <10% of the time yet still cost context when found -- the reference-chain contract, #644).
+   - Deeply nested READMEs that duplicate guidance the reference chain already carries.
+   - Architecture / design docs that restate what the codebase already shows (a measured overexploration trigger).
+3. ~ Point the operator at `content/docs/agent-docs.md` (the empirically-grounded structure pattern) and the `REFERENCES.md` reference-chain contract for remediation. For directive's own always-loaded file, the `verify:agents-md-budget` ratchet (#645) and the consumer advisory (`agentsMdAdvisory`, #2155) are the size guards.
+4. ⊗ Do NOT convert this into a hard gate or auto-delete any doc -- the value is the nudge at the right moment; thresholds are a judgment call the operator owns.
+
 ## Phase 7 -- Summary
 
 ! Present a consolidated summary to the user covering:

package/tasks/verify.yml

@@ -35,6 +35,18 @@ tasks:
         vars:
           ENGINE_CMD: 'rule-ownership-lint --root "{{.DEFT_ROOT}}"'
 
+  biome-config:
+    desc: "Guard against #2190 (biome check . flipping recommended-preset diagnostic severity between warning and error non-deterministically): asserts biome.json declares an explicit non-error severity for noUnusedVariables and noNonNullAssertion. Three-state exit (0 clean / 1 missing/error severity / 2 config error)."
+    deps:
+      - task: :engine:_ts-build
+    # Framework-source-only gate: it reads THIS repo's own biome.json, so it
+    # targets DEFT_ROOT (not USER_WORKING_DIR) -- a consumer deposit has no
+    # TS engine / biome.json to guard. Mirrors verify:content-manifest.
+    cmds:
+      - task: :engine:invoke
+        vars:
+          ENGINE_CMD: 'verify-biome-config --project-root "{{.DEFT_ROOT}}"'
+
   content-manifest:
     desc: "Verify the Content Manifest (conventions/content-manifest.json) classifies every git-tracked top-level entry (#1821). Fails on an unclassified entry, a stale classified path, an invalid bucket, or a duplicate path. Wave-1 shippability audit for the engine/content split (#1669)."
     deps:
@@ -358,3 +370,27 @@ tasks:
       - task: :engine:invoke
         vars:
           ENGINE_CMD: 'verify:wip-cap --project-root "{{.USER_WORKING_DIR}}" {{.CLI_ARGS}}'
+
+  agents-md-budget:
+    desc: "Ratchet gate for AGENTS.md per-region line budgets (#645). Counts the managed section and the unmanaged region separately (the #1309 propagation duplicates content across the marker) and fails when either region grows past plan.policy.agentsMdBudget. Seeded at current size, so it ships green; growth past the ratchet fails. Lowering a budget (a reduction PR) is always allowed; raising it is a reviewed diff to the typed field. Three-state exit (0 within / 1 over / 2 config error)."
+    dir: '{{.USER_WORKING_DIR}}'
+    deps:
+      - task: :engine:_ts-build
+    # Per `conventions/task-caching.md` (#574): NO `sources:` / `generates:`
+    # because the gate forwards user-facing flags via {{.CLI_ARGS}} (--quiet).
+    cmds:
+      - task: :engine:invoke
+        vars:
+          ENGINE_CMD: 'verify:agents-md-budget --project-root "{{.USER_WORKING_DIR}}" {{.CLI_ARGS}}'
+
+  agents-md-advisory:
+    desc: "ADVISORY (never fail-closing) consumer AGENTS.md legibility signal (#2155). Counts the UNMANAGED (project-authored) region only -- the framework-owned managed section is excluded -- and compares it against the SOFT, operator-adjustable budget plan.policy.agentsMdAdvisory.unmanagedSoftMaxLines (generous default when unset). Consumer companion to the maintainer-only #645 ratchet; deliberately NOT a check:consumer dependency (advise->observe->enforce per #1419). Default posture ALWAYS exits 0; the opt-in --enforce flag promotes an over-budget region to a hard cap (exit 1). Raising the field is the documented, no-friction way to accept growth and silence the nudge."
+    dir: '{{.USER_WORKING_DIR}}'
+    deps:
+      - task: :engine:_ts-build
+    # Per `conventions/task-caching.md` (#574): NO `sources:` / `generates:`
+    # because the gate forwards user-facing flags via {{.CLI_ARGS}} (--quiet / --enforce).
+    cmds:
+      - task: :engine:invoke
+        vars:
+          ENGINE_CMD: 'verify:agents-md-advisory --project-root "{{.USER_WORKING_DIR}}" {{.CLI_ARGS}}'

package/templates/agent-prompt-preamble.md

@@ -96,7 +96,7 @@ Worked example (a tiered leaf worker on Composer):
 - model_source: cursor-route
 ```
 
-! Pre-dispatch gate (#1739): run `task verify:routing` before spawning a cohort -- it fails when a dispatched worker role has no decision (pinned model or explicit harness default) for the active provider. Session start runs `task verify:routing -- --advise` (non-blocking disclosure).
+! Pre-dispatch gate (#1739 / #1877): run `task verify:routing` before spawning ANY sub-agent (cohort OR solo) — it fails when a dispatched worker role has no decision (pinned model or explicit harness default) for the active provider. `task verify:story-ready` chains the same routing gate for single Cursor/Grok Task dispatches (#1877). Session start runs `task verify:routing -- --advise` (non-blocking disclosure).
 
 Reference: `.deft/routing.local.json` + `task swarm:routing-set` + `task verify:routing` (#1739, supersedes the `plan.policy.swarmSubagentBackend` enum of #1531a / #1735), `scripts/policy.py` `SWARM_WORKER_ROLES`, issue #1531 scope update (dispatch provider / worker role / model selection are three separate concerns).
 

package/templates/agents-consumer-header.md

@@ -0,0 +1,18 @@
+# Project
+
+<!-- Purpose: bounded consumer AGENTS.md header (#2065 Option A). Edit the one-liner below. Do NOT add Status / Next / Known Issues — they rot silently; see UPGRADING.md § AGENTS.md: managed vs unmanaged header. -->
+
+One-line project description (edit me).
+
+## Session orientation
+
+Scoped work, ranked queue, and tracked bugs live in authoritative sources — not in this header:
+
+- Project identity → `xbrief/PROJECT-DEFINITION.xbrief.json`
+- Scoped work → `xbrief/` lifecycle folders
+- Ranked queue → `deft triage:queue` / `deft triage:welcome`
+- Tracked bugs → GitHub issues
+
+## Local dev
+
+(Optional) Ephemeral shell quirks or uncommitted local artifacts only — not tracked work state.

package/templates/agents-entry.md

@@ -62,17 +62,10 @@ Check what exists before doing anything else:
 
 ⊗ Self-report the session-start ritual as complete without a fresh `deft session:start` state, or bypass `deft verify:session-ritual` before implementation dispatch. Headless workers and CI MAY set `DEFT_SESSION_RITUAL_SKIP=1`; the verifier exits 0 but warns when the bypass hides a failure.
 
-`deft doctor` remains the install-integrity + toolchain + AGENTS.md managed-section freshness probe (#1308). When the managed-section is stale, the doctor points the operator at `deft agents:refresh` to regenerate AGENTS.md from `templates/agents-entry.md`. The canonical `scripts/doctor.py` (single owner post #1335/#1336) also detects payload staleness from the `<install>/VERSION` manifest and, when behind, emits the canonical upgrade command `npm i -g @deftai/directive@latest` (#1339 / #1409 / #1912).
-
-**Canonical bootstrap / update path:** Install and upgrade via npm: `npm i -g @deftai/directive` (install) or `npm i -g @deftai/directive@latest` (upgrade). Node ≥ 20 is required to run Deft (the live gates run on the TypeScript engine). On a machine without Node, install Node first, then use npm — the frozen legacy Go installer (GitHub Releases) is only a legacy/offline + layout-migration bridge (#1912), not a Node-free path. Legacy `deft upgrade` / `run upgrade` are metadata-only acknowledgment and `deft relocate -- --confirm` is back-compat only; git-clone / submodule / legacy doctor surfaces are de-emphasized in UPGRADING.md / README / skills. Agent example: after installing, start your session; `deft doctor` tells you the exact state.
-`deft triage:welcome` emits the triage one-liner and, when state is incomplete, nudges the operator at `deft triage:welcome --onboard` (#1143). Default mode is non-interactive; the `--onboard` flag runs the 6-phase interactive ritual. D2's 4-hour suppression window governs repeat emission during session start; the canonical key compares structured fields from the latest `xbrief/.eval/summary-history.jsonl` record: `cache_empty`, `untriaged`, `stale_defer`, `in_flight`, `in_flight_filesystem`, `in_flight_cache_scoped`, `triage_scope_configured`, `wip_count`, `wip_cap`, `repos`, `scope_drift`, and `reconcilable` (#1279). Re-emission within the window occurs when any key field changes, including when the `[triage:scope]` discrepancy line appears or resolves.
-
-## Resume nudge (conditional, #1269)
-
-Reserved placement for the optional 6th conditional step (resume nudge from the ritual sentinel) tracked by #1269. The substance lands with that PR; this anchor exists today so consumers see the canonical placement once #1269 merges and the sentinel becomes available.
-
 ⊗ Reorder, skip, or merge the ritual tiers above without an explicit operator override -- the canonical order is what makes the downstream gate stack composable.
 
+`deft doctor` is the install-integrity + toolchain + managed-section freshness probe (#1308); when the managed section is stale it points at `deft agents:refresh`, and when the payload is behind it emits the upgrade command `npm i -g @deftai/directive@latest`. Install/upgrade via npm (`npm i -g @deftai/directive`; Node ≥ 20) — see `.deft/core/UPGRADING.md` for the bootstrap/upgrade path (the legacy Go installer is a legacy/offline bridge only). `deft triage:welcome` emits the triage one-liner and nudges `deft triage:welcome --onboard` when state is incomplete; its D2 4-hour suppression window and comparison-key set are owned by the `triage:welcome` implementation (#1143 / #1279).
+
 ## WIP cap
 
 The `plan.policy.wipCap` field caps the number of in-flight scope xBRIEFs (`xbrief/pending/` + `xbrief/active/`). The framework default is 10 (per umbrella #1119 Current Shape v3). When the cap is reached, `deft scope:promote` refuses with a relief hint pointing at `deft scope:demote --batch --older-than-days 30` (D1 / #1121). Operators can override the cap from the consumer side via `deft triage:welcome --onboard` (the Phase 4 wipCap prompt) or by inspecting / editing the typed field via `deft policy:show --field=wipCap`.
@@ -81,6 +74,10 @@ The `plan.policy.wipCap` field caps the number of in-flight scope xBRIEFs (`xbri
 
 Projects on the legacy `vbrief/` tree are still read-accepted; run `deft migrate:xbrief` to convert safely to `xbrief/` with semantic v0.6→v0.8 transforms. Legacy `x-vbrief/` reference tokens remain read-accepted until you migrate.
 
+## Unmanaged project header (#2065)
+
+! Do NOT treat the unmanaged AGENTS.md header as the work queue; ⊗ Do NOT add `Status`, `Next:`, or `Known Issues` blocks — they rot silently. See UPGRADING.md § AGENTS.md: managed vs unmanaged header for the Session orientation pointer and rationale.
+
 ## Cache-as-authoritative work selection (#1149)
 
 ! When the operator asks "what should I work on next?" / "build a cohort" / "what's the queue?", run `deft triage:queue --limit=10` (D11 / #1128) and present the ranked list before suggesting anything else. The agent MUST NOT recommend work from memory or open-GitHub-issue intuition. This is the consumer-side mirror of the maintainer rule of the same name; the triage queue is the source of truth for what to work on next.
@@ -89,23 +86,19 @@ Projects on the legacy `vbrief/` tree are still read-accepted; run `deft migrate
 
 ## Umbrella status reading (#1152 / #2066)
 
-Umbrella and epic issues carry a pass-1 body (plan, stale by design) and a canonical `## Current shape (as of pass-N)` comment (live state). Before reporting umbrella status:
+Rationale + cross-references: `.deft/core/docs/analysis/2026-07-02-agents-md-incident-rule-rationale.md` § Umbrella current-shape convention (#1152).
 
 - ! Fetch issue comments via REST (`gh api repos/<owner>/<repo>/issues/<N>/comments`), read the `## Current shape (as of pass-N)` comment, and any linked context or `LockedDecisions` xBRIEF referenced there — following the reading order body -> current-shape comment -> amendment comments (claim-cites-state-surface, #2066). Prefer the deterministic read path: `deft umbrella:current-shape <N>` (or `task umbrella:current-shape <N>`) — it locates the canonical comment, validates #1152 sections, and never falls back to the issue body.
 - ⊗ Conclude umbrella or epic status from the issue body alone. Any "X is done" / "X is the blocker" assertion about an umbrella MUST cite the current-shape comment or another state artifact, not the body.
 
-Cross-references: `.deft/core/.agents/skills/deft-directive-refinement/SKILL.md` and `.deft/core/.agents/skills/deft-directive-triage/SKILL.md` (before reporting umbrella status). Refs #1152, #2066.
-
 ## Issue body→comments reading (#2143)
 
-When ingesting or dispatching against **any** GitHub issue (not only umbrellas), later maintainer comments may supersede the original body — the #2126 recurrence shipped the wrong fix from a body-only fetch.
+Rationale + cross-references: `.deft/core/docs/analysis/2026-07-02-agents-md-incident-rule-rationale.md` § Issue body→comments reading (#2143); preamble § 5.6 in `.deft/core/content/templates/agent-prompt-preamble.md`.
 
 - ! Fetch both the issue body and `repos/<owner>/<repo>/issues/<N>/comments` via REST before concluding what the issue asks for or building a worker dispatch envelope. Read body first, then the comment thread in chronological order.
 - ! `deft issue:ingest` / `task issue:ingest` fetches `/comments` by default and folds the thread into the ingested overview (#2143).
 - ⊗ Build a dispatch envelope from the issue body alone when the issue has comments.
 
-Cross-references: `.deft/core/content/templates/agent-prompt-preamble.md` § 5.6. Refs #2143, #1152, #2066, #2126.
-
 ## Content packs
 
 Deft ships versioned content packs (e.g. lessons learned from prior work) under `.deft/core/packs/`. Discover and LOAD pack content via the slice surface instead of reading whole pack files into context:
@@ -125,31 +118,9 @@ Deft ships versioned content packs (e.g. lessons learned from prior work) under
 - ! When the MAP is wrong, update `plan.architecture.codeStructure` or the selected provider artifact, then regenerate the MAP.
 - ⊗ Treat a stale or absent MAP as an unrelated implementation blocker, hand-edit `.planning/codebase/MAP.md`, or make the generated projection more authoritative than the xBRIEF metadata.
 
-## Skill Routing
-
-When user input matches a trigger keyword, read the corresponding skill (paths are relative to the consumer's project root and resolve under `.deft/core/.agents/skills/`):
-
-- "review cycle" / "check reviews" / "run review cycle" -> `.deft/core/.agents/skills/deft-directive-review-cycle/SKILL.md`
-- "swarm" / "parallel agents" / "run agents" -> `.deft/core/.agents/skills/deft-directive-swarm/SKILL.md`
-- "decompose" / "story decomposition" / "swarm readiness" -> `.deft/core/.agents/skills/deft-directive-decompose/SKILL.md`
-- "refinement" / "reprioritize" / "refine" / "triage" / "pre-ingest" / "action menu" -> `.deft/core/.agents/skills/deft-directive-refinement/SKILL.md` -- the `work the cache` phrase routes to the dedicated `deft-directive-triage` entry below (#1130), not here, to keep routing unambiguous.
-- "triage <N>" / "triage issue" / "ingest issue" -> `.deft/core/.agents/skills/deft-directive-refinement/SKILL.md`
-- "build" / "implement" / "implement spec" -> `.deft/core/.agents/skills/deft-directive-build/SKILL.md`
-- "cost" / "budget" / "pre-build cost" / "how much will this cost" -> `.deft/core/.agents/skills/deft-directive-cost/SKILL.md`
-- "setup" / "bootstrap" / "onboard" -> `.deft/core/.agents/skills/deft-directive-setup/SKILL.md`
-- "sync" / "good morning" / "update deft" / "update xbrief" / "sync frameworks" -> `.deft/core/.agents/skills/deft-directive-sync/SKILL.md`
-- "pre-pr" / "quality loop" / "rwldl" / "self-review" -> `.deft/core/.agents/skills/deft-directive-pre-pr/SKILL.md`
-- "interview loop" / "q&a loop" / "run interview loop" -> `.deft/core/.agents/skills/deft-directive-interview/SKILL.md`
-- "run probe" / "/deft:directive:run:probe" / "probe" -> `.deft/core/.agents/skills/deft-directive-probe/SKILL.md` (deprecated alias: `/deft:run:probe`)
-- "glossary" / "ubiquitous language" / "domain model" / "DDD" / "define terms" -> `.deft/core/.agents/skills/deft-directive-glossary/SKILL.md`
-- "improve architecture" / "deep modules" / "interface design" / "refactor RFC" -> `.deft/core/.agents/skills/deft-directive-gh-arch/SKILL.md`
-- "debug" / "root cause" / "investigate" / "why did X break" / "why is X slow" / "systematic debugging" / "forensic" -> `.deft/core/.agents/skills/deft-directive-debug/SKILL.md`
-- "triage hygiene" / "work the cache" -> `.deft/core/.agents/skills/deft-directive-triage/SKILL.md`
-- "what's next" / "queue" / "build a cohort" -> `.deft/core/.agents/skills/deft-directive-triage/SKILL.md`
-- "welcome" / "onboard triage" -> invokes `deft triage:welcome --onboard` (N3 / #1143)
-- "lessons" / "prior art" / "what have we learned about X" -> discover packs with `deft packs:slice --list-packs`, then `deft packs:slice <pack> --list` and load the relevant slice before improvising (see Content packs above)
-
-The `deft-directive-release` skill is intentionally excluded -- it cuts deft framework releases against a temp clone of `deftai/directive` and is not a consumer-facing surface.
+## Skills
+
+Skill routing (which skill answers which trigger) is not a table in this policy section. To pick a skill, scan the **Skills Index** (Level-0) in `.deft/core/REFERENCES.md` — it lists every skill under `.deft/core/.agents/skills/` with a one-sentence description and trigger keywords, unified with the framework doc routing so you consult one place to decide what to load. Read a `SKILL.md` (Level-1) only when the index indicates a match. Before improvising a multi-step workflow, scan the skills catalog first — skills are versioned and tested. The `welcome` / `onboard triage` trigger invokes `deft triage:welcome --onboard` (N3 / #1143); for `lessons` / `prior art`, discover packs with `deft packs:slice --list-packs` then load the relevant slice (see Content packs above).
 
 ## Branch policy & branch verification
 
@@ -168,28 +139,22 @@ When the active project's `xbrief/PROJECT-DEFINITION.xbrief.json` has `plan.poli
 
 This phrasing comes from `.deft/core/scripts/policy.py::disclosure_line` and stays in lockstep with the typed surface (#746). When the policy is OFF (default; `allowDirectCommitsToMaster=false`), no session-start disclosure is required -- the absence of the disclosure line itself signals the default-enforcing state.
 
-Override paths the user may invoke:
-- `deft policy:show` -- inspect resolved policy
-- `deft policy:enforce-branches` -- re-enable branch protection
-- `deft policy:allow-direct-commits -- --confirm` -- re-confirm opt-out (audited)
-- `DEFT_ALLOW_DEFAULT_BRANCH_COMMIT=1` -- emergency env-var bypass
+Override paths (`deft policy:show` / `deft policy:enforce-branches` / `deft policy:allow-direct-commits -- --confirm` / `DEFT_ALLOW_DEFAULT_BRANCH_COMMIT=1`) are detailed in the Branch policy & branch verification section above.
 
 ⊗ Begin a session that will commit/push without surfacing the policy state when allowDirectCommitsToMaster=true.
 
-## PowerShell
-
-**Grok Build Windows capture limitations (#1353):** When running under the Grok Build runtime on Windows + pwsh 7+, `run_terminal_command` leaks internal wrapper text (Get-Content and redirection fragments) whenever the command string contains `|`, `2>&1`, `| cat`, `>`, or similar metacharacters. Non-piped commands execute cleanly.
+## Platform-conditional rules (PowerShell / Windows)
 
-- ! Never emit commands containing pipes or redirections through the agent shell tool on this platform. For anything requiring a pipe, use one of: Python one-liners with `pathlib` / `subprocess.run(capture_output=True)` (preferred -- bypasses the wrapper at the OS level), run the operation in the user's native terminal and paste the result back, or isolate the work in a dedicated worktree and mark the step as "user shell required".
-- ! This rule applies to the Grok Build runtime (pwsh 7+); Warp + Claude (PTY-based) is not affected.
+Platform/tool/runtime-specific rules are lazy-loaded, not rendered here, so they don't crowd context for sessions that can't trigger them (#2157 / #1882). If your session matches a trigger below, load `.deft/core/content/scm/github.md` § "PowerShell platform-conditional rules for agents" **before** the risky operation:
 
-Cross-reference: `.deft/core/docs/analysis/2026-05-26-issue-1353-grok-windows-capture-opensrc-audit.md`. Refs #1353.
+- ! Editing files with non-ASCII glyphs from PowerShell (especially PS 5.1) -- enforced at commit by `deft verify:encoding` (#798).
+- ! Running shell commands under the Grok Build Windows + pwsh 7+ runtime -- piped/redirected commands leak wrapper text (#1353); PTY-based Warp + Claude are exempt.
 
 ## Development Process
 
 ### Implementation Intent Gate (#810)
 
-- ! Run `deft xbrief:preflight -- <path>` before any code-writing tool call or `start_agent` dispatch -- the gate exits 0 only when the candidate xBRIEF lives in `xbrief/active/` AND `plan.status == "running"`. The Taskfile target resolves the wrapped script via `.deft/core/scripts/_resolve_preflight_path.py` (which probes the canonical, legacy, and in-repo install layouts in priority order) and fails closed with a structured `gate misconfigured` error pointing at `deft framework:doctor` if no candidate resolves -- the gate cannot silently fail open on a misconfigured install (#1046 / #1047). The helper names `deft xbrief:activate <path>` as its idempotent activation companion; story workflows should use the Story Start Gate below to bridge proposed/pending scope through `deft scope:promote` and `deft scope:activate` before invoking preflight.
+- ! Run `deft xbrief:preflight -- <path>` before any code-writing tool call or `start_agent` dispatch -- the gate exits 0 only when the candidate xBRIEF lives in `xbrief/active/` AND `plan.status == "running"`. Use the pre-`start_agent` gate stack step 2 for ordering and the Story Start Gate below for the `deft scope:promote` / `deft scope:activate` workflow bridge. If the gate is misconfigured, run `deft framework:doctor` and follow UPGRADING.md recovery guidance (#1046 / #1047).
 - ! Require an explicit action-verb directive (`build`, `implement`, `ship`, `swarm`, `run agents`, `start agent`) from the user before invoking the preflight gate or `start_agent` for implementation. When intent is ambiguous, ask one targeted question instead of inferring.
 - ⊗ Infer implementation intent from lifecycle vocabulary ("do the full PR process", "start the work", "poller agents"), branching language, or workflow shape. Workflow-shape vocabulary is NOT authorization to spawn an implementation agent.
 - ⊗ Treat affirmative continuation phrases (`yes`, `go`, `proceed`, `do it`) as implementation authorization unless the prior turn explicitly proposed implementation. Broad approval is not a substitute for an explicit action-verb directive.
@@ -201,11 +166,10 @@ Cross-reference: `.deft/core/docs/analysis/2026-05-26-issue-1353-grok-windows-ca
 - ! Before starting any new implementation story or switching from one story to another, run `git status --short --branch`.
 - ! If the working tree is dirty, stop and summarize the current branch, modified/untracked files, and whether the changes appear related to the next story. Ask the operator to choose one path: commit existing work, stash existing work, include existing work in the current story, or stop.
 - ⊗ Begin a new story while unrelated dirty work is present without explicit operator approval.
-- ! Resolve exactly one target story xBRIEF path by default. Batching multiple stories requires explicit operator approval and a short rationale.
+- ! Default to one story per branch/PR: resolve exactly one target story xBRIEF path by default, require explicit operator approval plus a short rationale for batching multiple stories, and create a checkpoint commit after each completed story before beginning another story.
 - ! When invoked as part of a swarm cohort dispatch, the approved Phase 5 allocation plan satisfies the "explicit operator approval and a short rationale" requirement above -- the dispatched paths and allocation rationale ARE the consent token. Do NOT re-prompt the parent for batching approval mid-cohort; the all-or-nothing dispatch envelope rule (#954) forbids mid-scope user-approval gates.
 - ! Within a swarm cohort, between stories, the working tree MUST be clean (a checkpoint commit + `deft scope:complete` just landed). If `git status --short` shows uncommitted state between stories, checkpoint-commit it and proceed -- do NOT pause to ask the operator. The dirty-tree "ask the operator" branch above applies only at the FIRST story-start of a fresh branch.
 - ! If the target story is in `xbrief/proposed/`, run `deft scope:promote -- <path>` first; if it is in `xbrief/pending/`, run `deft scope:activate -- <path>`. After activation, run `deft xbrief:preflight -- <active-story-path>` before code-writing.
-- ! Default to one story per branch/PR. Create a checkpoint commit after each completed story before beginning another story, unless the operator explicitly approved batching.
 - ! After checks pass for the story, complete the lifecycle with `deft scope:complete -- <active-story-path>` before final PR handoff.
 - ! Before dispatching an implementation sub-agent, run the deterministic Gate 0 `deft verify:story-ready -- --vbrief-path <active-story-path> [--allocation-context <dispatch-envelope-file>]` ahead of `deft xbrief:preflight`. It machine-checks a clean working tree (or `--allow-dirty`), the target xBRIEF in `xbrief/active/` with `plan.status == "running"`, and the dispatch envelope's `## Allocation context` consent token; three-state exit (0 ready / 1 not ready / 2 config error). A `swarm-cohort` section is ready only when `allocation_plan_id` AND `batching_rationale` are non-null; an absent section is the solo path. Any non-zero exit aborts dispatch.
 

package/templates/embed.go

@@ -18,3 +18,9 @@ import _ "embed"
 //
 //go:embed agents-entry.md
 var AgentsEntry string
+
+// AgentsConsumerHeader is the bounded unmanaged AGENTS.md header scaffold written
+// above the managed section on fresh consumer installs (#2065 Option A).
+//
+//go:embed agents-consumer-header.md
+var AgentsConsumerHeader string

package/templates/embed_test.go

@@ -2,6 +2,7 @@ package templates
 
 import (
 	"os"
+	"strings"
 	"testing"
 )
 
@@ -34,3 +35,29 @@ func TestAgentsEntryNonEmpty(t *testing.T) {
 		t.Fatal("AgentsEntry is empty -- templates/agents-entry.md embed is broken")
 	}
 }
+
+// TestAgentsConsumerHeaderMatchesFile asserts the embedded consumer header equals
+// templates/agents-consumer-header.md on disk (#2065).
+func TestAgentsConsumerHeaderMatchesFile(t *testing.T) {
+	onDisk, err := os.ReadFile("agents-consumer-header.md")
+	if err != nil {
+		t.Fatalf("could not read templates/agents-consumer-header.md: %v", err)
+	}
+	if AgentsConsumerHeader != string(onDisk) {
+		t.Errorf("embedded AgentsConsumerHeader drift from templates/agents-consumer-header.md:\n"+
+			"embedded len=%d, on-disk len=%d",
+			len(AgentsConsumerHeader), len(onDisk))
+	}
+}
+
+func TestAgentsConsumerHeaderOmitsRetiredSections(t *testing.T) {
+	if strings.Contains(AgentsConsumerHeader, "## Status") {
+		t.Error("consumer header must not scaffold ## Status (#2065)")
+	}
+	if strings.Contains(AgentsConsumerHeader, "## Known Issues") {
+		t.Error("consumer header must not scaffold ## Known Issues (#2065)")
+	}
+	if !strings.Contains(AgentsConsumerHeader, "## Session orientation") {
+		t.Fatal("consumer header must include Session orientation pointer")
+	}
+}

package/tools/package-manager-network.md

@@ -0,0 +1,29 @@
+# Package-Manager Network Access (#2182)
+
+Legend (from RFC2119): !=MUST, ~=SHOULD, ⊗=MUST NOT, ?=MAY.
+
+**⚠️ See also**: [main.md](../../main.md) | [tools/taskfile.md](./taskfile.md) | [scm/github.md](../scm/github.md)
+
+**Scope:** How Directive's own tooling (session ritual, doctor, read-only flows) treats npm/pnpm registry access as an explicit, security-sensitive, opt-in operation. Applies to Directive's own code, not to a consumer project's own build/install scripts.
+
+## Why this exists
+
+Directive runs against arbitrary repositories, including private monorepos with private package scopes, workspace dependencies, proxy configuration, and authenticated registries. If Directive silently invokes `npm`/`pnpm` during session startup or health checks, it may contact public or private registries, disclose package names/scopes/dependency-graph shape over the network, pick up unintended project/user registry configuration, or trip sandboxed network-approval prompts for work that never needed dependency resolution. Registry traffic itself is sensitive even when no secrets are printed.
+
+## Rules
+
+- ! Read-only, session-start, and session-ritual flows (`deft session:start`, `deft verify:session-ritual`, `deft verify:tools`) MUST perform no npm/pnpm registry access. Tool-presence probes MUST use PATH lookups (`which`/`accessSync`) or `--version` checks, never a subcommand that can resolve dependencies or query a registry.
+- ! `deft doctor` MUST default to an OFFLINE tier: no check in the default run may contact an npm/pnpm registry. The one check that can (`payload-staleness`, which resolves the latest framework version via `git ls-remote` and falls back to `npm view <package> version`) is gated behind the explicit `--network` flag and is skipped by default with a pointer to that flag.
+- ! Before a network-gated check runs, `deft doctor --network` MUST print a disclosure line naming the tool and registry class it may contact (e.g. "may contact your git remote and, as a fallback, the npm registry") BEFORE any network call is attempted.
+- ! Any future doctor check, session step, or read-only command that needs to invoke `npm`/`pnpm` in a way that can reach a registry MUST follow the same pattern: explicit flag or subcommand, disclosed registry class before the call, and offline by default.
+- ~ Where a package-manager operation is unavoidable in an explicitly-invoked flow (e.g. a release or install workflow that legitimately needs to fetch packages), prefer offline/frozen modes (`--offline`, `--prefer-offline`, `--frozen-lockfile`) when the operation only needs to validate local state rather than resolve fresh metadata.
+- ⊗ MUST NOT invoke `npm`/`pnpm` subcommands that can contact a registry from any code path reachable by `session:start`, `verify:session-ritual`, `verify:tools`, or the default `deft doctor` invocation.
+- ⊗ MUST NOT ship a new registry-reaching check without adding it to this doc and gating it the same way.
+
+## Non-goals
+
+This does not ban dependency installation or registry verification from explicit build/check/release workflows (e.g. `task build`, CI install steps) -- those are intentionally invoked and their network use is expected. It does not require supporting every private registry provider, and it does not replace npm/pnpm lockfile or provenance checks where they are intentionally invoked.
+
+## Reference implementation
+
+`packages/core/src/doctor/payload-staleness.ts` is the only code path in the TS engine that shells out to `npm` (`npm view`) or performs a git-remote network call for framework-currency checks; `packages/core/src/doctor/main.ts` gates it behind `--network` and prints the disclosure line first. `packages/core/src/session/session-start.ts` and `packages/core/src/verify-env/verify-tools.ts` perform no package-manager network access at all -- tool presence is resolved via PATH probing only.