@deftai/directive-content 0.103.0 → 0.105.0

package/tasks/occupancy.yml

@@ -0,0 +1,17 @@
+version: '3'
+
+# tasks/occupancy.yml -- worktree occupancy lease (#3433).
+
+vars:
+  DEFT_ROOT: '{{joinPath .TASKFILE_DIR ".."}}'
+
+tasks:
+  steal:
+    desc: "Supersede a live worktree occupancy lease (#3433). Flags: --confirm --occupant <id>"
+    dir: '{{.USER_WORKING_DIR}}'
+    env:
+      PYTHONUTF8: "1"
+    cmds:
+      - task: :engine:invoke
+        vars:
+          ENGINE_CMD: 'occupancy:steal --project-root "{{.USER_WORKING_DIR}}" {{.CLI_ARGS}}'

package/tasks/scm.yml

@@ -33,13 +33,9 @@ version: '3'
 # surfaces (--body-file, --add-label, --remove-label, ...) that this
 # stub deliberately does not re-implement; #881 owns the full surface.
 #
-# Forward-compat marker: the ONLY scm:* surface in v1 is the four issue:*
-# commands above plus the #1555 body-posting safety wrapper. PR commands
-# (scm:pr:list/view/merge/close) and any additional scm:* surface are
-# EXPLICITLY deferred to #881; do not add them here. See
-# vbrief/active/2026-05-05-883-story-1-scm-stub.vbrief.json for the full
-# Story 1 scope and vbrief/active/2026-05-05-883-deft-cache-quarantine-v1.vbrief.json
-# for the epic chain context.
+# Forward-compat marker: v1 was issue:* plus #1555 body-posting. #3391
+# adds scm:sync-default (dest-targeted staged sync PRs). Other PR verbs
+# remain #881.
 # ---------------------------------------------------------------------------
 
 vars:
@@ -163,6 +159,16 @@ tasks:
         vars:
           ENGINE_CMD: 'github-body comment-edit {{.CLI_ARGS}}'
 
+  sync-default:
+    desc: "[#3391] Open dest-targeted sync PRs under syncMaxFiles -- new PR per staged leg"
+    dir: '{{.USER_WORKING_DIR}}'
+    deps:
+      - task: :engine:_ts-build
+    cmds:
+      - task: :engine:invoke
+        vars:
+          ENGINE_CMD: 'scm:sync-default {{.CLI_ARGS}}'
+
   body:pr:edit:
     desc: "[#1555] Safely edit a PR body from --body-file and live gh read-back"
     dir: '{{.USER_WORKING_DIR}}'

package/tasks/vbrief.yml

@@ -142,8 +142,9 @@ tasks:
           ENGINE_CMD: 'vbrief-reconcile labels --project-root "{{.USER_WORKING_DIR}}" {{.CLI_ARGS}}'
 
   reconcile:umbrellas:
-    # Umbrella current-shape auto-update (#1289). Walks every kind=epic
-    # vBRIEF, resolves its children from its x-vbrief/plan references,
+    # Umbrella current-shape auto-update (#1289 / #3428). Walks every
+    # kind=epic vBRIEF and slices.jsonl umbrellas. Epic children come from
+    # x-vbrief/plan / github-issue refs; slices rows already list children.
     # computes the wave structure from the children's swarm.depends_on[]
     # edges, builds the canonical AGENTS.md section-1152 current-shape body
     # (Last updated / Last pass type / Child count / Child-count history /

package/tasks/verify.yml

@@ -47,6 +47,16 @@ tasks:
         vars:
           ENGINE_CMD: 'verify-biome-config --project-root "{{.DEFT_ROOT}}"'
 
