@deftai/directive-content 0.94.0 → 0.96.0

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

@@ -89,14 +89,18 @@ Skill residual of #2874 / #2876 (spawn routing fixed; post-spawn ownership still
 ! Long pollers MUST honour on-disk heartbeats (`docs/subagent-heartbeat.md`, #1166).
 ! Pre-spawn verification and Duplicate-Agent rules in `references/core-phase-4.md` apply; resume the same OpenClaw session when possible rather than spawning a replacement on the same worktree.
 
-### Parent-monitor after `subagent_announce` (#2943)
+### Parent-monitor after `subagent_announce` (#2943 / hard-stop #3131)
 
-! When a leaf completion arrives via `subagent_announce` (parent-push completion), the parent’s **first response** MUST be **tool-first** or **yield** — never multi-sentence progress-only prose with zero tools:
+! When a leaf completion arrives via `subagent_announce` (parent-push completion), the parent’s **first response** MUST be one of:
 
-1. ! **Tool-first ground-truth batch** in the same turn: inspect worktrees / open PRs / xBRIEF state via `gh`, `git`, or file reads, **or**
-2. ! **`sessions_yield`** (or host yield) so the Control UI stays steerable without narrating unfinished work.
+1. ! **Tool-first ground-truth batch** in the same turn: inspect worktrees / open PRs / xBRIEF state via `gh`, `git`, or file reads, then one consolidate, **or**
+2. ! **`sessions_yield`** (or host yield / wait) so the Control UI stays steerable without narrating unfinished work, **or**
+3. ! **One short user answer** that is **not** a repeated progress line.
 
 ⊗ Open the first post-announce turn with multi-sentence status narration only (“Checking worktrees and open PRs next…”, “Two leaves look unfinished…”) and zero tool calls / yield — that is the #2943 text-repetition hang class (`stopReason: length` / abort with no tools).
+⊗ Emit **N>2** near-identical assistant sentences (or streaming text chunks) in one turn with no `tool_use` / yield — **FC14** illegal shape; **hard-stop** the turn (#3131). Soft skill prose is not sole mitigation.
+
+! **Machine check:** `evaluateParentTurnShape` in `@deftai/directive-core/parent-turn-shape` (`packages/core/src/parent-turn-shape/`). When `failClass` is `FC14` (or post-announce `progress-only-no-tool`), abort / force tool-or-yield. Operator recovery: [`../../docs/openclaw-agent-host.md`](../../docs/openclaw-agent-host.md) § Operator recovery — FC14.
 
 ! **Thin DONE = failed leaf (#2943):** completion text without PR URL / merge evidence (and not a structured `BLOCKED` / `FAILED` terminal per preamble §11) is a **failed leaf**, not success. After the ground-truth batch, re-dispatch or take over. ⊗ Treat thin DONE as shipped / success.
 

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

@@ -1,12 +1,15 @@
 ---
 name: deft-directive-sync
 description: >-
-  Session-start framework sync skill. Pulls latest deft submodule, validates
-  xBRIEF lifecycle structure, checks folder/status consistency, detects stale
-  origins (RFC D12), and summarizes changes.
+  Session-start framework sync and upgrade handoff. Refreshes deposit via npm
+  + directive/deft update, validates xBRIEF lifecycle, detects stale origins
+  (RFC D12), and finishes SCM release handoff in released | pr-open |
+  blocked:<reason> (#1604).
 triggers:
   - good morning
   - update deft
+  - update directive
+  - upgrade framework
   - update xbrief
   - sync frameworks
 ---
@@ -18,23 +21,34 @@ triggers:
 
 # Deft Directive Sync
 
-Session-start framework sync -- pull latest deft submodule updates, validate xBRIEF lifecycle structure, and detect stale origins.
+Session-start framework sync and upgrade handoff -- refresh the framework deposit via npm + `directive update` / `deft update`, validate xBRIEF lifecycle structure, detect stale origins (RFC D12), then finish SCM release handoff in a named terminal state (#1604).
 
-> **Canonical bootstrap / update path (#761 npm cutover):** Install and upgrade via npm: `npm i -g @deftai/directive` (install) or `npm i -g @deftai/directive@latest` (upgrade); Node >= 20 is required. For machines without Node, the frozen legacy Go installer (`deft-install` / platform-specific `install-*` from GitHub Releases) is a no-Node bootstrap bridge (#1912) -- migrate to npm once Node is available. After a session start the canonical `scripts/doctor.py --session --json` (`deft doctor` / `task doctor`) reports install + payload state and, when the manifest sha shows the payload is stale, recommends `npm i -g @deftai/directive@latest`. Legacy `run upgrade` / `task upgrade` are metadata-only acknowledgment (they do NOT replace the payload), and git-submodule / `task framework:doctor` paths are back-compat only -- the submodule sync in Phases 1-2 below is the legacy update flow, de-emphasized in UPGRADING.md / README. See UPGRADING.md and #761 / #1912.
+> **Canonical bootstrap / update path (#761 / #1604):** Install and upgrade via npm: `npm i -g @deftai/directive` (install) or `npm i -g @deftai/directive@latest` (upgrade); Node >= 20 is required. Then from the project root run `directive update` (or `deft update`) to refresh `.deft/core/`, optionally `deft migrate` for npm provenance, and `directive doctor` / `deft doctor` / `task doctor` to confirm deposit health. For machines without Node, the frozen legacy Go installer (`deft-install` / platform-specific `install-*` from GitHub Releases) is a no-Node bootstrap bridge (#1912) -- migrate to npm once Node is available. Legacy `run upgrade` / `task upgrade` are metadata-only acknowledgment (they do NOT replace the payload). **Git-submodule / `task framework:doctor` paths are back-compat only** -- Phases 1-2 below are the legacy update flow, de-emphasized in UPGRADING.md / README. Deposit success is not upgrade released; Phase 8 records one terminal state: `released` | `pr-open` | `blocked:<reason>`. See UPGRADING.md and #761 / #1912 / #1604.
 
 Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
 
 ## Platform Requirements
 
-! This skill requires **GitHub** as the SCM platform and the **GitHub CLI (`gh`)** to be installed and authenticated. Origin freshness checks (Phase 5) fetch issue data via `gh issue view`.
+! This skill requires **GitHub** as the SCM platform and the **GitHub CLI (`gh`)** to be installed and authenticated for origin freshness (Phase 5) and for the PR path of Phase 8 SCM release handoff. Origin freshness checks fetch issue data via REST-equivalent `gh` surfaces (prefer `gh api repos/<owner>/<repo>/issues/<N>` over GraphQL-heavy forms when under rate pressure; #954).
 
 ## When to Use
 
-- User says "good morning", "update deft", "update xbrief", or "sync frameworks"
+- User says "good morning", "update deft", "update directive", "upgrade framework", "update xbrief", or "sync frameworks"
 - Beginning of a new session where framework updates may be available
-- After a known upstream deft release
+- After a known upstream deft / `@deftai/directive` release
+- After a successful local deposit when the default branch still lacks the framework update
 
+## Missing CLI / PATH remediation
 
+! When `directive`, `deft`, or the global npm bin is missing from PATH (or `npm i -g @deftai/directive@latest` has not been run), surface actionable install remediation first:
+
+```bash
+npm i -g @deftai/directive@latest
+```
+
+(or the pnpm equivalent: `pnpm add -g @deftai/directive@latest`). Then re-run `directive update` / `deft update` and `directive doctor`.
+
+⊗ Send the operator to manual GitHub release-asset archaeology or Go installer discovery as the happy path when Node is available -- npm is the primary remediation (#761 / #1604).
 
 ## Session orientation — unmanaged header (#2065)
 
@@ -65,7 +79,7 @@ A project is **pre-cutover** if ANY of the following are true. This prose mirror
 
 ### Action on Detection
 
-! If pre-cutover state is detected, display the actionable migration message, then **skip Phases 1-6** and proceed directly to Phase 7 with the Document Model line set to "pre-v0.20 (legacy)":
+! If pre-cutover state is detected, display the actionable migration message, then **skip Phases 0-6** and proceed directly to Phase 7 with the Document Model line set to "pre-v0.20 (legacy)". Phase 8 still applies if a local migration/framework change must land on the default branch after the frozen migrator path:
 
 > "This project uses the pre-v0.20 document model. Current npm releases no longer ship in-product `task migrate:vbrief` (#2068). Follow UPGRADING.md § Frozen pre-v0.20 document-model migration: pin framework v0.59.0, install Python 3.11+ and uv, run `task migrate:vbrief` once from that payload, then upgrade to current npm."
 
@@ -88,12 +102,77 @@ A project is **pre-cutover** if ANY of the following are true. This prose mirror
 ⊗ Skip model state detection during sync -- always report the document model state.
 ⊗ Silently ignore pre-cutover artifacts -- the user must be informed with an actionable command to fix the state.
 
-## Phase 1 -- Pre-flight
+## Phase 0 -- Primary upgrade (npm deposit) (#761 / #1604)
+
+! Treat npm + `directive update` / `deft update` as the **primary** consumer upgrade path when an upgrade is authorized. Do not lead with submodule update when Node is available.
+
+### 0a: When mutation is authorized
+
+! **Mutating** engine install / deposit refresh is authorized only when at least one of:
+
+1. The operator used an **explicit upgrade** trigger: `update deft`, `update directive`, `upgrade framework`, or equivalent ("upgrade Directive", "run update").
+2. Doctor / payload-staleness already reports the deposit is **behind** and the operator confirmed the upgrade (or autonomous upgrade was pre-approved).
+3. CLI is **missing** from PATH -- then Missing CLI remediation may install the global package so doctor/update can run.
+
+! For routine session orientation triggers (`good morning`, `sync frameworks`, plain `update xbrief` without upgrade language):
+
+1. ! Run **read-only** checks: CLI present?, `directive doctor` / `deft doctor` / `task doctor` when available, structure validation (Phases 3+).
+2. ! If doctor reports a stale deposit or available upgrade, **report** the recommended command and ask for consent before mutating.
+3. ⊗ Run `npm i -g @deftai/directive@latest` or `directive update` / `deft update` on a routine "good morning" without staleness evidence **and** operator consent (or pre-approved autonomous upgrade).
+
+### 0b: Consumer worktree isolation before deposit
+
+! Before any mutating deposit that will be handed off in Phase 8:
+
+1. ! Run `git status --porcelain` at the **project root** (not only the legacy submodule).
+2. ! If the worktree or index has non-framework product changes (or any unexpected staged paths), **stop** and either:
+   - ask the operator to stash / commit product work first, or
+   - record `blocked:dirty-worktree` and skip deposit mutation,
+   - or, with explicit consent, isolate product changes (stash including index) so the deposit cannot mix with them.
+3. ! After deposit, stage **only** framework-managed paths for the upgrade commit (e.g. `.deft/core/`, managed AGENTS section, hooks, VERSION / marker files). Reconstruct a clean index if needed rather than `git add -A`.
+4. ⊗ Create a framework-only commit or PR from a mixed worktree/index that still carries product feature paths.
+
+### 0c: Engine + deposit (when authorized)
+
+1. ! Confirm the global CLI is available (`directive --version` or `deft --version`). If missing, run Missing CLI / PATH remediation above, then continue.
+2. ! Upgrade the global engine only when mutation is authorized (0a):
+
+```bash
+npm i -g @deftai/directive@latest
+```
+
+3. ! From the **project root**, after worktree isolation (0b), refresh the deposit:
+
+```bash
+directive update
+# or: deft update
+```
+
+4. ~ Optionally stamp npm provenance (idempotent): `directive migrate` / `deft migrate`.
+5. ! Verify deposit health:
+
+```bash
+directive doctor
+# or: deft doctor / task doctor
+```
+
+6. ! Record whether the working tree now has **framework-only** changes under `.deft/core/`, managed AGENTS section, hooks, or related managed files that need SCM release.
+
+### 0d: Framework-only change-set discipline
+
+! Keep upgrade commits/PRs **framework-only** -- do not mix product feature work into the same commit or PR as the deposit refresh.
+
+⊗ Treat a successful deposit alone as `released` -- the default branch must carry the update (or a PR must be open) before the operator goal is complete (#1604).
+⊗ Force a global CLI upgrade or deposit mutation on routine session sync without consent or staleness evidence.
+
+## Phase 1 -- Pre-flight (legacy submodule path)
+
+! **Legacy / back-compat only.** Run Phases 1-2 only when the consumer still uses a `deft/` git submodule layout and cannot use the npm deposit path. Prefer Phase 0 for all npm-managed installs.
 
 ! Check that the deft/ submodule working tree is clean before attempting any update.
 
 1. ! Run `git -C deft status --porcelain`
-2. ! If output is non-empty (dirty working tree): **stop** and ask user whether to stash (`git -C deft stash`) or abort the sync entirely. Do NOT proceed with a dirty submodule.
+2. ! If output is non-empty (dirty working tree): **stop** and ask user whether to stash (`git -C deft stash`) or abort the sync entirely. Do NOT proceed with a dirty submodule. Record terminal state `blocked:dirty-submodule` if the operator aborts.
 3. ! Record the current DEFT commit for later comparison:
    ```
    git -C deft log --oneline -1
@@ -103,7 +182,9 @@ A project is **pre-cutover** if ANY of the following are true. This prose mirror
    - Clean/dirty status
    - Confirmation that pre-flight passed (or the blocker if dirty)
 
-## Phase 2 -- Update DEFT Submodule
+## Phase 2 -- Update DEFT Submodule (legacy / back-compat)
+
+! **Legacy / back-compat only** -- not the primary consumer upgrade path (#1604). Submodule update does not replace Phase 0 for npm installs.
 
 1. ! Run the submodule update:
    ```
@@ -214,7 +295,7 @@ After structure validation, sync framework-level assets.
 
 ### 6a: Check AGENTS.md freshness
 
-~ Compare the project's `AGENTS.md` against the deft template (if a template exists in the updated `deft/` submodule):
+~ Compare the project's `AGENTS.md` against the deft template (if a template exists in the updated deposit / `.deft/core/` or legacy `deft/` submodule):
 
 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
@@ -230,7 +311,7 @@ After structure validation, sync framework-level assets.
 
 ### 6c: List new skills
 
-! Compare the `skills/` directory before and after the update:
+! Compare the `skills/` directory (or deposited `.deft/core/` skills) before and after the update:
 
 1. ! List any new skill directories added in the update
 2. ~ For each new skill, read its frontmatter `description` field and present a one-liner
@@ -282,29 +363,103 @@ Doc sprawl is a project-health concern, not just a human-experience one: a lean,
 
 ! Present a consolidated summary to the user covering:
 
-1. **DEFT version change**: old commit -> new commit (or "already up to date")
-2. **Structure validation**: lifecycle folders status (all present / missing folders listed)
-3. **PROJECT-DEFINITION status**: valid / missing / stale (with freshness details)
-4. **xBRIEF validation results**: pass/fail per file, with details on any failures
-5. **Lifecycle consistency**: all consistent / N mismatches found (with details)
-6. **Origin freshness**: N stale / N externally-closed / N current (with details)
-7. **Document Model**: pre-v0.20 (legacy) / v0.20+ (xBRIEF-centric) OK / v0.20+ with warnings (see Pre-Cutover Detection Guard)
-8. **AGENTS.md status**: current / has upstream changes / needs review
-9. **Codebase MAP status**: current / stale / absent / not configured (advisory)
-10. **New skills**: list any newly added skills with descriptions
+1. **Upgrade path used**: npm deposit (Phase 0) / legacy submodule (Phases 1-2) / already up to date
+2. **DEFT / deposit version change**: old version or commit -> new (or "already up to date")
+3. **Structure validation**: lifecycle folders status (all present / missing folders listed)
+4. **PROJECT-DEFINITION status**: valid / missing / stale (with freshness details)
+5. **xBRIEF validation results**: pass/fail per file, with details on any failures
+6. **Lifecycle consistency**: all consistent / N mismatches found (with details)
+7. **Origin freshness**: N stale / N externally-closed / N current (with details)
+8. **Document Model**: pre-v0.20 (legacy) / v0.20+ (xBRIEF-centric) OK / v0.20+ with warnings (see Pre-Cutover Detection Guard)
+9. **AGENTS.md status**: current / has upstream changes / needs review
+10. **Codebase MAP status**: current / stale / absent / not configured (advisory)
+11. **New skills**: list any newly added skills with descriptions
+12. **Pending SCM release**: whether framework-only changes still need commit/push/PR/merge (Phase 8)
 
-! Ask the user: "Shall I commit the submodule update?" -- do NOT auto-commit.
+! After a successful deposit (or submodule bump), **do not stop at the local change set**. Proceed to Phase 8 SCM release handoff. If there is nothing to release (already on default branch / no local framework delta), record terminal state `released` when the default branch already carries the current framework update; otherwise name the next release step.
+
+? For the legacy submodule path only, if a bump is ready and the operator has not yet approved a commit, ask: "Shall I commit the submodule update and continue SCM release handoff?" -- do NOT auto-commit without approval. Prefer message:
 
-? If the user confirms, commit with message:
 ```
 chore(deft): update deft submodule to <short-hash>
 ```
 
+For npm deposit changes, prefer a framework-only commit message such as:
+
+```
+chore(deft): refresh framework deposit to <version>
+```
+
+## Phase 8 -- SCM release handoff (#1604)
+
+! After a successful framework deposit (Phase 0) or legacy submodule bump (Phases 1-2), carry the update through consumer SCM release. Installer/update success is not upgrade released.
+
+! Record **exactly one** terminal state when this skill exits after a deposit-related run:
+
+| Terminal state | Meaning |
+| --- | --- |
+| `released` | Default branch carries the framework update (merged or committed directly under policy). |
+| `pr-open` | Framework-only branch pushed and PR opened; awaiting review/merge per policy. |
+| `blocked:<reason>` | Explicit blocker (examples: `blocked:dirty-worktree`, `blocked:auth`, `blocked:branch-protection`, `blocked:human-merge-gate`, `blocked:ci`, `blocked:operator-declined`). |
+
+### 8a: Policy detection
+
+1. ! Read consumer branch policy: `plan.policy.allowDirectCommitsToMaster`, `plan.policy.requireHumanMerge`, and any known branch-protection / default-branch rules (`deft policy:show` when available).
+2. ! Classify the path:
+   - **PR path (default when protected or human-merge):** branch protection enabled, or `requireHumanMerge` is true, or direct commits to default branch are disallowed.
+   - **Direct-commit path:** `allowDirectCommitsToMaster` (or equivalent) is true **and** human-merge is not required **and** branch protection does not forbid the commit.
+
+### 8b: PR-oriented path (branch-protected / human-merge)
+
+1. ! With operator consent (or autonomous consent when the operator already approved upgrade handoff), create a **framework-only** branch (e.g. `chore/deft-update-<version>`), commit framework deposit files only, push, and open a PR targeting the default branch.
+2. ! Stop at terminal state **`pr-open`** once the PR URL is available -- unless policy explicitly allows bot merge **and** the operator directed merge.
+3. ⊗ Auto-merge past `requireHumanMerge` / the human merge gate (#1193). Agents may open PRs; they do not merge when policy forbids it.
+4. ⊗ Claim `released` when the PR is only open or only locally committed.
+
+### 8c: Direct-commit-enabled path
+
+1. ! Present an **explicit** default-branch path with confirmation (do not silently commit to master/main).
+2. ! On confirmation, commit framework-only changes on the default branch (or merge the framework branch) and push so the default branch carries the update.
+3. ! Record terminal state **`released`** only after the default branch ref includes the framework update.
+
+### 8d: Stop-after-commit is a failure mode
+
+! A local framework-only commit without push/PR/merge **and** without naming the next release step is a **failure mode** of this skill (#1604 historical class).
+
+- ! If the workflow must pause after a local commit, name the next step explicitly (push + open PR, or confirm direct-commit + push) and record `blocked:<reason>` or continue until `pr-open` / `released`.
+- ⊗ End the skill at "local framework-only commit done" without a terminal state line.
+- ⊗ Report `released` when only a local commit exists and the default branch does not yet carry the update.
+
+### 8e: Terminal state line
+
+! End the skill output with a single machine-readable line operators and agents can grep:
+
+```text
+upgrade-handoff: released
+upgrade-handoff: pr-open
+upgrade-handoff: blocked:<reason>
+```
+
+Include the PR URL when state is `pr-open`, and the merge/default-branch SHA when state is `released`.
+
+### 8f: Framework-only path allowlist
+
+! When committing for handoff, include only framework deposit artifacts (managed `.deft/core/`, AGENTS managed section, hooks, VERSION/marker files, and other paths the deposit itself refreshed). Exclude product source, tests, and unrelated staged files. If isolation was used in 0b, restore the operator's product stash only **after** the framework commit is complete (or on a separate branch).
+
 ## Anti-Patterns
 
 - ⊗ Auto-commit submodule changes without user approval
+- ⊗ Auto-commit or auto-push framework deposit changes without the Phase 8 policy path and consent rules
+- ⊗ Stop after a local framework-only commit without naming the next release step or recording a terminal state (#1604)
+- ⊗ Claim terminal state `released` when the update is only local or only on an open PR
+- ⊗ Auto-merge when `requireHumanMerge` is true or branch protection forbids bot merge (#1193)
+- ⊗ Treat git submodule update as the primary consumer upgrade path when npm + `directive update` / `deft update` is available
+- ⊗ Send operators to manual GitHub release-asset archaeology when `npm i -g @deftai/directive@latest` is the correct remediation
 - ⊗ Overwrite project-level `./xbrief/*.xbrief.json` files -- those are project data
 - ⊗ Skip the pre-flight dirty check -- a dirty submodule can cause merge conflicts or data loss
 - ⊗ Include a separate fetch of the xBRIEF schema from upstream deftai/xBRIEF -- that is a CI concern (see #128), not a user sync task
 - ⊗ Auto-move xBRIEFs to fix folder/status mismatches -- report only; never auto-fix
 - ⊗ Auto-update xBRIEFs based on origin freshness -- report only; user decides during refinement
+- ⊗ Mix product feature work into a framework-only upgrade commit or PR
+- ⊗ Force `npm i -g @deftai/directive@latest` or deposit mutation on routine session sync without staleness evidence and operator consent
+- ⊗ Run Phase 8 framework-only commit from a mixed product+framework worktree/index without isolation

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

@@ -78,7 +78,7 @@ Directive does not guess your mix: **ordered plan** (`task plan-sequence:*`) whe
 
 ! Walk per-item decisions through the canonical `task triage:*` verbs (tasks own audit-log append / schema / `xbrief/proposed/` write).
 
-! **Operator brief (same turn as menu) (#2890):** Before every per-item decision menu, present an operator brief in the **same operator-visible message/surface** as the menu, containing at least: issue `#N` + title + link; labels (or explicit none); 2–5 line problem/context summary; AC bullets or explicit "thin body / no AC"; agent **lean** + one-line why (Accept / Defer / Reject / Needs-AC / …). ~ Prefer `task triage:show --format=operator <N>` as the brief backbone; agent still owns lean. ⊗ Menu-only or chip-only Phase 3 turns without that brief. ⊗ Brief-only turn followed by a later chip/menu-only turn that does not restate the brief.
+! **Operator brief (same turn as menu) (#2890 / #3116):** Before every per-item decision menu, present an operator brief in the **same operator-visible message/surface** as the menu, containing at least: **URL-first** lead (canonical issue URL as the first line for that item, or `#N title` + URL); labels (or explicit none); **current-state validity** (`still-open` | `partial` | `likely-shipped` | `needs-re-scope`) + one-line evidence (linked closed PR, code path, or "no evidence of fix"); 2–5 line problem/context summary; AC bullets or explicit "thin body / no AC"; agent **lean** + one-line why (Accept / Defer / Reject / Needs-AC / …). ~ Prefer `task triage:show --format=operator <N>` as the brief backbone (URL-first + validity placeholder); agent still owns validity verdict and lean. ⊗ Menu-only or chip-only Phase 3 turns without that brief. ⊗ Brief-only turn followed by a later chip/menu-only turn that does not restate the brief. ⊗ Body-only summary without validity check against current master, closed children, or linked PRs.
 
 ! **Host structured-question adapter:** On chips / `ask_user` / similar UIs (e.g. OpenClaw `ask_user`), keep the prose brief in chat; structured options are **actions only** (Accept / Defer / Reject / Needs-AC / Mark duplicate / Discuss / Back). Option labels ≉ substitute for the brief.
 
@@ -86,11 +86,11 @@ For each candidate, render the canonical numbered action menu and dispatch:
 
 ```
 What would you like to do with this candidate?
-  1. Accept         -- `task triage:accept <N>`
-  2. Reject         -- `task triage:reject <N>`
-  3. Defer          -- `task triage:defer <N> [--resume-on <event>]`
-  4. Needs-AC       -- `task triage:needs-ac <N>`
-  5. Mark duplicate -- `task triage:mark-duplicate <N> <of-issue>`
+  1. Accept         -- `task triage:accept -- --issue <N> --repo OWNER/NAME`
+  2. Reject         -- `task triage:reject -- --issue <N> --repo OWNER/NAME`
+  3. Defer          -- `task triage:defer -- --issue <N> --repo OWNER/NAME [--resume-on <event>]`
+  4. Needs-AC       -- `task triage:needs-ac -- --issue <N> --repo OWNER/NAME`
+  5. Mark duplicate -- `task triage:mark-duplicate -- --issue <N> --of <of-issue> --repo OWNER/NAME`
   6. Discuss
   7. Back
 ```
@@ -100,6 +100,7 @@ What would you like to do with this candidate?
 - ! On `Back`, un-buffer prior selection and re-render its action menu only before a `task triage:*` dispatch; after dispatch use `task triage:reset`.
 - ~ Bulk: `task triage:bulk-{accept,reject,defer,needs-ac}`; results still flow through the audit log.
 - ⊗ Write to `xbrief/proposed/` directly -- only `task triage:accept` is authorised.
+- ~ **Accept → pending chain (#1136):** `task triage:accept` ingests into **`proposed/`**. To stage into WIP (`pending/`) in one operator action: `task triage:accept -- --issue <N> --repo OWNER/NAME --auto-promote` (WIP cap still enforced; use `--force` on the accept command for WIP override). Separately, promote an already-accepted proposed scope by issue: `task scope:promote -- --from-issue=<N> [--repo OWNER/NAME]` (gates on latest `candidates.jsonl` decision = `accept`; non-accept refuses unless `--force-no-cache`; no decision soft-warns, `--strict` fails). Path-based `task scope:promote -- <file>` remains ungated for refinement scaffolds.
 
 ## Phase 4 -- Audit
 
@@ -116,11 +117,23 @@ What would you like to do with this candidate?
 
 ! Undo via `task triage:reset <N>` (Layer 5; history never deleted). ⊗ Edit/delete `xbrief/.eval/candidates.jsonl` to "undo".
 
+## Quarterly closed-entry archive vs TTL prune (#1137)
+
+Live walkers (`triage:queue`, scope-drift, bootstrap) scan `.deft-cache/github-issue/`. Closed issues can linger forever. Operators may run an **explicit, reversible** archive pass — never auto on bootstrap/session/check.
+
+| Tool | What it does |
+| --- | --- |
+| `task triage:cache-archive` | Move **closed** + aged (default 30d) entries → `.deft-cache/archived/github-issue/...` with `archive-meta.json`. Skips open lifecycle scopes. `--dry-run` first. |
+| `task triage:archive-list` / `task triage:restore-from-archive` | List / move back to live. |
+| `task cache:prune` | **TTL hard-delete** by `expires_at` — **not** reversible; **not** closed-state archive. |
+
+! Prefer archive for closed clutter; use prune only for expired TTL / cap eviction. ⊗ Wire archive into session-start or `task check`.
+
 ## Anti-Patterns
 
 - ⊗ Recommend work without `task triage:queue` (#1149).
 - ⊗ Conclude "nothing to do" from folder scans or live GitHub alone (#2576).
-- ⊗ Stale-cache walk; reimplement audit/`proposed/` writes; treat defer/needs-ac as terminal; edit candidates.jsonl; menu-only Phase 3 without operator brief (#2890).
+- ⊗ Stale-cache walk; reimplement audit/`proposed/` writes; treat defer/needs-ac as terminal; edit candidates.jsonl; menu-only Phase 3 without operator brief (#2890); body-only brief without URL-first or current-state validity (#3116).
 
 ## EXIT
 
@@ -128,5 +141,5 @@ What would you like to do with this candidate?
 
 ## References
 
-- #1119 D6; #1128 D11 (`triage:queue` / `show` / `audit`); #2890 Phase 3 operator brief; #1122 / #1123 / #1127 / #1129 / #1131
+- #1119 D6; #1128 D11 (`triage:queue` / `show` / `audit`); #2890 Phase 3 operator brief; #3116 validity + URL-first; #1122 / #1123 / #1127 / #1129 / #1131; #1136 (`scope:promote --from-issue` / `triage:accept --auto-promote`)
 - Siblings: `deft-directive-refinement`, `deft-directive-swarm`, `deft-directive-sync`

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

@@ -14,7 +14,6 @@ triggers:
   - compress into xbrief
   - xbrief:create
   - xbrief:verify
-
 ---
 <!-- AUTO-GENERATED by task packs:render -- DO NOT EDIT MANUALLY -->
 <!-- Purpose: rendered skill -->

package/tasks/cache.yml

@@ -77,3 +77,34 @@ tasks:
       - task: :engine:invoke
         vars:
           ENGINE_CMD: 'cache prune {{.CLI_ARGS}}'
+
+  # #1137 — reversible closed-entry archive (NOT TTL prune; never auto-wired)
+  archive-closed:
+    desc: "Reversible archive of closed github-issue cache entries (#1137). -- task triage:cache-archive -- [--dry-run] [--older-than-days 30] [--repo OWNER/NAME] [--json]"
+    dir: '{{.USER_WORKING_DIR}}'
+    deps:
+      - task: :engine:_ts-build
+    cmds:
+      - task: :engine:invoke
+        vars:
+          ENGINE_CMD: 'cache archive-closed --project-root "{{.USER_WORKING_DIR}}" {{.CLI_ARGS}}'
+
+  archive-list:
+    desc: "List archived github-issue cache entries (#1137). -- task triage:archive-list -- [--repo OWNER/NAME] [--format=json] [--since ISO] [--limit N]"
+    dir: '{{.USER_WORKING_DIR}}'
+    deps:
+      - task: :engine:_ts-build
+    cmds:
+      - task: :engine:invoke
+        vars:
+          ENGINE_CMD: 'cache archive-list --project-root "{{.USER_WORKING_DIR}}" {{.CLI_ARGS}}'
+
+  restore-from-archive:
+    desc: "Restore archived github-issue entry to live cache (#1137). -- task triage:restore-from-archive -- --issue N [--repo OWNER/NAME] [--force]"
+    dir: '{{.USER_WORKING_DIR}}'
+    deps:
+      - task: :engine:_ts-build
+    cmds:
+      - task: :engine:invoke
+        vars:
+          ENGINE_CMD: 'cache restore-from-archive --project-root "{{.USER_WORKING_DIR}}" {{.CLI_ARGS}}'

package/tasks/triage-classify.yml

@@ -22,7 +22,7 @@ vars:
 
 tasks:
   classify:
-    desc: "Inspect / validate plan.policy.triageAutoClassify[] + triageHoldMarkers[] (#1129 / D10). -- task triage:classify -- [--list | --validate]"
+    desc: "Inspect / validate triageAutoClassify + triageLabelMirror; Tier-1 SCM label mirror (#1129 / #1423). -- task triage:classify -- [--list | --validate | --mirror [--apply]]"
     internal: true
     deps: [":engine:_ts-build"]
     dir: '{{.USER_WORKING_DIR}}'

package/templates/agent-prompt-preamble.md

@@ -73,13 +73,13 @@ When the operator supplies an ordered plan (delivery sequence, cohort, checklist
 
 ## 2.6 Provider-neutral worker metadata (#1531)
 
-Heterogeneous swarm dispatch (#1531) assigns each worker a **dispatch provider** (the runtime primitive that launched the agent), a **worker role** (what the agent is allowed to do), and a **selected backend** or **routing policy** (how the harness maps that role to a concrete agent). These fields are provider-neutral: Composer-class coding agents, Grok Build (`spawn_subagent`), Cursor/cloud agents, OpenClaw (`sessions_spawn`, #2874 / #2879), and future adapters share the same contract.
+Heterogeneous swarm dispatch (#1531) assigns each worker a **dispatch provider** (the runtime primitive that launched the agent), a **worker role** (what the agent is allowed to do), and a **selected backend** or **routing policy** (how the harness maps that role to a concrete agent). These fields are provider-neutral: Composer-class coding agents, Grok Build (`spawn_subagent`), Cursor/cloud agents, Claude Code (`claude-code` / `claude-agent`, #3134), OpenClaw (`sessions_spawn`, #2874 / #2879), and future adapters share the same contract.
 
 ! Every intentional backend-routed dispatch MUST carry a separate `## Worker metadata` section in the dispatch envelope, placed AFTER `## Allocation context` and BEFORE the task body. This section is advisory metadata for the worker and for audit; it does NOT replace, extend, or reorder the five-field #1378 `## Allocation context` recognition contract above.
 
 When present, the section documents these fields in order:
 
-- `dispatch_provider`: the runtime primitive that launched this worker -- e.g. `spawn_subagent`, `start_agent`, `sessions_spawn` (OpenClaw host; platform descriptor `openclaw` per #2874 / #2875), `cursor-composer`, `cursor-cloud-agent`, or a future adapter id. Names the harness surface, not the model.
+- `dispatch_provider`: the runtime primitive that launched this worker -- e.g. `spawn_subagent`, `start_agent`, `sessions_spawn` (OpenClaw host; platform descriptor `openclaw` per #2874 / #2875), `cursor-composer`, `cursor-cloud-agent`, `claude-code` (Claude Code host; register primitive `claude-agent` per #3134), or a future adapter id. Names the harness surface, not the model.
 - `worker_role`: the role boundary for this dispatch -- one of `leaf-implementation`, `orchestrator`, `review-monitor`, or `merge-release` (stable ids from `packages/core/src/swarm/routing.ts` `SWARM_WORKER_ROLES`). Tells the worker which preamble rules and skill surfaces apply.
 - `selected_backend`: the stable backend id from `plan.policy.swarmSubagentBackend` / `task policy:subagent-backends` (accepted set today: `composer`, `grok-build`, `cursor-cloud` only — see `KNOWN_SUBAGENT_BACKEND_IDS`) | null -- which catalogued **coding** backend the operator selected for this role. OpenClaw is a **host / dispatch_provider** (`sessions_spawn` / descriptor `openclaw`), not a `swarmSubagentBackend` enum value; do not write `selected_backend: openclaw` into policy (#2879 Greptile P1).
 - `routing_policy`: <path or reference to the operator's routing file / tiering policy> | null -- when backend selection is delegated to harness routing instead of a typed policy field, cite the policy handle here so postmortems can reconstruct the route. The canonical handle is the gitignored, per-machine `.deft/routing.local.json` (#1739), keyed by `(dispatch_provider, worker_role)`; set decisions with `task swarm:routing-set -- --role <role> (--model <slug> | --harness-default)`.
@@ -94,7 +94,7 @@ Populate `selected_backend` OR `routing_policy` (or both when the operator sets
 - `orchestrator`, `review-monitor`, or `merge-release` + explicit backend routing: at least one MUST be non-null so strong-tier audit traces stay reconstructable.
 - Any role on the harness-default agent with no tiering decision: both MAY be null; `dispatch_provider` and `worker_role` remain required.
 
-**Role-boundary expectations (all providers):** the same boundaries apply whether the worker runs on Composer, Grok Build, Cursor/cloud, OpenClaw, or a future adapter:
+**Role-boundary expectations (all providers):** the same boundaries apply whether the worker runs on Composer, Grok Build, Cursor/cloud, Claude Code, OpenClaw, or a future adapter:
 
 - ! `leaf-implementation` workers implement scoped xBRIEF work in their assigned worktree only -- gates (`task check`, file-scope audit, Greptile review cycle) are model-agnostic and MUST still pass.
 - ! `orchestrator`, `review-monitor`, and `merge-release` roles MUST run on strong or review-capable agents; dispatchers MUST NOT route these roles to cheap leaf backends.
@@ -547,11 +547,33 @@ Every worker MUST send a final status message before exiting its tool loop, rega
 
 ! **`review_cycle` evidence enum (#3090):** Handoffs, swarm finish messages, and L4 process claims MUST use only `done` | `in_progress:<pr>#<monitor_or_lease_ref>` | `skipped:<reason>` | `n/a`. Freeform `started` / `pending` / `initiated` is forbidden. L4 `status: pass` is illegal unless `review_cycle: done` (Step 6 fail-closed on HEAD) or `review_cycle: in_progress:…` with a verifiable sticky lease / parent-retained ownership. After a drive-to:merge-ready / babysit / shepherd claim, the same turn MUST end in Owner Continuity Gate A/B/C (monitor+lease, parent-retained next dual-source action, or explicit BLOCKED/FAILED finish) — never silent hold. Optional machine gate: `deft verify:l4-owner --pr <N>` / `task verify:l4-owner -- --pr <N>`. Full MUST language: `skills/deft-directive-review-cycle/SKILL.md` Owner Continuity Gate.
 
-! **Parent tool-first after leaf completion (#2943):** When a parent / monitor receives a leaf completion event (`subagent_announce`, parent-push, or host completion notify), its **first response** MUST be a **tool-first** ground-truth batch (`gh` / `git` / worktree or file status) **or** a host **yield** (`sessions_yield` on OpenClaw, or equivalent). ⊗ Multi-sentence progress-only first response with zero tools / yield — the OpenClaw text-repetition hang class (#2943).
+! **Bound proof for remote artifact claims / invented-done (#3120):** Handoff evidence MUST distinguish at least three axes and a binding state:
+
+| Axis / field | Meaning |
+|---|---|
+| **work** | Local changes (edits, tests, commits on the branch) |
+| **ship** | Pushed branch / PR exists on the forge |
+| **gate** | Checks / review verdict on the claimed HEAD |
+| **`proof_status`** | `bound` \| `unbound` \| `n/a-no-remote-claim` |
+
+- ! **`proof_status` enum:** `bound` (same-turn probes bind every remote claim) \| `unbound` (remote claims present without probes — illegal under `status: pass`) \| `n/a-no-remote-claim` (no PR URL / PR number / SHA / CI-green / review-score fields filled).
+- ! **`status: pass` is forbidden** when any remote artifact is claimed (PR URL/number, commit/HEAD SHA, CI green/success, review score) unless `proof_status` is `bound` **and** each claim has a same-turn probe (`command` + short raw `snippet` from that command's stdout). Unbound remote claims → **invalid evidence (fail)**, not pass-with-notes.
+- ! **Binding = probe-then-fill (MUST):** run `git` / forge probe first (`git rev-parse HEAD`, `gh api repos/<o>/<r>/pulls/<N>`, `task pr:watch -- <N> --one-shot`, checks API), then **copy** IDs/URLs/SHAs/scores from the probe JSON/text into the evidence block. ⊗ Fill PR/SHA/CI/review fields from recollection, narration, or prior-turn memory.
+- ! **Fail ranking:** **invented-done** (false or unbound remote artifacts under pass) is **stricter** than **empty-done** (pass with no work/ship/gate substance and no remote claims). Empty returns are incomplete; invented complete returns are worse and MUST fail closed.
+- ! **Legal partial:** local work `done` + ship `not_started` / `blocked` **without** PR/SHA/CI/review fields and `proof_status: n/a-no-remote-claim` (or non-pass `status: partial`) is valid — do not invent ship state.
+- Machine check (library): `validateHandoffEvidence` in `@deftai/directive-core` `handoff-evidence` (`packages/core/src/handoff-evidence/`). Skills: build / pre-pr / review-cycle final checklist.
+
+! **Parent tool-first after leaf completion (#2943 / hard-stop #3131):** When a parent / monitor receives a leaf completion event (`subagent_announce`, parent-push, or host completion notify), its **first response** MUST be exactly one of: (1) a **tool-first** ground-truth batch (`gh` / `git` / worktree or file status) then one consolidate, (2) a host **yield** (`sessions_yield` on OpenClaw, or equivalent), or (3) **one short user answer** that is **not** a repeated progress line. ⊗ Multi-sentence progress-only first response with zero tools / yield — the OpenClaw text-repetition hang class (#2943). ⊗ Emit **N>2** near-identical assistant sentences (or streaming text chunks) in one turn with no `tool_use` / yield — **FC14** illegal shape; hard-stop the turn (#3131). Soft skill prose is **not** sole mitigation.
+
+! **Machine check (FC14 hard-stop):** `evaluateParentTurnShape` in `@deftai/directive-core` `parent-turn-shape` (`packages/core/src/parent-turn-shape/`). Feed ordered turn events (`assistant_text` / `tool_use` / `yield`); when `ok === false` and `failClass` is `FC14` (or post-announce `progress-only-no-tool`), abort / force tool-or-yield. Operator recovery for current OpenClaw beta pins: `docs/openclaw-agent-host.md` § Operator recovery — FC14.
 
 ⊗ Treat thin DONE (no PR URL / merge evidence) as success (#2943).
+⊗ N>2 near-identical assistant sentences with no tool_use / yield, or soft-prose-only mitigation for the parent hang (FC14 / #3131).
 ⊗ Treat empty/unknown review-monitor settle as DONE without same-turn ground truth, or dual-spawn a second monitor while the first lease is live (#3044).
 ⊗ Emit freeform `review_cycle: started` / `pending` / `initiated` or L4 `status: pass` without `done` or verifiable `in_progress:<pr>#…` (#3090).
+⊗ Claim `status: pass` (or equivalent process-green handoff) with PR URL / SHA / CI green / review score filled from memory without same-turn probe binding — **invented-done** (#3120).
+⊗ Set `proof_status: n/a-no-remote-claim` while remote PR/SHA/CI/review fields are non-empty (#3120).
+⊗ Mark ship/gate `done` or fill PR fields when only local work completed — legal partial omits remote fields (#3120).
 
 Per-step acks during the run are noise. ONE start message, ONE final message; intermediate messages only on `BLOCKED` / `FAILED`. The final message lets the dispatcher distinguish a clean exit from a silent timeout when the lifecycle event arrives.
 

package/templates/agents-entry.md

@@ -72,6 +72,7 @@ Legacy `vbrief/` read-accepted; `deft migrate:xbrief` for `xbrief/` (v0.6→v0.8
 
 ! On **through merge** / **drive to merge** / land-ship / **drive-to: merge-ready** story intent: parent MUST dispatch a `drive-to: merge-ready` worker (worktree, preflight, pre-pr, review-cycle, merge/`scope:complete`) via the **swarm/solo-worker launch path** even if **cohort size is 1** — parent MUST NOT implement as the leaf. Depth: swarm Phase 0 + skill-pin-policy (#3032 / #1880 Gap C).
 ⊗ Parent conversation implements or babysits product fix/CI loops for drive-to:merge-ready work when background subagent/worktree dispatch is available (#3032).
+! After leaf announce: tool-first / yield / one short non-repeated answer; ⊗ N>2 near-identical zero-tool (FC14 / #3131). Machine: `evaluateParentTurnShape` (`parent-turn-shape`). Depth: preamble §11 + `docs/openclaw-agent-host.md`.
 
 ## Review-surface precedence (#2308)