@deftai/directive-content 0.66.2 → 0.68.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-gh-slice/SKILL.md

@@ -97,6 +97,7 @@ Iterate until the user approves the breakdown.
 
 ### Step 5: Create the GitHub issues
 
+- ! **Pre-filing master-diff check (#1102):** before filing an issue that proposes ADDING a file or directory, run `git ls-tree origin/master -- <path>` (or `gh api repos/{owner}/{repo}/contents/{path}` for repos without a local clone) to confirm the file does not already exist on master. If it does, scope the issue to the DELTA between current state and the proposed end-state, not the original "deposit this file" framing.
 - ! Create issues in dependency order (blockers first) so you can reference real issue numbers
 - ! Use `gh issue create` for each approved slice with the template below
 - ! Trace each issue back to the relevant SPECIFICATION.md phase/task IDs where applicable
@@ -197,3 +198,4 @@ task slice:list                  # enumerate recorded slices for verification
 - ⊗ Proceeding without `gh` authentication
 - ⊗ Omitting dependency ordering — blockers must be created first
 - ⊗ Describing implementation internals instead of observable behavior in issue bodies
+- ⊗ File an issue proposing to add a file or directory that already exists on master without first running the `git ls-tree origin/master -- <path>` existence check (#1102) -- the stale "add file X" filing (#1099 proposed adding `.github/dependabot.yml`, which had already landed via #1070; closed as a duplicate and re-filed as the additive-delta #1100) is exactly the recurrence this check prevents

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-refinement/SKILL.md

@@ -154,6 +154,8 @@ The agent may suggest the next phase, but the user decides. Phases can be entere
 
 ! Scan external sources for new work items and create proposed scope xBRIEFs.
 
+! **Pre-filing master-diff check (#1102).** When a refinement pass FILES a new GitHub issue that proposes ADDING a file or directory (rather than ingesting an existing issue), first run the pre-filing existence check from [`../deft-directive-gh-slice/SKILL.md`](../deft-directive-gh-slice/SKILL.md) Step 5 -- `git ls-tree origin/master -- <path>` (or `gh api repos/{owner}/{repo}/contents/{path}`) -- so a stale "add file X" issue is never opened against state that already exists on master (the #1099 -> #1100 close-and-refile recurrence).
+
 ### Step 1: Gather Sources
 
 1. ? Scan non-GitHub sources (Jira, direct user requests, etc.) manually if applicable — those ingest paths are not yet task-wrapped

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

@@ -774,7 +774,20 @@ What the sweep does (script: `scripts/swarm_complete_cohort.py`):
 
 ! **Interactive path:** the monitor runs `task swarm:complete-cohort` by hand (or `--dry-run` first to preview the planned transitions) once the merge cascade finishes, then runs `task xbrief:validate`.
 
-! **Headless / multi-worker path:** the cohort sweep is NOT optional here -- it is the structural fix for the #1487 recurrence where the multi-worker close-out never executed the per-cohort completion. The launching monitor (or the close-out automation that follows `task pr:wait-mergeable-and-merge`, #1369) MUST invoke `task swarm:complete-cohort -- --cohort '<cohort-glob>'` after the last cohort PR merges and MUST gate on its exit 0 plus a green `task xbrief:validate` before declaring the swarm closed. The `--json` flag emits a structured verdict for a parent monitor agent to consume.
+! **Headless / multi-worker path (#2225):** after the merge cascade (`task pr:wait-mergeable-and-merge`, #1369) reports the cohort's PRs MERGED, the monitor SHOULD invoke the automated finalize surface instead of hand-authoring a separate lifecycle-sweep PR:
+
+```pwsh path=null start=null
+# Resolve merged stories from PR closing keywords and land the sweep PR:
+task swarm:finalize-cohort -- --pr <N1>,<N2> --repo <owner/repo> [--label <cohort-label>]
+# Preview only (no commit / no PR):
+task swarm:finalize-cohort -- --pr <N1>,<N2> --repo <owner/repo> --dry-run
+# Explicit story list when PR bodies omit Closes #N:
+task swarm:finalize-cohort -- --stories <issue-or-path>... --repo <owner/repo>
+```
+
+The finalize surface runs the same `completeCohort(...)` engine as `task swarm:complete-cohort`, fast-forwards the local base branch, creates a `swarm/finalize/<label>` feature branch (branch policy #747 safe), commits the `xbrief/` lifecycle moves, and auto-opens the sweep PR. Pass `--no-commit` to sweep only (manual Step 2b), or `--no-open-pr` to commit locally without opening the PR. Gate on exit 0 plus green `task xbrief:validate` before declaring the swarm closed.
+
+! **Manual fallback (#1487):** `task swarm:complete-cohort` remains the idempotent manual primitive when finalize automation is unavailable or you need a dry-run preview of transitions only. The headless path above replaces the historical requirement to hand-author a separate `chore(xbrief)` sweep PR every cycle.
 
 ⊗ Declare a swarm closed while any cohort story xBRIEF remains in `xbrief/active/` or any fully-childless decompose-created epic parent remains in `xbrief/pending/` -- run `task swarm:complete-cohort` and confirm `task xbrief:validate` is green first (#1487).
 

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/engine.yml

@@ -37,7 +37,7 @@ tasks:
 
   invoke:
     internal: true
-    desc: "Run a deft-ts verb from vendored bin.js (source checkout) or global deft (npm consumer deposit)."
+    desc: "Run a deft-ts verb from vendored bin.js (source checkout) or global deft (npm consumer deposit). Source checkouts without a built dist fail fast (#2181) -- runtime/session tasks must not trigger engine:_ts-build / pnpm."
     # Run from the operator project root so deft verbs resolve USER_WORKING_DIR
     # correctly; without this, included engine.yml defaults cwd to tasks/ (#2022).
     dir: '{{.USER_WORKING_DIR}}'
@@ -45,8 +45,33 @@ tasks:
       - |
         set -eu
         bin="{{.DEFT_ROOT}}/packages/cli/dist/bin.js"
+        root_pkg="{{.DEFT_ROOT}}/package.json"
+        is_buildable_source=0
+        if [ -f "{{.DEFT_ROOT}}/packages/cli/package.json" ] \
+           && [ -f "$root_pkg" ] \
+           && node -e "const fs=require('fs');const j=JSON.parse(fs.readFileSync(process.argv[1],'utf8'));process.exit(j.scripts&&j.scripts.build?0:1)" "$root_pkg"; then
+          is_buildable_source=1
+        fi
         if [ -f "$bin" ]; then
+          if [ "$is_buildable_source" = 1 ] && [ -f "$root_pkg" ]; then
+            node -e "
+              const fs=require('fs');
+              const pkg=JSON.parse(fs.readFileSync(process.argv[1],'utf8'));
+              const req=pkg.engines&&pkg.engines.node;
+              if(!req) process.exit(0);
+              const major=Number(process.versions.node.split('.')[0]);
+              const m=String(req).match(/>=\\s*(\\d+)/);
+              if(m&&major<Number(m[1])){
+                console.error('deft: Node '+process.versions.node+' does not satisfy engines.node '+req+' (read from '+process.argv[1]+').');
+                process.exit(2);
+              }
+            " "$root_pkg" || exit $?
+          fi
           node "$bin" {{.ENGINE_CMD}}
+        elif [ "$is_buildable_source" = 1 ]; then
+          echo "deft: CLI artifact missing at {{.DEFT_ROOT}}/packages/cli/dist/bin.js" >&2
+          echo "  Run \`task build\` first (framework source checkout)." >&2
+          exit 2
         elif command -v deft >/dev/null 2>&1; then
           deft {{.ENGINE_CMD}}
         else

package/tasks/pr.yml

@@ -95,3 +95,32 @@ tasks:
       - task: :engine:invoke
         vars:
           ENGINE_CMD: 'pr-wait-mergeable {{.CLI_ARGS}}'
+
+  # pr:watch -- deterministic PR-verdict polling surface (#1056). A
+  # blocking-by-default poll that resolves to a terminal three-state verdict
+  # (exit 0 CLEAN / 1 NEW_P0_P1 / 2 ERRORED|STALL|TIMEOUT|config), so an
+  # orchestrator that promises to poll a PR review to conclusion cannot
+  # silently forget (the invocation IS the wait). --one-shot degrades to a
+  # single probe. Reuses the CANONICAL Greptile/SLizard verdict detector
+  # (packages/core/src/content-contracts/skills/greptile-detector.ts -- the
+  # same module pr:merge-ready and the swarm poller template consume); no
+  # second detector. SHA-match gating means a stale pre-push review is never
+  # read as the verdict. All gh access routes through the UTF-8-safe
+  # execFile shim (#1366). Cross-referenced from the AGENTS.md
+  # `## Multi-agent orchestration discipline (#954)` Tier-4 pointer.
+  #
+  # Per `conventions/task-caching.md` (#574): NO `sources:` / `generates:`
+  # because user-facing flags (`--one-shot` / `--max-wait-minutes` /
+  # `--poll-seconds` / `--json` / `--repo` / `--project-root`) MUST NOT be
+  # silently swallowed by go-task's incremental-build cache.
+  #
+  # Companion module: packages/core/src/pr-watch/
+  # Companion tests:  packages/core/src/pr-watch/*.test.ts
+  watch:
+    desc: "Blocking poll of a PR to a terminal three-state verdict (0 CLEAN / 1 NEW_P0_P1 / 2 ERRORED|STALL|TIMEOUT|config); --one-shot for a single probe (#1056)"
+    deps: [":engine:_ts-build"]
+    dir: '{{.USER_WORKING_DIR}}'
+    cmds:
+      - task: :engine:invoke
+        vars:
+          ENGINE_CMD: 'pr-watch {{.CLI_ARGS}}'

package/tasks/session.yml

@@ -12,7 +12,7 @@ tasks:
   start:
     desc: "Run quick-tier session-start ritual and write .deft/ritual-state.json (#1348). Flags: --defer step=reason / --json"
     dir: '{{.USER_WORKING_DIR}}'
-    deps: [":engine:_ts-build"]
+    # Runtime/session dispatch: no engine:_ts-build / pnpm build (#2181).
     env:
       PYTHONUTF8: "1"
     cmds:

package/tasks/swarm.yml

@@ -93,3 +93,19 @@ tasks:
       - task: :engine:invoke
         vars:
           ENGINE_CMD: 'swarm-complete-cohort {{.CLI_ARGS}} --project-root "{{.USER_WORKING_DIR}}"'
+
+  # swarm:finalize-cohort -- post-merge cohort lifecycle automation (#2225).
+  # After a cohort's PRs merge, resolves the merged stories (via Closes #N ->
+  # active-brief mapping or an explicit --stories list), runs the same
+  # completeCohort(...) sweep as swarm:complete-cohort, and lands the
+  # active/ -> completed/ moves on a feature branch with an auto-opened PR —
+  # eliminating the hand-authored lifecycle-sweep PR tax for stop-at:pr-open
+  # swarms. swarm:complete-cohort remains the idempotent manual primitive.
+  finalize-cohort:
+    desc: "After cohort PRs merge, auto-sweep story briefs active/ -> completed/ and open the lifecycle PR (#2225)"
+    deps: [":engine:_ts-build"]
+    dir: '{{.USER_WORKING_DIR}}'
+    cmds:
+      - task: :engine:invoke
+        vars:
+          ENGINE_CMD: 'swarm-finalize-cohort {{.CLI_ARGS}} --project-root "{{.USER_WORKING_DIR}}"'

package/tasks/triage-summary.yml

@@ -23,7 +23,7 @@ tasks:
   summary:
     desc: "Emit the D2 (#1122) one-line triage state for the session-start ritual (N9 / #1149). Always exits 0; appends a JSONL record to vbrief/.eval/summary-history.jsonl. -- task triage:summary -- [--json] [--no-history]"
     internal: true
-    deps: [":engine:_ts-build"]
+    # Runtime/session dispatch: no engine:_ts-build / pnpm build (#2181).
     dir: '{{.USER_WORKING_DIR}}'
     cmds:
       - task: :engine:invoke

package/tasks/triage-welcome.yml

@@ -24,7 +24,7 @@ tasks:
   welcome:
     desc: "Run the 6-phase onboarding ritual (N3 / #1143): detect prior state, prompt subscription scope, run triage:bootstrap, prompt wipCap, offer WIP relief, print triage:summary. Idempotent; re-run resumes cleanly. -- task triage:welcome -- [--no-subprocess]"
     internal: true
-    deps: [":engine:_ts-build"]
+    # Runtime/session dispatch: no engine:_ts-build / pnpm build (#2181).
     dir: '{{.USER_WORKING_DIR}}'
     env:
       DEFT_TASK_PREFIX: '{{.DEFT_TASK_PREFIX | default ""}}'

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:
@@ -145,6 +157,20 @@ tasks:
         vars:
           ENGINE_CMD: 'verify:encoding --project-root "{{.USER_WORKING_DIR}}" {{.CLI_ARGS}}'
 
+  forward-coverage:
+    desc: "Forward-coverage gate (#1310): fail when a NEW source file (scripts/, src/, cmd/, packages/*/src, or *.py/*.go/*.ts/*.tsx, excluding *.test.ts / *_test.go / test_*.py / *.d.ts) is added without a corresponding test in the SAME diff. Migrates the prose 'new source files MUST include tests' rule to deterministic enforcement, mirroring verify:encoding (#798) / verify:branch (#747). Defaults to the HEAD-relative diff; pass --staged for the pre-commit invocation. Three-state exit (0 clean / 1 missing forward coverage / 2 config error)."
+    dir: '{{.USER_WORKING_DIR}}'
+    deps:
+      - task: :engine:_ts-build
+    # Per `conventions/task-caching.md`: NO `sources:` / `generates:` because
+    # user-facing flags (--staged / --head / --allow-list <path> / --quiet) MUST
+    # NOT be silently swallowed by go-task's incremental-build cache (same
+    # rationale as verify:encoding above).
+    cmds:
+      - task: :engine:invoke
+        vars:
+          ENGINE_CMD: 'verify:forward-coverage --project-root "{{.USER_WORKING_DIR}}" {{.CLI_ARGS}}'
+
   vbrief-conformance:
     desc: "Detect bare non-conformant vBRIEF keys (#1620). Scans tracked vbrief/**/*.vbrief.json and flags any document/plan/item key that is not 0.6 spec-core, x-directive/-namespaced, or x-vbrief/-namespaced. plan.policy + plan.completedNote carry a TEMPORARY allow-list pending vBRIEF #12. Defaults to --all; pass --staged for the pre-commit invocation."
     dir: '{{.USER_WORKING_DIR}}'
@@ -178,8 +204,8 @@ tasks:
   cache-fresh:
     desc: "Pre-`start_agent` cache-freshness gate (#1127). Refuses implementation dispatch when the triage cache is stale, missing, or the target issue's latest decision is not `accept`. Subscription-aware via plan.policy.triageScope[] (D12 / #1131). Flags: --for-issue N / --max-age-hours N / --allow-stale / --repo OWNER/NAME / --allow-missing-bootstrap (consumed by the framework's own `task check` so a fresh checkout passes -- consumers leave it OFF)."
     dir: '{{.USER_WORKING_DIR}}'
-    deps:
-      - task: :engine:_ts-build
+    # Runtime/session + pre-dispatch gate: no engine:_ts-build / pnpm build (#2181).
+    # Parent `task check` still builds via its own engine:_ts-build dep first.
     # Per `conventions/task-caching.md` (#574): NO `sources:` / `generates:`
     # because the gate forwards user-facing flags via {{.CLI_ARGS}}
     # (--for-issue / --max-age-hours / --allow-stale / --repo) that
@@ -208,8 +234,7 @@ tasks:
   session-ritual:
     desc: "Fail-closed session ritual verifier (#1348). Flags: --tier quick|gated / --json. Set DEFT_SESSION_RITUAL_SKIP=1 for headless workers and CI."
     dir: '{{.USER_WORKING_DIR}}'
-    deps:
-      - task: :engine:_ts-build
+    # Runtime/session dispatch: no engine:_ts-build / pnpm build (#2181).
     # No sources/generates: this gate is time-, HEAD-, and worktree-sensitive.
     cmds:
       # Oracle/fallback (parity): scripts/verify_session_ritual.py (#1828 Wave 8 / #1854 s3).
@@ -220,8 +245,7 @@ tasks:
   tools:
     desc: "Detect required Deft host tools and print install or manual guidance (#1187). Flags: --install / --yes / --json"
     dir: '{{.USER_WORKING_DIR}}'
-    deps:
-      - task: :engine:_ts-build
+    # Runtime/session dispatch: no engine:_ts-build / pnpm build (#2181).
     cmds:
       # Oracle/fallback (parity): scripts/verify_tools.py (#1828 Wave 8).
       - task: :engine:invoke
@@ -358,3 +382,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
 
@@ -159,6 +130,7 @@ Three consumer-facing surfaces enforce the branch-policy contract (#746 / #747):
 - `deft verify:branch` -- branch gate wired into the `deft check` aggregate; refuses a commit on the default branch unless `plan.policy.allowDirectCommitsToMaster = true` (typed) or `DEFT_ALLOW_DEFAULT_BRANCH_COMMIT=1` is set.
 - `.githooks/pre-commit` / `pre-push` -- local hooks installed via `deft setup`; verify via `deft verify:hooks-installed`. After a framework upgrade, run `deft update` to refresh hook templates to the current TS-native `deft verify:*` / `deft preflight-gh` wiring (#2049).
 - `deft policy:show --field=allowDirectCommitsToMaster` -- inspect the resolved policy; `deft policy:allow-direct-commits -- --confirm` writes the typed override with an audit row.
+- `deft verify:forward-coverage` -- forward-coverage gate (#1310): a NEW source file (`scripts/`, `src/`, `cmd/`, `packages/*/src`, or `*.py`/`*.go`/`*.ts`/`*.tsx`, excluding tests + `*.d.ts`) added without a corresponding test in the SAME diff fails the gate. Wired into `deft check` + the pre-commit hook (`--staged`); document genuine exceptions (shims, generated code) via `--allow-list <path>`. Mirrors the `deft verify:encoding` (#798) prose->deterministic migration.
 
 ## Branch Policy Disclosure (#746)
 
@@ -168,28 +140,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 +167,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