+  telemetry-coverage:
+    desc: "Dead-surface detector for run-summary event kinds (#3362). Every RUN_SUMMARY_EVENT_KINDS member needs a production caller and a field-shaped fixture. Default is warn-only; pass --enforce to fail closed. -- task verify:telemetry-coverage [-- --enforce]"
+    deps:
+      - task: :engine:_ts-build
+    # Framework-source-only gate: scans THIS repo's packages/core/src emitters.
+    cmds:
+      - task: :engine:invoke
+        vars:
+          ENGINE_CMD: 'verify-telemetry-coverage --project-root "{{.DEFT_ROOT}}" {{.CLI_ARGS}}'
+
   contained-writes:
     desc: "Inventory raw product write sinks outside the contained-write allowlist (#2951 / #2980). Default CLI remains fail-open; task check wires --enforce fail-closed. -- task verify:contained-writes [-- --enforce]"
     deps:
@@ -155,6 +165,26 @@ tasks:
         vars:
           ENGINE_CMD: 'verify:branch --project-root "{{.USER_WORKING_DIR}}" --allow-missing-project-definition'
 
+  gh-auth:
+    # Worker-envelope GitHub auth validation (#1557). Thin task wrapper over the
+    # existing `github-auth-modes` engine verb, added by #3483: the swarm skill
+    # named `task verify:gh-auth` at MUST/⊗ level (references/core-phase-3.md
+    # Step 3, references/core-ops.md) but only the engine verb ever shipped, so
+    # the documented invocation exited 200 ("task does not exist").
+    #
+    # NOTE: NO `sources:` / `generates:` per conventions/task-caching.md --
+    # this probes live process/network state through {{.CLI_ARGS}} flags and a
+    # cached skip would return a stale verdict.
+    desc: "Validate GitHub auth from the worker envelope (#1557): host-gh vs injected-token mode, gh auth status, and API reachability. Fails closed on missing_injected_token in cloud-headless. -- task verify:gh-auth [-- --json] [--repo OWNER/NAME] [--github-auth-mode host-gh|injected-token]"
+    dir: '{{.USER_WORKING_DIR}}'
+    deps:
+      - task: :engine:_ts-build
+    cmds:
+      # Bare CLI_ARGS per the verify:encoding convention -- go-task shell-escapes pass-through args.
+      - task: :engine:invoke
+        vars:
+          ENGINE_CMD: 'github-auth-modes {{.CLI_ARGS}}'
+
   routing:
     desc: "Operator coding sub-agent model routing gate (#1739). Pre-dispatch (default): fails when a dispatched worker role has no decision in .deft/routing.local.json. Pass --advise for the non-blocking session-start disclosure; --roles a,b to widen the gated set; --provider to override the runtime."
     dir: '{{.USER_WORKING_DIR}}'
@@ -463,7 +493,7 @@ tasks:
           ENGINE_CMD: 'verify:wip-cap --project-root "{{.USER_WORKING_DIR}}" {{.CLI_ARGS}}'
 
   orphan-active:
-    desc: "Fail-closed orphan-active guard (#2321). Detects xbrief/active/ briefs with plan.status==running whose referenced GitHub issues are all closed and/or whose linked PR is merged — the stop-at:pr-open lifecycle leak. Remediation points at task scope:complete / scope:cancel or swarm finalize surfaces. Three-state exit (0 clean / 1 orphan / 2 config). Pass --skip-gh to rely on triage cache only."
+    desc: "Fail-closed orphan-active guard (#2321 / #3429). Detects xbrief/active/ briefs with plan.status==running whose referenced GitHub issues are all closed and/or whose linked PR is merged — the stop-at:pr-open lifecycle leak. Confirmed shipped remediates with task scope:complete / scope:cancel or swarm finalize. Unresolved GitHub lookup still exits 1 but prints a retry, not scope:complete. Three-state exit (0 clean / 1 orphan / 2 config). Pass --issue N to scan one origin after merge; --skip-gh to rely on triage cache only."
     dir: '{{.USER_WORKING_DIR}}'
     deps:
       - task: :engine:_ts-build
@@ -473,7 +503,7 @@ tasks:
           ENGINE_CMD: 'verify:orphan-active --project-root "{{.USER_WORKING_DIR}}" {{.CLI_ARGS}}'
 
   completed-tracked:
