@deftai/directive-content 0.90.0 → 0.92.0

package/patterns/in-band-signaling.md

@@ -0,0 +1,124 @@
+# No in-band signaling / absence is not a decision (#1695)
+
+Coding-standards pattern: do not overload one field (or its
+presence/absence) to carry two orthogonal facts. Separate **value** from
+**decision-provenance**. Triggered by the wipCap onboarding contradiction
+(#1694).
+
+Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
+
+**Load when:** modeling a config/policy field, or any onboarding /
+decision / lifecycle state that might be inferred from whether a value
+is present.
+
+**⚠️ See also**:
+- [../coding/coding.md](../coding/coding.md) — always-loaded Design
+  Principles floor (`**State & Data Modeling (#1695)**`)
+- [../coding/coding.md](../coding/coding.md) — resolver `source`
+  provenance (typed | default | default-on-error) for *value*-provenance
+
+## The pattern
+
+**In-band signaling** smuggles control or metadata through the data
+channel. **Out-of-band signaling** gives the control signal its own
+field.
+
+The cautionary prior art is the blue-box / 2600 Hz tone: phone systems
+shared the control signal with the voice channel, so a tone on the data
+path could seize trunk control. The same footgun appears under several
+names:
+
+- Overloaded NULL / sentinel values (SQL NULL meaning "unknown" *and*
+  "not applicable" *and* "use default")
+- Connascence of Meaning (Page-Jones) — components silently agreeing
+  what a magic value or absence *means*
+- "Make illegal states unrepresentable" — an ambiguous
+  "absent-but-decided vs absent-and-undecided" state should not be
+  expressible in one field
+- Single Responsibility applied to data — one field, one reason to
+  change
+
+- ! MUST encode exactly one fact per field
+- ! MUST record decision / onboarding / lifecycle state in an explicit
+  out-of-band marker when a workflow needs to know a human chose
+- ⊗ MUST NOT infer decision-state from whether a value field is present
+- ⊗ MUST NOT treat field absence as "incomplete" when omission is a
+  deliberate valid default
+
+## The orthogonality test
+
+Ask: can fact A and fact B vary independently?
+
+| Fact A (value) | Fact B (decided?) | Independent? |
+| --- | --- | --- |
+| value == default | decided = true (accepted default) | yes |
+| value == default | decided = false (never considered) | yes |
+| value == override | decided = true | yes |
+| value == override | decided = false | usually illegal |
+
+If two facts can vary independently, they MUST live in separate slots.
+If one fact strictly implies the other, sharing a slot is fine:
+
+- **True `Optional<T>`** — absence means "no value" and there is no
+  second "was this considered?" question
+- **Tombstones** — a dedicated deleted/absent sentinel that only means
+  lifecycle, not a configured value
+- **Value-provenance `source`** — once a resolved value exists, source
+  ∈ {typed, default, default-on-error} is a property *of that resolve*,
+  not a second independent human decision
+
+Worked examples:
+
+1. **WIP cap onboarding (#1694)** — `plan.policy.wipCap` value vs "did
+   the operator consider a cap?" Independent; use
+   `x-directive/onboarding.wipCapDecided`.
+2. **Feature flag default** — `enabled: false` may mean "deliberately
+   off" or "never configured." If product needs the distinction, store
+   an explicit decided marker.
+3. **Optional timeout** — absence of `timeoutMs` means "use library
+   default" and no workflow asks whether a human considered it. One
+   fact; one field is fine.
+
+## Three kinds of provenance in directive
+
+Directive already separates two of three facts for policy resolution:
+
+| Kind | What it answers | Modeled? |
+| --- | --- | --- |
+| **Effective value** | What int/string do we use right now? | yes (the field or default) |
+| **Value-provenance** | Override vs framework default vs error-fallback? | yes (`source` on resolvers / `PolicyField`) |
+| **Decision-provenance** | Did a human choose this (including accepting default)? | **must be modeled out-of-band** |
+
+- ! MUST generalize the `source` discipline to decision-provenance:
+  never fake "operator decided" from field presence
+- ! MUST leave value fields to mean exactly one thing (e.g.
+  `plan.policy.wipCap` = deliberate non-default override only)
+- ~ SHOULD keep decision markers under an `x-directive/` namespaced
+  block when the value lives on PROJECT-DEFINITION
+
+## Canonical worked example — wipCap onboarding (#1694)
+
+**Before:** `_classify_onboarding` / `classifyOnboarding` treated
+absent `plan.policy.wipCap` as incomplete onboarding. Accepting the
+framework default (omit-by-design, #1186 D1 / #1250) left the field
+absent forever, so the nudge never cleared. Setting a non-default
+cleared the nudge but broke `test_policy_omits_wip_cap`. The nudge was
+structurally unsatisfiable on deft's own repo.
+
+**Root cause:** one field carried two orthogonal facts — configured
+value *and* decision-made.
+
+**After (#1694 direction 2):**
+
+- `plan.policy.wipCap` (or `x-directive/policy.wipCap`) means only a
+  deliberate non-default override
+- `plan["x-directive/onboarding"].wipCapDecided` records that the
+  operator considered WIP cap (including accepting the default)
+- `writeWipCapDecision` / `writeWipCap` (default path) set the marker
+  without materializing the value field
+- `classifyOnboarding` reads decision-provenance, not field presence
+
+Greenfield consumers still get prompted until they run
+`deft triage:welcome --onboard` (or otherwise record the decision).
+Deft's own repo commits the marker with `acceptedDefault: true` and
+stays omit-by-design green.

package/scm/github.md

@@ -290,6 +290,53 @@ Rationale: `docs/analysis/2026-07-02-agents-md-incident-rule-rationale.md` § SC
 
 See also § ghx cache proxy (#884) for install surfaces and read-only vs mutation rules.
 
+## Mismatched/headless SCM readiness (#2275)
+
+Follow-up to adoption epic #2203 (Decision 7). Framework-local gates
+(`session:start`, `verify:*`, `xbrief:preflight`, `doctor`, `scope:*`,
+local `cache-fresh` checks) run with zero SCM tooling. SCM-dependent gates
+need `gh`/`ghx` **in the execution env** (not only on the install host) plus
+auth.
+
+### Probe contract
+
+- ! `session:start` (read-only, cold, and re-arm) reports SCM readiness via
+  `[deft scm]` lines and a `scm` object in `--json`. Shallow by default
+  (PATH + token presence + short `gh auth status`); deep API validation when
+  `--with-network` / `DEFT_SESSION_START_NETWORK=1`.
+- ! `deft scm:status` (alias `scm:readiness`) is the explicit probe verb:
+  exit `0` ready / `1` not ready / `2` config. Flags: `--json`,
+  `--deep` / `--shallow` / `--depth shallow|deep`.
+- ! When not ready, diagnostics MUST name the reason
+  (`binary-absent` | `missing-token` | `unauthenticated` | ...) and list
+  skipped gates (`triage:queue`, `issue:ingest`, `pr:*`, `reconcile:issues`,
+  `cache:fetch-all`, `scm:*`, ...). Never fail opaquely on a missing binary.
+- ! Session-start itself MUST NOT hard-block when SCM is unavailable
+  (framework-local orientation still succeeds).
+- ! SCM-dependent verbs that actually need the network MUST fail loud with
+  the #2275 diagnostic (exit non-zero / `ScmStubError`) rather than hang on
+  auth prompts or emit an unhelpful spawn error.
+- ⊗ Echo `GH_TOKEN` / `GITHUB_TOKEN` / `GH_ENTERPRISE_TOKEN` values into
+  prompts, transcripts, logs, or `--json` payloads -- report presence only
+  (`injected_token_present`).
+
+### Making SCM gates runnable in a mismatched env
+
+1. **Host-gh (local / unsandboxed):** install GitHub CLI (or `task setup:ghx`)
+   in the *execution* environment, then `gh auth login`. Host credential
+   stores are not shared into agent sandboxes.
+2. **Injected-token (cloud / headless):** set `GH_TOKEN`, `GITHUB_TOKEN`, or
+   `GH_ENTERPRISE_TOKEN` in the execution env via host secrets. Runtime mode
+   `cloud-headless` infers `github_auth_mode=injected-token` (#1557).
+3. **Run SCM elsewhere:** keep framework-local work in the sandbox; run
+   `triage:*` / `pr:*` / `issue:ingest` from a matched authenticated shell.
+4. **Deep check:** `deft scm:status --deep` or
+   `deft github-auth-modes --json` validates API reachability and optional
+   repo access.
+
+Contract file: `content/contracts/scm-readiness.md`. Implementation:
+`packages/core/src/scm/readiness.ts`.
+
 ## 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-build/SKILL.md

@@ -27,6 +27,42 @@ Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
 
 ## Ordered-plan / cohort exhaustion (#2402)
 
+## Multi-scope turn/cache budget (epic #3009)
+
+Multi-scope greenfield (app-bank pins, N story scopes) multiplies agent turns when ceremony, promote, check, and render are re-run per scope. Apply the following after offline seed.
+
+### Offline seed vs implement phase (#3010)
+
+! Distinguish **offline seed** (operator or harness already ran `directive init` / deposit, pin-copied scopes into `xbrief/proposed/`, and recorded session ritual) from the **agent implement phase**.
+
+! When seed + session ritual are already complete for the engagement:
+- ⊗ Run `directive init` again
+- ⊗ Run full cold `session:start` unless hooks deny writes and recovery is required
+- ⊗ Run `directive migrate` or re-copy scopes already present
+- ! Prefer recovery via `session:ready` (or re-arm) when PreToolUse denies — not full re-init
+- ! Documented consumer/harness contract: seed is done once; implement agents only activate+implement
+
+### Batch promote; one active implement (#3011)
+
+! For a multi-scope pin, batch-stage scopes with `task scope:promote -- --batch` (all `proposed/`) or `task scope:promote -- --batch <path>…`.
+! Implement path remains **one** `scope:activate` + implement at a time — no multi-active write fence.
+! When pin order is known, do **not** re-list the entire lifecycle tree every scope; walk the known ordered list.
+⊗ Activate all scopes at once or drop the one-active-scope / story-ready stack.
+
+### Quality check once at end of multi-scope batch (#3012)
+
+! On an approved multi-scope batch (operator-approved multi-story branch, swarm cohort, or pin walk): run full `task check` (merge chokepoint) **once at the end of the batch** (or after the last scope), not after every scope.
+! Exception: if the last full check **failed**, fix loops MAY re-run check until green.
+! Pre-PR / merge-ready gates remain end-of-unit — this does not weaken them.
+! Iteration lane (affected tests / `verify:forward-coverage` / `coverage:hotspots`) still applies **per scope** during implementation (#1704).
+⊗ Spam full `directive check` / `task check` after every scope when the batch is still mid-flight and the last merge-chokepoint check was green.
+
+### One-shot project:render (#3013)
+
+! Greenfield init seeds a minimal render-ready `PROJECT-DEFINITION`. Treat `task project:render` as a **refresh of items from lifecycle folders**, not multi-turn identity research.
+⊗ Invent project identity across many turns when seed already stamped the skeleton.
+
+
 ! When processing an approved multi-story cohort or an active ordered-plan sequence, stop after the final approved entry. Do not promote or dispatch adjacent stories from queue intuition. Continuation language advances only within the approved order; skill-chaining is non-authorizing.
 
 ## Step 0 -- Implementation Preflight (#810)
@@ -39,7 +75,7 @@ Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
 - ! **Swarm-cohort dispatch carve-out**: when this skill is invoked as part of a swarm cohort allocated by `skills/deft-directive-swarm/SKILL.md`, the approved Phase 5 allocation plan satisfies the "explicit operator approval and short rationale recorded in the handoff" requirement above -- the dispatched xBRIEF paths and allocation rationale ARE the consent token. Process each assigned story sequentially under the checkpoint-commit + `task scope:complete` discipline below. Do NOT re-prompt the parent for batching approval mid-cohort -- the all-or-nothing dispatch envelope rule (`AGENTS.md` `## Multi-agent orchestration discipline (#954)`) forbids mid-scope user-approval gates.
 - ! **Structured consent-token recognition (#1378)**: the canonical recognition path for the carve-out above is the structured `## Allocation context` section of the dispatch envelope (the frozen schema in `templates/agent-prompt-preamble.md`, Story A of #1378). When that section reports `dispatch_kind: swarm-cohort` with a non-null `allocation_plan_id` AND a non-null `batching_rationale`, the consent token is satisfied mechanically -- read `cohort_vbriefs` as the authoritative file boundary and process each entry sequentially under the checkpoint-commit + `task scope:complete` discipline below, without re-prompting the parent for batching approval mid-cohort. When the `## Allocation context` section is ABSENT (pre-#1378 dispatches, solo-interactive sessions), fall back to the #1371 prose carve-out immediately above -- the prose carve-out remains the recognition path of record for un-elevated envelopes.
 - ! **Within a cohort, between stories**: the working tree MUST be clean after each story's checkpoint commit + `task scope:complete`. If `git status --short` shows uncommitted state between stories (e.g. a missed `task scope:complete` move, an unstaged file from the prior story), 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, where uncommitted operator work might legitimately exist.
-- ! If the target story is in `xbrief/proposed/`, run `task scope:promote -- <path>` first; if it is in `xbrief/pending/`, run `task scope:activate -- <path>`. After activation, update the path to the active-file location before preflight.
+- ! If the target story is in `xbrief/proposed/`, run `task scope:promote -- <path>` first (or `task scope:promote -- --batch` for a multi-scope pin — #3011); if it is in `xbrief/pending/`, run `task scope:activate -- <path>`. After activation, update the path to the active-file location before preflight.
 - ! Before any code-writing tool call -- the first scaffold edit, the first `task` invocation that mutates files, or any `start_agent` dispatch that will implement scope -- MUST run `task xbrief:preflight -- <active-story-path>` (the structural intent gate; wraps `scripts/preflight_implementation.py` so the same invocation works whether deft is the project root or installed as a `deft/` subdirectory).
 
 The gate exits 0 only when the candidate xBRIEF lives in `xbrief/active/` AND `plan.status == "running"`. Any other state (pending/, proposed/, completed/, active/-with-non-running-status, malformed JSON, missing keys) exits 1 with an actionable redirect to `task xbrief:activate <path>`.
@@ -255,6 +291,9 @@ task test:coverage  # >=85% or PROJECT-DEFINITION.xbrief.json override
 - ! Phase checkpoint commits MAY use the iteration lane; phase is NOT done for PR handoff until full `task check` passes at the merge chokepoint
 - ⊗ Skip quality gates or claim they passed without running
 - ⊗ Treat iteration-lane green as merge-ready without full `task check`
+- ! **Multi-scope batch (#3012):** when implementing an approved multi-scope pin/cohort, reserve full `task check` for end-of-batch (or after last scope) unless the last full check failed — then re-run on the fix loop. Do not run full check after every intermediate scope.
+- ⊗ Re-run full install/session ceremony after offline seed when ritual is already complete (#3010) — use `session:ready` for recovery only.
+
 
 ## Coding Standards (Summary)
 
@@ -320,6 +359,10 @@ feat(phase-2): add REST API endpoints with integration tests
 - ⊗ Move to next phase before current passes checks
 - ⊗ Make commits without running iteration-lane validation; ⊗ skip full `task check` at PR/merge chokepoint (#1704)
 - ⊗ Proceed without USER.md -- always run the USER.md Gate first
+- ⊗ Re-run `directive init`, cold `session:start`, migrate, or re-copy pin scopes after offline seed when ritual is already complete (#3010)
+- ⊗ Run full `task check` after every intermediate scope of an approved multi-scope batch when the last merge-chokepoint check was green (#3012)
+- ⊗ Promote scopes one-by-one for a known multi-scope pin when `scope:promote --batch` would stage them in one turn (#3011)
+
 - ⊗ Spawn an implementation agent or invoke a code-writing tool against a xBRIEF that has not passed `task xbrief:preflight` (which wraps `scripts/preflight_implementation.py`) -- always run the Step 0 Implementation Preflight (#810) first; satisfy via `task xbrief:activate <path>`
 - ⊗ Proceed without `COST-ESTIMATE.md` and a recorded build / rescope / no-build / skip(+reason) decision -- always run the Cost Phase Gate (#739) first
 - ⊗ Proceed with implementation when the build or test toolchain is unavailable -- always run the Toolchain Gate (Step 2) first

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

@@ -144,7 +144,9 @@ git --no-pager diff master
 - ! Check for scope creep -- changes that go beyond the spec task acceptance criteria
 - ! Verify no debug code, TODO comments, or temporary scaffolding remains
 - ! 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
+- ! **Closing-keyword policy (#3015 class D / #737 Layer 0):** Default PR body uses `Tracking: #N` / `Related: #N` / `Refs #N` only. Use `Closes` / `Fixes` / `Resolves #N` only when the **full issue DoD** is met (not Phase A partial / multi-phase mid-stream).
+- ⊗ Write `Closes #N Phase A`, `only if`, `partial`, or other conditional English around a real closing keyword — GitHub ignores the condition and auto-closes (#3015 enterprize#29).
+- ! **Run `task pr:check-closing-keywords` before opening the PR (default mode `both` = FP #737 + intent #3015).** Offline: `--body-file` / `--commits-file`. Scans body and commits for closing-keyword tokens in negation / quotation / example / code-block contexts (FP) and for any unallowlisted real close (intent). When full DoD close is intentional, pass `--allow-close <N,M>` (CLI allowlist only — body trailers are not an authorization path). FP-only: `--mode fp`. Known-safe quoted tokens: `--allow-known-false-positives`. Recurrence stack: #167, #697 / #698, #401 / #700, #735 (class A), #3015 (class D enterprize#29).
 - ~ 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.
 
@@ -173,4 +175,4 @@ After exiting:
 - ⊗ Make out-of-scope fixes during Write -- this introduces scope creep that Diff will flag, forcing another iteration
 - ⊗ Ignore the iteration count -- more than 3 iterations usually indicates oscillating fixes or an unclear spec task
 - ⊗ Add a prohibition (`!` or `⊗`) without scanning the same file for conflicting softer-strength rules (`~`, `≉`) that reference the same term
-- ⊗ Skip `task pr:check-closing-keywords` (#737) before pushing a PR. The negation-context substring match is the Layer 0 (prevention) gate that prevents the recurring auto-close of umbrella / staying-OPEN issues observed in #697 (closed #642), #401 (closed #642), #700 (closed #233), and #735 (closed #734) -- each incident required manual reopen and downstream cleanup. The lint's three-state exit (0 clean / 1 hits found / 2 config error) MUST be treated as a hard refusal: rewrite the PR body / commit messages until clean, OR pass `--allow-known-false-positives` ONLY for legitimately-quoted occurrences (test fixtures, documentation that discusses the trigger token literally). See `skills/deft-directive-swarm/SKILL.md` Phase 6 Step 1 for the corresponding Layer 3 (recovery) `pr:check-protected-issues` rule (#701)
+- ⊗ Skip `task pr:check-closing-keywords` (#737) before pushing a PR. Intent mode (#3015) also refuses bare/conditional real `Closes #N` without `--allow-close`. The negation-context substring match is the Layer 0 (prevention) gate that prevents the recurring auto-close of umbrella / staying-OPEN issues observed in #697 (closed #642), #401 (closed #642), #700 (closed #233), and #735 (closed #734) -- each incident required manual reopen and downstream cleanup. The lint's three-state exit (0 clean / 1 hits found / 2 config error) MUST be treated as a hard refusal: rewrite the PR body / commit messages until clean, OR pass `--allow-known-false-positives` ONLY for legitimately-quoted occurrences (test fixtures, documentation that discusses the trigger token literally). See `skills/deft-directive-swarm/SKILL.md` Phase 6 Step 1 for the corresponding Layer 3 (recovery) `pr:check-protected-issues` rule (#701)

package/skills/deft-directive-review-cycle/SKILL.md

@@ -55,7 +55,7 @@ On repos with `.deft/core/` installed, **PR shepherding intent** routes here --
 On OpenClaw hosts with Directive installed (`.deft/core/` or equivalent content deposit), **babysit / shepherd / watch** intent likewise routes here -- not host-local freestyle poll loops and not OpenClaw `cron` alone.
 
 - ! When the OpenClaw tool surface exposes `sessions_spawn`, Approach 1 is the **default** babysit path: spawn a background review-monitor via `sessions_spawn` (register with `--platform-primitive sessions_spawn` or the alias `openclaw-sessions-spawn`).
-- ! Prefer a **visible** Control UI subagent when OpenClaw Control UI is the operator control plane so humans can inspect the monitor.
+- ! Prefer a **visible** Control UI subagent (`visible:true` when the tool surface allows) when OpenClaw Control UI is the operator control plane so humans can inspect the monitor (#3044; invisible empty settles are higher FC04 residual risk).
 - ! Long review-monitor ownership (>~3 min) MUST NOT block the parent OpenClaw session — background `sessions_spawn` + parent yield; same Gap D rule as Cursor/Grok Build (#1880).
 - ! Prefer deep-think gates inside the monitor via the dual-invoke probe order (#2893): `deft pr:watch` / `deft pr:merge-ready` first, then `task deft:pr:watch` when the Taskfile include is present, then the #2878 gh-only fallback — bare `task pr:watch` is not the consumer form.
 - ⊗ Treat OpenClaw `cron` (or any host scheduler alone) as Approach 1. Cron/timer re-invocation is Approach 2 only when `sessions_spawn` is unavailable.
@@ -362,7 +362,7 @@ Remediation:
 
 ! **Heartbeat contract for Cursor pollers (#1877 / #1166 / #2876):** OpenClaw sessions_spawn pollers share this contract. A Cursor `Task` or OpenClaw `sessions_spawn` review-monitor poller whose loop runs > ~3 min MUST honour the sub-agent heartbeat contract (`docs/subagent-heartbeat.md`), same as the `spawn_subagent` path — emit periodic progress so the parent can distinguish a live poller from a hung one.
 
-~ **Visible Control UI (OpenClaw):** When OpenClaw Control UI is the operator control plane, SHOULD spawn the review-monitor as a **visible** subagent so humans can inspect progress without attaching to the parent session.
+~ **Visible Control UI (OpenClaw / #3044):** When OpenClaw Control UI is the operator control plane, SHOULD spawn the review-monitor with `visible:true` when the tool surface allows so humans can inspect progress without attaching to the parent session; invisible empty settles are higher FC04 residual risk.
 
 ! When the platform descriptor indicates Tier 1 (sub-agent support), spawn a review-monitor sub-agent using the primitive matching the descriptor:
 
@@ -374,6 +374,51 @@ Remediation:
 
 ⊗ Use OpenClaw `cron` alone as Approach 1 when `sessions_spawn` is available — cron is Approach 2 scheduler fallback only (#2876).
 
+### Empty announce ≠ done (parent DoD) (#3044 / FC04 residual)
+
+! When a review-monitor settle arrives with **empty body**, **missing `STATUS:` line**, or **status unknown** (including host `(no output)` / empty `subagent_announce`):
+
+1. ! The parent MUST run **same-turn ground truth** before any DONE / CLEAN / merge-ready claim: at least `gh pr view <N>` (or REST `pulls/<N>`), `gh pr checks <N>`, and current HEAD SHA (`gh api repos/<owner>/<repo>/pulls/<N> -q .head.sha`).
+2. ! Classify the settle as **FC04 residual** (empty babysit ≠ done) until ground truth shows a terminal merge/close outcome **or** an explicit structured `BLOCKED` / `FAILED` handback.
+3. ⊗ Treat empty / unknown settle as `DONE`, `CLEAN`, merge-ready, or batch-complete.
+4. ⊗ Spawn a second review-monitor solely because the first settle was empty/unknown without completing the ground-truth batch first (#3044 dual-lease recurrence).
+
+~ Recurrence: enterprize PR #43 (2026-08-02) — first monitor polled live, host settled empty/unknown; parent spawned a second same-`taskName` monitor; dual lease collision while PR stayed open. See also `meta/lessons.md` and FC04 / growth friction R1 + R10.
+
+### Single review-monitor lease (#3044 / #2814)
+
+! **One sticky lease per PR:** ownership is the single sticky GitHub PR comment `<!-- deft:review-owner -->` (or the dual-invoke `review-monitor:register` form that writes it). Parallel ownership is forbidden.
+
+! **Pre-spawn check:** before launching another Approach 1 review-monitor (`sessions_spawn`, `spawn_subagent`, Cursor `Task`, `start_agent`):
+
+1. ! Read the sticky lease (dual-invoke `verify:review-monitor` when available, else `gh api` issues comments for `<!-- deft:review-owner -->`).
+2. ! List active same-PR / same-`taskName` subagents when the host exposes that surface (OpenClaw `subagents list` or equivalent).
+3. ⊗ Spawn a second monitor while a prior owner is **running**.
+4. ⊗ Spawn a second monitor when the last settle was **empty/unknown** and ground truth has **not** shown a terminal merge/close (or explicit structured handback that releases ownership).
+5. ! If the prior owner is **dead** (liveness fail / `REDISPATCH_OK` / `verify:subagent-alive` exit 1) and the PR is still open: spawn **one** replacement monitor and re-claim the lease with **`--force`** (CLI: `deft review-monitor:register --pr <N> --monitor-agent-id <id> --force` / task: `task review-monitor:register -- --pr <N> --monitor-agent-id <id> --force`, or host equivalent force takeover) so a non-expired foreign lease does not block replacement — then **update** the sticky lease comment to the new owner. Never silent dual ownership.
+6. ! On register conflict when the prior owner is **still alive**: attach to the existing owner or stop — do not parallel-fix.
+7. ⊗ Refuse replacement of a dead owner solely because the 30-minute lease has not expired without attempting force takeover (#3044).
+
+### Required non-empty monitor handback (#3044)
+
+! Approach 1 review-monitor prompts (including `templates/swarm-greptile-poller-prompt.md` and any host-filled spawn prompt) MUST require a **non-empty** final handback with these fields:
+
+```text
+STATUS: DONE|BLOCKED|FAILED
+HEAD: <sha>
+CHECKS: <summary>
+MERGE: <url|error|n/a>
+ISSUE: <closed|open|n/a>
+NOTES: <short>
+```
+
+⊗ Empty final assistant message from a review-monitor.
+⊗ Parent treating a settle that lacks `STATUS:` as success.
+
+~ **Visible Control UI risk (#3044):** When OpenClaw Control UI is the operator plane, prefer `visible:true` on the review-monitor spawn; invisible empty settles are higher risk for FC04 misclassification. Cross-link: `skills/deft-directive-swarm/references/host-openclaw.md` Babysit / review-monitor residual.
+
+
+
 **Approach 2 (fallback -- no sub-agent primitive for the descriptor):**
 
 ! When the platform descriptor indicates no sub-agent orchestration (or the primitive is unavailable), use discrete tool calls with a yield between checks. For `grok-build` / spawn_subagent descriptor this path is normally avoided in favor of Approach 1; it exists for pure interactive or limited runtimes.
@@ -566,3 +611,6 @@ task lifecycle:event -- emit plan:approved \
 - ⊗ Activate Approach 3 (blocking `Start-Sleep` loop) without first warning the user that it will lock the conversation pane and receiving confirmation
 - ⊗ Exit the review loop on a Greptile confidence number alone while the check run is non-terminal -- a confidence score is NOT a verdict without a terminal check-run (`completed` + `{success, neutral}`) AND a HEAD-matching `Last reviewed commit:` completion marker (#1259)
 - ⊗ Call `gh pr merge` on cached/earlier review state without an immediately-preceding pre-merge re-poll that re-satisfies the Step 6 fail-closed all-of (#1259)
+- ⊗ Treat empty/unknown review-monitor settle as DONE/CLEAN/merge-ready without same-turn ground truth (#3044 / FC04 residual)
+- ⊗ Spawn a second review-monitor while prior owner is running or last settle was empty/unknown without terminal ground truth (#3044)
+- ⊗ Accept empty review-monitor final message missing STATUS/HEAD/CHECKS/MERGE handback (#3044)

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

@@ -23,6 +23,7 @@ Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
 - User says "set up deft", "configure deft", or "bootstrap my project"
 - User asks to create USER.md, PROJECT-DEFINITION.xbrief.json, or a specification
 - User clones a deft-enabled repo for the first time with no config
+- User says "revisit experimental rules", "toggle experimental meta", "enable SOUL", "disable morals", or wants to change Experimental Rules after bootstrap (#46)
 
 ## Opt-out flag (`.no-deft-directive`) (#2926)
 
@@ -194,12 +195,28 @@ VBA (Excel macros), VHDL, Visual Basic (.NET), Zig, 6502-DASM
 2. ! If `deft_version` is present but **differs from the current framework version** (0.20.0): check whether any expected fields are missing from the USER.md
 3. ! If fields are missing: query the user for each missing field individually -- do NOT re-run the full Phase 1 interview
 4. ! After completing any field queries (even if none were needed), write the current `deft_version` (0.20.0) to USER.md
-5. ~ If `deft_version` matches the current version and all expected fields are present: no action needed (USER.md is fresh)
+5. ~ If `deft_version` matches the current version and all expected fields are present: USER.md is fresh — do **not** re-run Phase 1. ! Still offer the **Returning-user re-entry** menu below so the operator can revisit Experimental Rules or continue to Phase 2 without a full re-interview (#46).
 
 Expected USER.md fields: **Name**, **Custom Rules**, **Default Strategy**, and optionally **Coverage** and **Experimental Rules**.
 
 ⊗ Re-run the full Phase 1 interview when only individual fields are missing from a stale USER.md -- query missing fields individually instead.
 
+### Returning-user re-entry (#46)
+
+! When USER.md already exists (fresh or after individual missing-field fill), present a deterministic numbered menu before assuming Phase 1 is "done and silent":
+
+> "USER.md is in place. What next?"
+> 1. Continue to Phase 2 (project configuration) ★ (recommended when project config is still missing)
+> 2. **Revisit experimental rules** — enable/disable SOUL / morals / code-field without hand-editing schema
+> 3. Not now (exit setup)
+> 4. Discuss
+> 5. Back
+
+- ! Final two numbered options MUST be `Discuss` and `Back` per [`../../contracts/deterministic-questions.md`](../../contracts/deterministic-questions.md)
+- ! On option 2, enter **Revisit experimental rules** (next section) — not a full Phase 1 re-interview
+- ⊗ Silently skip past a complete USER.md with no re-entry offer when the operator entered setup (or asked to configure preferences)
+- ⊗ Invent a `deft config` / `task config:*` verb family for this slice — setup skill re-entry is the product surface (#46)
+
 ### Interview Rules
 
 ! This phase follows the deterministic interview loop defined in `skills/deft-directive-interview/SKILL.md`. The core rules (one question per turn, numbered options with stated default, explicit "other" escape, depth gate, default acceptance, confirmation gate, structured handoff) apply here. Key points repeated for emphasis:
@@ -307,6 +324,89 @@ for project-scoped settings (strategy, coverage).
 
 ---
 
+## Revisit experimental rules (#46)
+
+**Goal:** Guided enable/disable of USER.md **Experimental Rules** entries that *reference* framework deposit meta files (`meta/SOUL.md`, `meta/morals.md`, `meta/code-field.md`). This is a post-bootstrap return path — not Phase 1 bootstrap, not a general preferences UI, and not an editor for framework meta file bodies.
+
+### When to enter
+
+- Returning-user re-entry option **Revisit experimental rules**
+- Direct user ask: "revisit experimental rules", "toggle experimental meta", "turn on SOUL", "disable code-field", etc.
+- USER.md exists and is complete enough to edit (Name present); missing non-meta fields still use Freshness Detection individual queries first
+
+### Out of scope
+
+- ⊗ General preferences UI / rewriting Personal or Defaults sections as part of this path
+- ⊗ Editing framework `meta/*.md` content (deposit owns SOUL / morals / code-field bodies; `directive update` refreshes deposit)
+- ⊗ Deposit layout changes
+- ⊗ Inventing a full `deft config` mega-surface or new `task config:*` verb family for this slice
+- ⊗ Re-building USER.md bootstrap / non-overwrite semantics
+- ⊗ Treating Experimental Rules lines as project-local copies of meta files — they are **references** only
+
+### Flow
+
+! **Each message MUST contain exactly ONE question** (same interview rule as Phase 1).
+
+1. ! Resolve USER.md via Platform Detection (`$DEFT_USER_PATH` → platform path). Read the file as **UTF-8**.
+2. ! Parse current Experimental Rules state (on/off) for the three paths:
+   - `meta/SOUL.md`
+   - `meta/morals.md`
+   - `meta/code-field.md`
+   - Detection: any line containing that path counts as **on** (custom wording still counts).
+3. ! Show a **current state** summary (table or short list), for example:
+
+   | Entry | State | Role |
+   |-------|-------|------|
+   | SOUL.md | on/off | Results-first agent persona |
+   | morals.md | on/off | Epistemic honesty |
+   | code-field.md | on/off | Pre-code assumption protocol |
+
+4. ! Ask which entry to change with a deterministic numbered menu (one question). Options MUST include each of the three entries as toggle targets, plus **Done (save)** / **Done (discard)**, and final two options `Discuss` and `Back`:
+
+   > "Toggle which experimental meta entry? (current state shown above)"
+   > 1. SOUL.md — currently {on|off}
+   > 2. morals.md — currently {on|off}
+   > 3. code-field.md — currently {on|off}
+   > 4. Done — save changes
+   > 5. Done — discard changes
+   > 6. Discuss
+   > 7. Back
+
+5. ! When the user picks an entry (1–3), optionally show the short Phase 1 explainer (steps **5a–5c** copy below), then confirm the new on/off value with a Y/n or numbered keep/flip menu. Update the **in-memory** desired state; do not write yet. Return to the toggle menu (step 4) until Done.
+6. ! On **Done — save**: show a confirmation summary of the three final on/off values and require explicit affirmative (`yes` / `confirmed` / `approve`) before write — same Post-Interview Confirmation Gate strictness.
+7. ! On **Done — discard** or **Back** without save: leave USER.md unchanged and return to the Returning-user re-entry menu (or exit if invoked directly).
+
+### Explainers (reuse Phase 1 steps 5a–5c)
+
+- **SOUL.md** — Results-first agent persona (inspired by Winston Wolf). Enforces assess-before-acting, finish-what-you-start, right-tool-for-the-job, and play-the-long-game. Keeps the AI decisive and concise. Includes a named persona ('Vinston') — drop if you prefer to define your own agent personality.
+- **morals.md** — Epistemic honesty rules. No presenting speculation as fact, label unverified claims, self-correct when wrong. Foundational trust rules for any AI agent. Strongly recommended.
+- **code-field.md** — Pre-code assumption protocol. Requires stating assumptions and naming failure modes before writing a single line. Fights the 'it compiles, ship it' instinct. Based on NeoVertex1 context-field.
+
+### Safe write rules (non-clobber)
+
+! When persisting toggles to USER.md:
+
+1. ! Write **UTF-8** (no BOM). Create parent directories only if the resolved path's parent is missing — never relocate USER.md.
+2. ! Change **only** the `## Experimental Rules` section (add the section if enabling when absent; remove the section when all three are off and no custom bullets remain).
+3. ! Canonical enable lines (match Phase 1 template):
+   - `- ! Use meta/SOUL.md for strategic context and purpose-driven guidance`
+   - `- ! Use meta/morals.md for ethical AI development principles`
+   - `- ~ Use meta/code-field.md for advanced architecture patterns`
+4. ! Disable = remove lines that mention that path. Preserve any **custom** non-meta bullets under Experimental Rules.
+5. ! **Personal** and **Defaults** section bodies MUST remain byte-identical to the pre-write file (non-clobber).
+6. ~ Prefer the pure helper `applyExperimentalRulesState` / `setExperimentalRule` from `@deftai/directive-core` `userConfig` (`packages/core/src/user-config/experimental-rules.ts`) when the package is importable (framework checkout, tests, or a thin local script). When editing by hand as an agent, apply the same rules: section-only edit, UTF-8, path-based match, canonical enable lines.
+7. ! After write, re-read USER.md and show the final on/off state to the user.
+
+⊗ Rewrite the whole USER.md from the Phase 1 template when only Experimental Rules changed
+⊗ Clobber or reformat **Personal** / **Defaults** content while toggling experimental meta
+⊗ Hand-edit framework `meta/SOUL.md`, `meta/morals.md`, or `meta/code-field.md` bodies as part of this path
+⊗ Invent `deft config` / `task config:experimental-*` for this product slice when setup re-entry suffices
+
+### Then
+
+- ! After a successful save (or discard), re-offer the Returning-user re-entry menu (Continue to Phase 2 / Revisit again / Exit / Discuss / Back) unless the user asked only for the toggle and is done.
+- ~ If Phase 2 is already complete, prefer Exit over Continue unless the user wants project reconfiguration.
+
 ## Phase 2 — Project Configuration (PROJECT-DEFINITION.xbrief.json)
 
 **Goal:** Project-specific configuration — tech stack, type, quality standards — written as a xBRIEF file at `./xbrief/PROJECT-DEFINITION.xbrief.json`.
@@ -741,3 +841,6 @@ Per [strategies/interview.md](../../strategies/interview.md#interview-rules-shar
 - ⊗ Present choices through a host UI that replaces the canonical numbers with alphabetic affordances or unlabeled buttons
 - ⊗ Resolve paths relative to the skill file, AGENTS.md, or framework directory instead of the user's pwd at skill entry
 - ⊗ Generate an authoritative PRD.md — PRD.md is a read-only export via `task prd:render`, never a source of truth
+- ⊗ Skip the Returning-user re-entry / Revisit experimental rules path when USER.md exists and the operator entered setup to change experimental meta (#46)
+- ⊗ Clobber Personal or Defaults while toggling Experimental Rules (#46)
+- ⊗ Invent a full `deft config` verb family for experimental meta when setup re-entry suffices (#46)

package/skills/deft-directive-swarm/references/core-ops.md

@@ -92,6 +92,7 @@ CONSTRAINTS:
 
 ## Anti-Patterns
 
+- ⊗ Parent conversation implements or babysits product fix/CI loops for **through merge** / **drive-to: merge-ready** story work when background subagent/worktree dispatch is available — even if cohort size is 1; use the swarm/solo-worker launch path (#3032 / #1880 Gap C)
 - ⊗ Start prompts with context or description instead of an imperative TASK directive
 - ⊗ Use `--mcp` with Warp MCP server UUIDs from standalone (non-Warp) terminals
 - ⊗ Assign overlapping files to multiple agents

package/skills/deft-directive-swarm/references/core-phase-0.md

@@ -4,6 +4,12 @@
 
 ! Before assigning work to agents, build the cohort from the triage queue (queue-driven per #1142 / N2; see Step 0 below), then read project state and plan allocation against the activated cohort.
 
+### Through-merge / N=1 still uses the launch path (#3032)
+
+! When operator intent is **through merge**, **drive to merge**, **land/ship issue**, or explicit **drive-to: merge-ready** for story work, the parent (monitor) conversation MUST NOT implement product code or own the implementation PR as the leaf. Parent MUST run this skill's launch path: worktree isolation when available, worker envelope with `drive-to: merge-ready`, xBRIEF preflight, pre-pr + review-cycle, then merge/`scope:complete` per #1880 Gap C.
+! **Cohort size N=1 is still a cohort for dispatch.** Solo through-merge uses the same swarm/solo-worker launch path as multi-story (`dispatch_kind: solo` or a one-story swarm-cohort). Do not treat "only one issue" as permission for the parent to code.
+⊗ Parent implements, babysits product fix loops, or skips worktree + worker dispatch for through-merge / drive-to:merge-ready work when background subagent/worktree dispatch is available (#3032).
+
 ### Headless cohort fast-path: low-ceremony launch (C1 / #1387)
 
 ! When the operator supplies a **pre-approved cohort** via the **C1** `task swarm:launch` CLI, Phase 0 runs in headless / low-ceremony mode: the per-phase interactive approval gates (the Step 0c promote-fill prompts, the Step 0.5 lifecycle-bridge approval, and the Step 4/5 allocation approval) collapse into a SINGLE consent -- the `## Allocation context` token (#1378) carried in the dispatch envelope. The interactive promote-fill loop (Step 0a -- 0d below) is SKIPPED.

package/skills/deft-directive-swarm/references/host-openclaw.md

@@ -73,6 +73,16 @@ Package install alone does not put always-pins into `~/.openclaw/workspace/skill
 ! Babysit / PR shepherd on OpenClaw remains **Approach 1** via `sessions_spawn` (`skills/deft-directive-review-cycle/SKILL.md`). Cron alone is not Approach 1 (#2874 / #2876).
 ⊗ Regress babysit to main-session `gh` poll + cron when `sessions_spawn` is available.
 
+### Empty announce ≠ done + single lease residual (#3044)
+
+Skill residual of #2874 / #2876 (spawn routing fixed; post-spawn ownership still thrashed). Canonical MUST language lives in `skills/deft-directive-review-cycle/SKILL.md` (`### Empty announce ≠ done`, `### Single review-monitor lease`, `### Required non-empty monitor handback`).
+
+! On empty body / missing `STATUS:` / status-unknown review-monitor settle (`subagent_announce` with `(no output)` included): parent MUST same-turn ground truth (`gh pr view` + `gh pr checks` + HEAD) and MUST NOT treat the settle as DONE/CLEAN/merge-ready — **FC04 residual**.
+! One sticky `<!-- deft:review-owner -->` lease per PR. Pre-spawn: list active same-`taskName` / lease holder. ⊗ Second monitor while prior owner is running **or** last settle was empty/unknown without terminal ground truth. Dead owner + open PR → one replacement + lease update only.
+! Monitor handback MUST be non-empty with `STATUS` / `HEAD` / `CHECKS` / `MERGE` (see review-cycle skill + `templates/swarm-greptile-poller-prompt.md`).
+~ Prefer `visible:true` when Control UI is the operator plane; invisible empty settles raise FC04 misclassification risk.
+~ Recurrence: enterprize PR #43 (2026-08-02) dual-monitor + empty settle.
+
 ## Monitor / completion channel
 
 ! Completion is parent push / announce. Do not poll via Grok Build `get_command_or_subagent_output` or Cursor Task-complete semantics.

package/tasks/pr.yml

@@ -28,18 +28,17 @@ tasks:
         vars:
           ENGINE_CMD: 'pr-protected-issues {{.CLI_ARGS}}'
 
-  # pr:check-closing-keywords -- Layer 0 (prevention) closing-keyword
-  # negation-context lint introduced by #737. Refuses to push when the
-  # PR body or any commit message contains a closing-keyword token in a
-  # negation / quotation / example / code-block context. Pairs with the
-  # existing Layer 3 (recovery) ``pr:check-protected-issues`` (#701).
+  # pr:check-closing-keywords -- Layer 0 prevention (#737 FP + #3015 intent).
+  # Default --mode both: FP (negation/quote/example/code) + intent (any real
+  # Closes/Fixes/Resolves #N unless --allow-close N,M). Body trailers are not
+  # an authorization path. Pairs with Layer 3 ``pr:check-protected-issues`` (#701).
   #
   # Per ``conventions/task-caching.md`` (#574): NO ``sources:`` /
   # ``generates:`` because user-facing recovery flags (``--pr``,
-  # ``--body-file``, ``--commits-file``, ``--allow-known-false-positives``)
-  # MUST NOT be silently swallowed by go-task's incremental-build cache.
+  # ``--body-file``, ``--commits-file``, ``--allow-known-false-positives``,
+  # ``--allow-close``, ``--mode``) MUST NOT be silently swallowed by go-task cache.
   check-closing-keywords:
-    desc: "Scan PR body + commit messages for closing-keyword substrings in negation/quotation/example contexts that would trigger Layer 0 false-positive auto-closes (#737)"
+    desc: "Scan PR body + commits for closing-keyword FP contexts (#737) and unallowlisted real closes / intent mode (#3015 class D). Default --mode both."
     dir: '{{.USER_WORKING_DIR}}'
     deps: [":engine:_ts-build"]
     env:

package/tasks/roadmap.yml

@@ -12,7 +12,7 @@ vars:
 
 tasks:
   render:
-    desc: Render ROADMAP.md from pending/ and completed/ lifecycle folders
+    desc: Render ROADMAP.md from pending/ proposed/ active/ (forward) and capped completed/
     dir: '{{.USER_WORKING_DIR}}'
     deps:
       - task: :engine:_ts-build

package/tasks/scope.yml

@@ -36,7 +36,10 @@ vars:
 tasks:
 
   promote:
-    desc: "Promote a vBRIEF scope: proposed/ -> pending/ (status: pending)"
+    # Single: task scope:promote -- xbrief/proposed/<file>.xbrief.json
+    # Batch (#3011): task scope:promote -- --batch  (all proposed/)
+    #                task scope:promote -- --batch path1 path2 [--force]
+    desc: "Promote a vBRIEF scope: proposed/ -> pending/ (status: pending). Batch: --batch [paths...] (#3011)."
     dir: '{{.USER_WORKING_DIR}}'
     deps:
       - task: :engine:_ts-build

package/tasks/spec.yml

@@ -23,14 +23,17 @@ tasks:
           ENGINE_CMD: 'spec-validate --project-root "{{.USER_WORKING_DIR}}"'
 
   render:
-    desc: Render the specification artifact to SPECIFICATION.md
+    desc: >-
+      Render the specification artifact to a compact SPECIFICATION.md by default
+      (#1566: no completed lifecycle dump, no LegacyArtifacts). Opt in via
+      --include-scopes=current|all and --include-legacy-artifacts=on after --.
     dir: '{{.USER_WORKING_DIR}}'
     deps:
       - task: :engine:_ts-build
     cmds:
       - task: :engine:invoke
         vars:
-          ENGINE_CMD: 'spec-render --project-root "{{.USER_WORKING_DIR}}"'
+          ENGINE_CMD: 'spec-render --project-root "{{.USER_WORKING_DIR}}" {{.CLI_ARGS}}'
 
   pipeline:
     desc: Run full spec pipeline (validate then render)