-    desc: "Fail-closed completed-tracked land guard (#3264 / #1358 recurrence). Closed scoped GitHub issues with a known lifecycle xBRIEF origin must have a tracked xbrief/completed/ or xbrief/cancelled/ artifact on the delivery tip. Remediation: task swarm:finalize-cohort or a lifecycle PR. Three-state exit (0 clean / 1 missing land / 2 config). Pass --skip-gh to rely on triage cache only; --tip to override delivery tip."
+    desc: "Fail-closed completed-tracked land guard (#3264 / #1358 / #3476). Closed scoped GitHub issues with a known lifecycle xBRIEF origin must have a tracked xbrief/completed/ or xbrief/cancelled/ artifact on the delivery tip. --issue N is the drive-to DONE form. Remediation: task swarm:finalize-cohort or a lifecycle PR. Three-state exit (0 clean / 1 missing land / 2 config). Pass --skip-gh to rely on triage cache only; --tip to override delivery tip."
     dir: '{{.USER_WORKING_DIR}}'
     deps:
       - task: :engine:_ts-build

package/tasks/xbrief.yml

@@ -5,6 +5,29 @@ vars:
 
 tasks:
 
+  validate:
+    # Canonical xBRIEF lifecycle validation verb (#3483).
+    # Mirrors tasks/vbrief.yml validate exactly; callers use:
+    #   task xbrief:validate
+    # Legacy `task vbrief:validate` remains accepted for the same gate and is
+    # what CONSUMER_CHECK_GATES / `task check` still wire (gate ids are stable).
+    #
+    # The #2109 vbrief -> xbrief rename added xbrief:-prefixed verbs where the
+    # surface was rewritten (xbrief:preflight), but validate never got its
+    # alias while the swarm skill prose was updated as if it had -- leaving
+    # four MUST/⊗-level cohort-close instructions naming a verb that did not
+    # resolve. Refs #1487 (the recurrence the cohort-close gate prevents).
+    desc: "Validate xBRIEF lifecycle folder structure and cross-file consistency. Alias of vbrief:validate with xbrief-first naming (#3483)."
+    dir: '{{.USER_WORKING_DIR}}'
+    deps:
+      - task: :engine:_ts-build
+    cmds:
+      # Layout-aware (#2109 part 2a): pass --project-root and let the engine
+      # resolve the lifecycle dir (xbrief when migrated, else vbrief).
+      - task: :engine:invoke
+        vars:
+          ENGINE_CMD: 'xbrief:validate --project-root "{{.USER_WORKING_DIR}}"'
+
   preflight:
     # Canonical #810 implementation-intent gate for the xBRIEF lifecycle (#2449).
     # Mirrors tasks/vbrief.yml preflight; callers use:
@@ -18,3 +41,23 @@ tasks:
       - task: :engine:invoke
         vars:
           ENGINE_CMD: 'xbrief:preflight --vbrief-path {{.CLI_ARGS}}'
+
+  activate:
+    # Implementation-intent activation companion to xbrief:preflight (#3483).
+    # Mirrors tasks/vbrief.yml activate; callers use:
+    #   task xbrief:activate -- xbrief/pending/<story>.xbrief.json
+    # This is the redirect the preflight failure message names, and the swarm
+    # skill names it at MUST level (references/core-phase-0.md Step 1) -- so it
+    # has to resolve under the xbrief: spelling, not just vbrief:.
+    #
+    # NOTE: NO `sources:` / `generates:` per conventions/task-caching.md --
+    # the xBRIEF path is a user-facing {{.CLI_ARGS}} argument and a cached
+    # skip would silently swallow it.
+    desc: "Activate an xBRIEF: pending/ -> active/ (status: running). Idempotent. Alias of vbrief:activate with xbrief-first naming (#810 / #3483)."
+    dir: '{{.USER_WORKING_DIR}}'
+    deps:
+      - task: :engine:_ts-build
+    cmds:
+      - task: :engine:invoke
+        vars:
+          ENGINE_CMD: 'xbrief:activate {{.CLI_ARGS}}'

package/templates/agent-prompt-preamble.md

@@ -418,6 +418,15 @@ Decision tree:
 
 The probe itself is a `core`-bucket call, so polling it cheaply does not consume GraphQL.
 
+## 7.5 Forge-outage drop-back (#3422)
+
+#3167 caps CI-holdout babysit loops. #3180 attributes weather holds. Neither replaces this drop-back.
+
+! On attributed platform outage (`attribution: platform`) or repeated REST 429/502/503: **drop back** GitHub I/O (empty-commit, close/reopen, tight polls, new poller children), **report once** to the human in chat (what is down, attribution/incident, parked work, next probe time), and **re-probe once per** `plan.policy.forgeOutageRetryMinutes` (default **30**; USER.md Personal wins; min 5; `task policy:show --field=forgeOutageRetryMinutes`). Local work that does not need the forge MAY continue. Depth: `content/scm/github.md` § #3180 / #3422.
+
+⊗ Tight retry, empty-commit thrash, or sending the human to github.com as the only remediation.
+⊗ Auto-merge / `--skip-ci` because a status page is red (#3180).
+
 ## 8. Identity separation -- mode-aware GitHub credential rules (#983 / #1557)
 
 Workers MUST follow the GitHub credential rule recorded in the dispatch envelope's `github_auth_mode` field (§2.7) or launch manifest. The rule prevents maintainer/worker bucket coupling and audit conflation when modes are mixed across a cohort.
@@ -464,11 +473,11 @@ These rules bind **orchestrators** dispatching implementation, fix, or review-cy
 - ! **Envelope selection SLA (#3153):** Choose the boundary before spawn using the swarm decision tree (`skills/deft-directive-swarm/references/core-phase-0.md` — capacity stall, conf-only residual, wall-clock budget, large multi-gate, host nest limits). Happy-path default remains `drive-to: merge-ready`. A **deliberate** `stop-at: pr-open` is valid only with an immediate partner merge-path owner per `skills/deft-directive-review-cycle/SKILL.md` § Partner merge-path (babysit / Approach 1 lease / parent-retained — not freestyle global babysit). Under human-merge policy, that owner (or an explicit handoff recipient) remains responsible through merge + `scope:complete` — do not stand down at CLEAN alone. Consumer pin: `templates/agents-entry.md` § Envelope selection SLA. Silent PR-open handback for a worker already scoped merge-ready remains **forbidden**.
 - ! **Cursor Task ownership split (#2797 / #2814):** A Cursor `Task` implementation leaf MUST NOT spawn another Cursor `Task` review-monitor: nested Task (leaf spawning leaf) is unsupported/unreliable. A Cursor `drive-to: merge-ready` leaf instead owns a blocking `task pr:watch -- <N>` in its own process. To use an Approach 1 monitor, scope the leaf `stop-at: pr-open`; the orchestrator that owns the Task primitive then launches the sibling monitor and runs `task review-monitor:register -- --pr <N> --monitor-agent-id <id> --platform-primitive cursor-task` (GitHub sticky `<!-- deft:review-owner -->` lease — not local JSON).
 - ⊗ Let a Cursor leaf background `task pr:watch` and claim review monitoring is active. The process dies with the leaf and has no GitHub review-owner lease; treat that claim as a regression/eval failure and let `task verify:review-monitor -- --pr <N>` fail closed.
-- ! **Post-merge scope lifecycle (#2321 / Gap C):** Workers scoped `stop-at: pr-open` MUST NOT run `task scope:complete` before exit — their activation checkpoint rides into master on merge. The **orchestrator** (or Phase 6 `task swarm:finalize-cohort` / `task swarm:complete-cohort` on the headless path) MUST run `task scope:complete` or `task scope:cancel` for each shipped story xBRIEF after its PR merges. Workers scoped `drive-to: merge-ready` (or `drive-to: merge`) MUST include `task scope:complete` on their active xBRIEF as part of the same unit of work (after merge when appropriate).
+- ! **Post-merge scope lifecycle (#2321 / Gap C / #3429 / #3476):** Workers scoped `stop-at: pr-open` MUST NOT run `task scope:complete` before exit — their activation checkpoint rides into master on merge. The **orchestrator** (or Phase 6 `task swarm:finalize-cohort` / `task swarm:complete-cohort` on the headless path) MUST run `task scope:complete` or `task scope:cancel` for each shipped story xBRIEF after its PR merges. Workers scoped `drive-to: merge-ready` (or `drive-to: merge`) MUST include `task scope:complete` on their active xBRIEF as part of the same unit of work (after merge when appropriate). After merge (or observing merge) of issue `#N`, run `task verify:orphan-active -- --issue N`. Exit `0` is required before `DONE`. Exit `1` shipped → run the printed `task scope:complete -- <path>`. Exit `1` unresolved lookup → retry / emit `BLOCKED`; ⊗ complete unfinished scope. After `scope:complete`, `task verify:completed-tracked -- --issue N` MUST be exit `0` against `origin/<deliveryBranch>` (not feature-worktree HEAD) before `DONE` (#3476). Exit `1` missing tracked artifact → not DONE; remediate with `task swarm:finalize-cohort` or a lifecycle PR. `scope:complete` stays filesystem-only — ⊗ teach every leaf to commit on master.
 - ! Workers scoped `drive-to: merge-ready` MUST drive to merge-ready in their own tool loop — pre-PR, push, PR open, review-cycle poll/fix loop, and the #1259 Step 6 fail-closed exit — without handing back at PR-open for the orchestrator to re-dispatch separate leaf agents for review or fixes.
 - ⊗ Re-dispatch a separate review-monitor or fix agent after an implementation worker exits at PR-open when the original envelope scoped `drive-to: merge-ready` — that split recreates cross-agent state-handoff hazards and terminal lifecycle gaps (#1878 / Gap C).
 - ⊗ Dispatch `stop-at: pr-open` without a named review-cycle partner merge-path owner plan (#3153).
-- ⊗ Leave an `xbrief/active/` brief with `plan.status == running` on master after the story's issue is closed or its PR merged — `task verify:orphan-active` fails closed on that signature (#2321).
+- ⊗ Leave an `xbrief/active/` brief with `plan.status == running` on master after the story's issue is closed or its PR merged, or emit `DONE` with `ISSUE: closed` while that brief remains in `active/` — `task verify:orphan-active -- --issue N` must be exit `0` after merge (#2321 / #3429).
 
 **Background / independent dispatch (Gap D):**
 
@@ -535,6 +544,16 @@ The parent monitor watches the heartbeat file directly (three-state exit 0 ok /
 Principle: `main.md` `## Rule Authority [AXIOM]`.
 Principle: `main.md` `## Thin Fail-Closed Design (#3265)`.
 
+## 10.56 Writing bar — clarity, simplicity, brevity (#3368)
+
+! Clarity, simplicity, brevity in documents and user communications, including sub-agent status and handbacks. Cut ceremony, not required fields. Depth: `.deft/core/docs/writing-ste100.md` (#2927 / #3368). ⊗ Full STE; ⊗ historical rewrite; ⊗ red CI style gate; ⊗ prefacing the rule.
+
+## 10.57 Telemetry deliverable fixture (#3362)
+
+! A telemetry deliverable is not done until a field-shaped fixture reads its events from the shared fake trial (`task verify:telemetry-coverage`). Silence is the failure mode this gate exists for.
+
+⊗ Ship a new `RUN_SUMMARY_EVENT_KINDS` member or exported emitter method without a production caller and a fixture that asserts the kind in `DEFT_RUN_SUMMARY_PATH` JSONL.
+
 ## 10.6 Dual stop for multi-iteration worker loops (#2442)
 
 Multi-iteration implement, pre-PR, repair, and monitor loops require **two** stops: **success** (goal / AC / checker met) and **failure or budget** (max iterations, no-progress, or time/token budget). Single-turn tasks are exempt. Principle and defaults: `main.md` `## Dual Stop Rule (#2442)`; build skill dual-stop table; swarm Phase 4 / core-ops.
@@ -552,7 +571,7 @@ Every worker MUST send a final status message before exiting its tool loop, rega
 - Failure: `FAILED: <reason> + recovery hint`
 - Stand-down: `STOOD-DOWN: <reason>` (e.g. user said "wait" with no follow-up dispatch)
 
-! **`drive-to: merge-ready` DONE reservation (#2843):** When the dispatch envelope scoped `drive-to: merge-ready` (or `drive-to: merge`), `DONE` is reserved for merge-ready completion — `task pr:merge-ready -- <N>` exit 0 on current HEAD, or merge + `task scope:complete` when the envelope included merge authority. Greptile P0/P1 outstanding, CI failure, branch behind, review-cycle cap, or any other merge blocker MUST NOT exit as `DONE`.
+! **`drive-to: merge-ready` DONE reservation (#2843):** When the dispatch envelope scoped `drive-to: merge-ready` (or `drive-to: merge`), `DONE` is reserved for merge-ready completion — `task pr:merge-ready -- <N>` exit 0 on current HEAD, or merge + `task scope:complete` when the envelope included merge authority. After merge, `task verify:orphan-active -- --issue <N>` MUST be exit 0 before `DONE` (#3429). Exit 1 shipped → run the printed `task scope:complete -- <path>`. Exit 1 unresolved lookup → retry / emit `BLOCKED`; ⊗ complete unfinished scope. After `scope:complete`, `task verify:completed-tracked -- --issue <N>` MUST be exit 0 against `origin/<deliveryBranch>` (not feature-worktree HEAD) before `DONE` (#3476). Exit 1 missing tracked artifact → not DONE; remediate with `task swarm:finalize-cohort` or a lifecycle PR. Untracked laptop `xbrief/completed/` is not land. Greptile P0/P1 outstanding, CI failure, branch behind, review-cycle cap, or any other merge blocker MUST NOT exit as `DONE`.
 
 ! **Mid-cycle BLOCKED contract (#2843):** A `drive-to: merge-ready` worker that must exit before merge-ready (blocker, cap, context limit, host turn budget) MUST emit `BLOCKED:` (never `DONE`) with: PR number (or `no-pr`), HEAD SHA, blocker class (`greptile_p0_p1` / `ci_failures` / `behind_base` / `review_cycle_cap` / `context_limit` / other), worktree path, and `REDISPATCH_OK` when a continuation leaf should take over. Example: `BLOCKED: Greptile P1 on HEAD abc1234 (PR #2842, blocker greptile_p0_p1, worktree .deft-scratch/worktrees/2839-appsec, REDISPATCH_OK)`.
 

package/templates/agents-entry.md

@@ -12,11 +12,11 @@ Deft is installed in .deft/core/. Full guidelines: .deft/core/main.md
 
 ## Session routing (#2176)
 
-! **Read-only default** until mutation intent: load AGENTS.md / main.md / USER.md / `xbrief/PROJECT-DEFINITION.xbrief.json`; resolve USER.md via `deft session:start` (`USER.md resolved …`; win32 `%APPDATA%\deft\USER.md`; unix `~/.config/deft/USER.md`; ⊗ invent `~/.config/deft` on Windows #2544); confirm Deft alignment + addressing-name; ⊗ no mutable `deft session:start` / triage welcome / sync / branch-policy unless asked or implementation-ready (#2176) — `.deft/core/commands.md` § Session routing. Bootstrap: cold-start → README § Cold-start (#2273) ⊗ never `.deft/core/`; pre-cutover → setup Pre-Cutover (#2068); missing USER.md / PROJECT-DEFINITION → setup Phase 1/2 (#1813) ⊗ before answering; else main → USER → PROJECT-DEFINITION; ~ sync. Mutation → `deft session:start` then `deft verify:session-ritual -- --tier=gated` (#1149). ? `deft session:start -- --read-only` (#2176).
+! **Read-only default** until mutation intent: load AGENTS.md / main.md / USER.md / `xbrief/PROJECT-DEFINITION.xbrief.json`; resolve USER.md via `deft session:start` (`USER.md resolved …`; win32 `%APPDATA%\deft\USER.md`; unix `~/.config/deft/USER.md`; ⊗ invent `~/.config/deft` on Windows #2544); confirm Deft alignment + addressing-name; ⊗ no mutable `deft session:start` / triage welcome / sync / branch-policy unless asked or implementation-ready (#2176) — `.deft/core/commands.md` § Session routing. Bootstrap: cold-start → README § Cold-start (#2273) ⊗ never `.deft/core/`; pre-cutover → setup Pre-Cutover (#2068); missing USER.md / PROJECT-DEFINITION → setup Phase 1/2 (#1813) ⊗ before answering; else main → USER → PROJECT-DEFINITION; ~ sync. Mutation → `deft session:start` then `deft verify:session-ritual -- --tier=gated` (#1149). Mutation ceremony claims a worktree occupancy lease (#3433; `commands.md` § Session routing). ? `deft session:start -- --read-only` (#2176).
 
 ## Session-start ritual (#1149)
 
-! On **mutation** session start, run `deft session:start`; before code-writing or `start_agent` dispatch run `deft verify:session-ritual -- --tier=gated` (stale after `plan.policy.sessionRitualStalenessHours`; records `deft verify:tools` / `deft doctor` / `deft verify:cache-fresh` / `deft agents:refresh` / `npm i -g @deftai/directive@latest`; #1149 / #1348) — `.deft/core/commands.md` § Session-start ritual. ! SCM mirror tip (#3124): restate existence + get-the-most user-visible when tip fires (depth `commands.md`). ⊗ Absorb tip without restating.
+! On **mutation** session start, run `deft session:start`; before code-writing or `start_agent` dispatch run `deft verify:session-ritual -- --tier=gated` (stale after `plan.policy.sessionRitualStalenessHours`; records `deft verify:tools` / `deft doctor` / `deft verify:cache-fresh` / `deft agents:refresh` / `npm i -g @deftai/directive@latest`; #1149 / #1348) — `.deft/core/commands.md` § Session-start ritual. Recovery: `deft session:ready` (one-shot: start + gated ritual + cache recovery; #2993). ! SCM mirror tip (#3124): restate existence + get-the-most user-visible when tip fires (depth `commands.md`). ⊗ Absorb tip without restating.
 
 ## WIP cap
 
@@ -25,6 +25,8 @@ Deft is installed in .deft/core/. Full guidelines: .deft/core/main.md
 ## xBRIEF layout (#2034 / #2110)
 
 Legacy `vbrief/` read-accepted; `deft migrate:xbrief` for `xbrief/` (v0.6→v0.8). `x-vbrief/` tokens read-accepted until migrated.
+! Completed xBRIEFs are record of *what is*, zero authority over *what to build next* (#3383). Current contract = active xBRIEF + human operator live instruction. Depth: `main.md` Persistence; build skill declare-the-contract / halt-and-ask.
+⊗ Treat a completed xBRIEF as the next-build contract.
 
 ## Unmanaged project header (#2065)
 
@@ -70,6 +72,8 @@ Legacy `vbrief/` read-accepted; `deft migrate:xbrief` for `xbrief/` (v0.6→v0.8
 ! Prefer `task deft:*` over AGENTS.md prose. See main.md.
 ## Thin Fail-Closed Design (#3265)
 ! One fail-closed `task deft:*` check + one remediation. See main.md.
+## Writing bar (#3368)
+! Clarity, simplicity, brevity in documents and user communications, including sub-agent status and handbacks. Cut ceremony, not required fields. STE how: `.deft/core/docs/writing-ste100.md` (#2927). ⊗ Full STE; ⊗ historical rewrite; ⊗ red CI style gate; ⊗ prefacing the rule.
 
 ## Continuous Improvement Learning (#607 / #3164)
 
@@ -88,6 +92,8 @@ Legacy `vbrief/` read-accepted; `deft migrate:xbrief` for `xbrief/` (v0.6→v0.8
 ⊗ Silent PR-open handback for a worker already scoped `drive-to: merge-ready`.
 ⊗ `stop-at: pr-open` without a named babysit / merge-path owner, or dual review-monitor leases on recovery (#3044 / #2261).
 ⊗ Stand down at CLEAN under human-merge with no reachable post-merge `scope:complete` owner.
+! After merge of issue `#N`, `deft verify:orphan-active -- --issue N` MUST exit 0 before `DONE` (#3429). After `scope:complete`, `deft verify:completed-tracked -- --issue N` MUST exit 0 on `origin/<deliveryBranch>` before `DONE` (#3476). Exit 1 shipped → printed `scope:complete`; missing tracked land → `swarm:finalize-cohort` or a lifecycle PR; unresolved lookup → retry / `BLOCKED` (⊗ complete unfinished scope).
+⊗ Emit `ISSUE: closed` while that brief is still in `active/`.
 
 ## Nuclear-family A2A topology (#3155)
 
@@ -129,6 +135,7 @@ Legacy `vbrief/` read-accepted; `deft migrate:xbrief` for `xbrief/` (v0.6→v0.8
 ## Contextual guardrails (runtime-detect lazy-load)
 
 ! Detect OS/shell; use portable syntax or explicit shell (#2568). `.deft/core/scm/github.md` (#2157/#2369): PS encoding→`deft verify:encoding` (#798); TS capture; cascade→`deft pr:wait-mergeable-and-merge`; SCM→`deft verify:scm-boundary`.
+! Forge outage (#3422): drop GitHub I/O on attributed outage or repeated 429/502/503; report once to the human; re-probe on `plan.policy.forgeOutageRetryMinutes` (default 30; USER.md Personal wins). Depth: `scm/github.md` § #3180. Complements #3167 / #3180.
 
 ## Development Process
 

package/vbrief/schemas/vbrief-core.schema.json

@@ -614,6 +614,18 @@
           "minimum": 1,
           "description": "Maximum age, in hours, for .deft/ritual-state.json before the fail-closed session ritual verifier requires task session:start to run again. Default: 4."
         },
+        "forgeOutageRetryMinutes": {
+          "type": ["integer", "null"],
+          "minimum": 5,
+          "description": "Minutes to wait between GitHub I/O re-probes after a forge outage drop-back (#3422). Default: 30. USER.md Personal wins over this project field. null is unset (same as omit)."
+        },
+        "projectInvariants": {
+          "type": "array",
+          "description": "Authored project-level must-not-break contracts (#3425). Empty or omitted is a no-op. Each entry names an id, statement, and contract surface (paths and/or module ids).",
+          "items": {
+            "$ref": "#/$defs/ProjectInvariant"
+          }
+        },
         "requireHumanMerge": {
           "type": "boolean",
           "description": "When true, agents may open PRs but must not merge (#1193). Defaults true when autoDeployOnMerge is also true. Override: policy:allow-bot-merge --confirm or DEFT_ALLOW_BOT_MERGE=1."
@@ -631,6 +643,66 @@
       },
       "additionalProperties": true
     },
+    "ProjectInvariant": {
+      "type": "object",
+      "description": "One authored project invariant (#3425). Contract surface is paths and/or module ids that must not be broken.",
+      "required": ["id", "statement"],
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1
+        },
+        "statement": {
+          "type": "string",
+          "minLength": 1
+        },
+        "contractSurface": {
+          "$ref": "#/$defs/ProjectInvariantContractSurface"
+        },
+        "contract_surface": {
+          "oneOf": [
+            { "$ref": "#/$defs/ProjectInvariantContractSurface" },
+            { "type": "array", "items": { "type": "string" } }
+          ]
+        },
+        "paths": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "moduleIds": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "module_ids": {
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      },
+      "additionalProperties": true
+    },
+    "ProjectInvariantContractSurface": {
+      "type": "object",
+      "description": "Must-not-break module/contract surface: repository paths and/or codeStructure module ids.",
+      "properties": {
+        "paths": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "pathGlobs": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "moduleIds": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "module_ids": {
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      },
+      "additionalProperties": true
+    },
     "HotfixCriteria": {
       "type": "object",
       "description": "Structural hotfix eligibility thresholds (#1193). Agent may label hotfix-candidate only; human promotes hotfix.",