@deftai/directive-content 0.55.0

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

@@ -0,0 +1,288 @@
+---
+name: deft-directive-sync
+description: >-
+  Session-start framework sync skill. Pulls latest deft submodule, validates
+  vBRIEF lifecycle structure, checks folder/status consistency, detects stale
+  origins (RFC D12), and summarizes changes.
+triggers:
+  - good morning
+  - update deft
+  - update vbrief
+  - sync frameworks
+---
+<!-- AUTO-GENERATED by task packs:render -- DO NOT EDIT MANUALLY -->
+<!-- Purpose: rendered skill -->
+<!-- Source of truth: packs/skills/skills-pack-0.1.json -->
+<!-- Regenerate with: task packs:render -->
+<!-- Edit the source, not this file. Slice instead of loading every SKILL.md: task packs:slice skills by-trigger --trigger <kw> (or list) -->
+
+# Deft Directive Sync
+
+Session-start framework sync -- pull latest deft submodule updates, validate vBRIEF lifecycle structure, and detect stale origins.
+
+> **Canonical bootstrap / update path (post #1334 Epic, #1409):** Use the published Go installer binary (`deft-install` / platform-specific `install-*` from releases) to (re)bootstrap or update the framework payload. The canonical headless one-command refresh for an existing install is `deft-install --yes --upgrade --repo-root . --json` (drop `--json` for human-readable output) -- it actually replaces the framework payload in `.deft/core/` plus the manifest and AGENTS.md. After install the canonical `scripts/doctor.py --session --json` (or `task doctor`) runs automatically and, when the manifest sha shows the payload is stale, recommends that exact command. 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. See UPGRADING.md and the installer-doctor handoff in #1339/#1340.
+
+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`.
+
+## When to Use
+
+- User says "good morning", "update deft", "update vbrief", or "sync frameworks"
+- Beginning of a new session where framework updates may be available
+- After a known upstream deft release
+
+## Framework Events Emitted Here
+
+! When this skill responds to a context-window shift or an explicit "are you using Deft?" probe (per AGENTS.md Deft Alignment Confirmation), emit the paired `session:interrupted` -> `session:resumed` framework events via `scripts/_events.py` so observability of agent-runtime state transitions is structural, not prose-only:
+
+- ! Before re-confirming alignment: `python -m scripts._events emit session:interrupted --session-id <id> --reason context-window-shift`
+- ! Immediately after the alignment confirmation line: `python -m scripts._events emit session:resumed --session-id <id> --interrupted-id <id-from-prior-emit>`
+- ⊗ Emit a `session:resumed` whose `interrupted_id` does not reference a prior `session:interrupted` -- such records are orphan and rejected by `scripts._events.validate_pairing` (#635 events behavioral wiring)
+
+## Pre-Cutover Detection Guard
+
+! Before proceeding with sync, detect whether the project uses the pre-v0.20 document model and report model state.
+
+### Detection Criteria
+
+A project is **pre-cutover** if ANY of the following are true. This prose mirrors the executable helper in `scripts/_precutover.py`; when in doubt, the helper is canonical.
+
+1. `SPECIFICATION.md` exists and is neither a deprecation redirect nor a current generated spec export. A current generated spec export contains `<!-- Purpose: rendered specification -->` and `<!-- Source of truth: vbrief/specification.vbrief.json -->`, and `vbrief/specification.vbrief.json` plus all five lifecycle folders exist.
+2. `PROJECT.md` exists and contains neither the legacy `<!-- deft:deprecated-redirect -->` sentinel NOR the current `Purpose: deprecation redirect` canonical-banner marker (real content, not a deprecation redirect)
+3. `vbrief/specification.vbrief.json` exists but the lifecycle folders (`vbrief/proposed/`, `vbrief/pending/`, `vbrief/active/`, `vbrief/completed/`, `vbrief/cancelled/`) do NOT exist
+
+### 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)":
+
+> "This project uses the pre-v0.20 document model. Run `task migrate:vbrief` to upgrade to the vBRIEF-centric model."
+
+! Include specific details about what was detected:
+
+- Missing lifecycle folders: "Run `task migrate:vbrief` to create the lifecycle folder structure"
+- `SPECIFICATION.md` with real content: "SPECIFICATION.md contains non-redirect content -- this file is deprecated; use scope vBRIEFs in `vbrief/` instead"
+- `PROJECT.md` with real content: "PROJECT.md contains non-redirect content -- this file is deprecated; use `PROJECT-DEFINITION.vbrief.json` instead"
+- Missing `PROJECT-DEFINITION.vbrief.json`: "Run `task project:render` to generate the project definition"
+- Scope vBRIEF in wrong folder: "Status is '{status}' but file is in {folder}/ -- run `task scope:activate <file>` to fix"
+
+### Model State in Sync Output
+
+! Include a **Document Model** line in the Phase 7 summary:
+
+- Pre-cutover detected: "**Document Model**: pre-v0.20 (legacy) -- run `task migrate:vbrief` to upgrade"
+- Post-cutover (lifecycle folders present, no stale artifacts): "**Document Model**: v0.20+ (vBRIEF-centric) -- OK"
+- Post-cutover with tampered placeholders: "**Document Model**: v0.20+ with warnings -- SPECIFICATION.md or PROJECT.md contains non-redirect content"
+
+⊗ 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
+
+! 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.
+3. ! Record the current DEFT commit for later comparison:
+   ```
+   git -C deft log --oneline -1
+   ```
+4. ! Present the current state to the user:
+   - Current DEFT commit (hash + subject)
+   - Clean/dirty status
+   - Confirmation that pre-flight passed (or the blocker if dirty)
+
+## Phase 2 -- Update DEFT Submodule
+
+1. ! Run the submodule update:
+   ```
+   git submodule update --remote --merge deft
+   ```
+2. ! Show what changed by comparing before/after:
+   ```
+   git -C deft log --oneline <old-hash>..HEAD
+   ```
+3. ~ If no new commits, report "deft submodule already up to date" and proceed to Phase 3.
+
+## Phase 3 -- Structure Validation
+
+! Validate the vBRIEF lifecycle folder structure and project files.
+
+### 3a: Lifecycle Folder Structure
+
+! Verify all required lifecycle folders exist:
+
+1. ! Check that the following directories exist under `./vbrief/`:
+   - `proposed/`
+   - `pending/`
+   - `active/`
+   - `completed/`
+   - `cancelled/`
+2. ! Report any missing folders with a clear warning:
+   - "WARNING: vbrief/{folder}/ does not exist -- lifecycle structure is incomplete"
+3. ~ If folders are missing, suggest running `task migrate:vbrief` or creating them manually
+
+### 3b: PROJECT-DEFINITION.vbrief.json Validation
+
+! Validate the project identity gestalt file:
+
+1. ! Check that `./vbrief/PROJECT-DEFINITION.vbrief.json` exists
+   - If missing: "WARNING: PROJECT-DEFINITION.vbrief.json not found -- run `task project:render` to create"
+2. ! If the file exists, validate it is well-formed:
+   - Valid JSON (`python3 -m json.tool` or equivalent)
+   - Top-level `vBRIEFInfo` envelope with `version` field equal to `"0.6"`
+   - `plan` object with `title`, `status`, and `items` fields present
+   - `plan.narratives` values are plain strings (not objects or arrays)
+3. ! **Freshness check**: Compare `vBRIEFInfo.updated` (or `vBRIEFInfo.created` if no `updated`) against recent scope completions:
+   - Scan `vbrief/completed/` for vBRIEFs with `vBRIEFInfo.updated` timestamps newer than the PROJECT-DEFINITION timestamp
+   - If stale: "WARNING: PROJECT-DEFINITION.vbrief.json may be stale -- {N} scopes completed since last update. Run `task project:render` to refresh."
+
+### 3c: Validate Root-Level vBRIEF Files
+
+! Validate all `./vbrief/*.vbrief.json` files at the vbrief root:
+
+1. ! Check each file is valid JSON
+2. ! Verify structural conformance:
+   - Top-level `vBRIEFInfo` envelope with `version` field present
+   - `plan` object with `title`, `status`, and `items` fields present
+   - `plan.status` values from valid enum: draft, proposed, approved, pending, running, completed, blocked, cancelled
+3. ~ Use `task vbrief:validate` if available for deeper validation
+4. ! Report any validation failures with file name and specific violation
+
+⊗ Overwrite or modify project-level `./vbrief/*.vbrief.json` files -- those are project data, not framework files. Report issues and let the user decide how to fix them.
+
+## Phase 4 -- Lifecycle Consistency Check
+
+! Verify that each scope vBRIEF's `plan.status` matches its folder location.
+
+1. ! Scan all scope vBRIEFs in lifecycle folders (`proposed/`, `pending/`, `active/`, `completed/`, `cancelled/`)
+2. ! For each vBRIEF, check `plan.status` against the expected statuses for its folder:
+   - `proposed/`: status should be `draft` or `proposed`
+   - `pending/`: status should be `approved` or `pending`
+   - `active/`: status should be `running` or `blocked`
+   - `completed/`: status should be `completed`
+   - `cancelled/`: status should be `cancelled`
+3. ! Report any mismatches:
+   - "MISMATCH: {filename} in {folder}/ has status '{status}' -- expected one of [{expected_statuses}]"
+4. ~ Per vbrief.md convention, trust the status field and suggest correcting the folder location:
+   - "Suggested fix: move {filename} to {correct_folder}/ (status '{status}' is authoritative)"
+
+⊗ Auto-move vBRIEFs to fix folder/status mismatches -- report only; user decides during refinement or ad-hoc
+
+## Phase 5 -- Origin Freshness (RFC D12)
+
+! For vBRIEFs with external origin references, detect staleness and externally-closed origins.
+
+### Step 1: Scan Origins
+
+1. ! For each vBRIEF in `proposed/` and `pending/` with a `github-issue` reference in `plan.references` or top-level `references`:
+   - Extract the issue number from the reference URL or `id` field
+   - Fetch the issue: `gh issue view {N} --repo {owner/repo} --json updatedAt,state`
+2. ! Compare the issue's `updatedAt` against the vBRIEF's `vBRIEFInfo.updated` (or `vBRIEFInfo.created` if no `updated` field)
+
+### Step 2: Categorize and Report
+
+1. ! **Stale origins** -- issue `updatedAt` is newer than vBRIEF `updated` timestamp:
+   - "{N} vBRIEFs have origins updated since last sync"
+   - List each: "{filename}: Issue #{N} updated {time_delta} ago"
+2. ! **Externally closed origins** -- issue state is `CLOSED`:
+   - "{N} vBRIEFs have origins that were closed externally"
+   - List each: "{filename}: Issue #{N} is closed ({close_reason})"
+3. ~ **Current origins** -- no changes detected (report count only)
+
+### Step 3: Recommendation
+
+- ! Report only -- never auto-update vBRIEFs based on origin changes
+- ~ If stale or externally-closed vBRIEFs are found, suggest: "Run a refinement session (`skills/deft-directive-refinement/SKILL.md`) to reconcile stale origins with user approval."
+
+⊗ Auto-update vBRIEFs based on origin freshness checks -- report only; user decides during refinement
+
+## Phase 6 -- Framework Sync
+
+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):
+
+1. ~ Diff the structure (section headings, key rules) rather than expecting byte-identical content
+2. ~ Report any new sections or rules added upstream that are missing locally
+3. ~ Do NOT auto-overwrite -- present differences and let the user decide
+
+### 6b: Check codebase MAP freshness
+
+~ If `./.planning/codebase/MAP.md` exists, or `PROJECT-DEFINITION.vbrief.json` declares a `projectionManifest[]` entry with `kind: "codebase-map"`, run `task verify:codebase-map-fresh` when the command resolves. If it reports drift, recommend `task codebase:map` and note that the generated MAP is advisory unless the operator asked to refresh projections.
+
+- ! Keep `plan.architecture.codeStructure` and configured provider artifacts authoritative; the MAP is a generated projection.
+- ⊗ Auto-edit canonical vBRIEF metadata to make the MAP fresh during sync -- report drift and let the operator choose a follow-up.
+
+### 6c: List new skills
+
+! Compare the `skills/` directory 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
+3. ~ Mention if any existing skills were updated (changed files)
+
+## Phase 6d -- Legacy Artifact Review (post-migration, one-time)
+
+! If `vbrief/migration/LEGACY-REPORT.md` exists (and has NOT been renamed to `LEGACY-REPORT.reviewed.md`), walk the operator through each captured legacy section and record their disposition inline in the same file. This phase surfaces the non-canonical content that `task migrate:vbrief` preserved via the `LegacyArtifacts` narrative mechanism (#505).
+
+### Detection
+
+1. ! Check for `vbrief/migration/LEGACY-REPORT.md` in the project root.
+2. ! If the file is absent or `LEGACY-REPORT.reviewed.md` exists (reviewed form), skip Phase 6d silently and proceed to Phase 7.
+3. ! If `LEGACY-REPORT.md` is present and has NOT been renamed, begin the review loop below.
+
+### Review loop
+
+1. ! Present the report summary (sources + per-bucket section counts) to the user.
+2. ! For each captured section listed under `## specification.vbrief.json -> LegacyArtifacts`, `## PROJECT-DEFINITION.vbrief.json -> LegacyArtifacts`, and `## PRD.md content (flagged: hand-edited)`:
+   - Restate the section title, source file + line range, and size.
+   - Offer exactly three disposition options: **Keep** (leave inside `LegacyArtifacts`), **Fold into {suggested narrative}** (move into a canonical narrative key), or **Drop** (remove from `LegacyArtifacts`, with explicit user confirmation).
+   - ~ If a sidecar pointer is present (`vbrief/legacy/{stem}-{slug}.md`), open the sidecar for the user before offering options so the full content is visible.
+3. ! Record each disposition inline in the same `LEGACY-REPORT.md` file under a new `## Reviewed` section with one entry per legacy item: original section, user's decision, target location (if folded) or confirmation note (if kept/dropped), and the reviewer's timestamp.
+4. ! For a **Fold** decision, the agent updates the target vBRIEF's narrative key AND deletes only the corresponding section from the `LegacyArtifacts` narrative -- never the file.
+5. ! For a **Drop** decision, the agent removes only the corresponding section from the `LegacyArtifacts` narrative.
+6. ! Once all sections carry a recorded disposition, rename the file to `LEGACY-REPORT.reviewed.md`. The file is kept so the audit trail remains -- ⊗ MUST NOT delete either form.
+
+### Anti-patterns
+
+- ⊗ Delete `LEGACY-REPORT.md` or `LEGACY-REPORT.reviewed.md` -- these are the migration audit trail and MUST persist.
+- ⊗ Auto-dispose of legacy artifacts without user input -- every section requires an explicit decision.
+- ⊗ Rename to `.reviewed.md` before every captured section has a recorded disposition in the `## Reviewed` section.
+- ⊗ Drop a legacy section without explicit user confirmation (even if the section looks obviously stale).
+- ⊗ Silently delete sidecar files under `vbrief/legacy/` -- they are referenced from `LegacyArtifacts` and are part of the audit trail.
+
+## Phase 7 -- Summary
+
+! 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. **vBRIEF 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+ (vBRIEF-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
+
+! Ask the user: "Shall I commit the submodule update?" -- do NOT auto-commit.
+
+? If the user confirms, commit with message:
+```
+chore(deft): update deft submodule to <short-hash>
+```
+
+## Anti-Patterns
+
+- ⊗ Auto-commit submodule changes without user approval
+- ⊗ Overwrite project-level `./vbrief/*.vbrief.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 vBRIEF schema from upstream deftai/vBRIEF -- that is a CI concern (see #128), not a user sync task
+- ⊗ Auto-move vBRIEFs to fix folder/status mismatches -- report only; never auto-fix
+- ⊗ Auto-update vBRIEFs based on origin freshness -- report only; user decides during refinement

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

@@ -0,0 +1,137 @@
+---
+name: deft-directive-triage
+description: >-
+  Triage-cache hygiene and "what's next?" queue selection -- the agent-facing
+  playbook for syncing the triage cache, classifying candidates, presenting a
+  ranked queue, walking per-item decisions (accept / reject / defer / needs-ac
+  / mark-duplicate), and auditing the session. Use when the operator asks what
+  to work on next, wants to build a cohort, work the cache, or run a triage
+  hygiene pass.
+triggers:
+  - triage
+  - triage hygiene
+  - work the cache
+  - what's next
+  - whats next
+  - what should I work on
+  - queue
+  - build a cohort
+  - build cohort
+---
+<!-- AUTO-GENERATED by task packs:render -- DO NOT EDIT MANUALLY -->
+<!-- Purpose: rendered skill -->
+<!-- Source of truth: packs/skills/skills-pack-0.1.json -->
+<!-- Regenerate with: task packs:render -->
+<!-- Edit the source, not this file. Slice instead of loading every SKILL.md: task packs:slice skills by-trigger --trigger <kw> (or list) -->
+
+# Deft Directive Triage
+
+Triage-cache hygiene + "what's next?" queue selection. Operates against the unified `.deft-cache/github-issue/` mirror (#883 Story 2) and the append-only `vbrief/.eval/candidates.jsonl` audit log (#845 Story 2); writes only via the canonical `task triage:*` verbs.
+
+Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
+
+## Platform Requirements
+
+! Requires **GitHub** as the SCM platform and the **GitHub CLI (`gh`)** authenticated against the active project's repo -- the cache surface (`task cache:fetch-all`) and the read-side gate (`task verify:cache-fresh`) both depend on it.
+
+## Deterministic Questions Contract
+
+! Every numbered-menu prompt rendered in this skill (Phase 2 candidate selection, Phase 3 per-item decision walk) ! MUST follow [`../../contracts/deterministic-questions.md`](../../contracts/deterministic-questions.md): render the canonical numbered menu in chat unless the host UI visibly preserves numeric option labels and returns numeric selections or exact displayed option text. The final two numbered options are `Discuss` and `Back`, in that order, and the Discuss-pause semantic from the contract applies verbatim -- on `Discuss` the agent halts the in-progress sequence and resumes only on an explicit user signal.
+
+## Phase 0 -- Sync
+
+! Probe cache freshness before doing any classification or selection. Stale cache reads produce stale decisions; the gate is the contract.
+
+1. ! Run `task verify:cache-fresh` (D5 / #1127). Exit 0 -> proceed to Phase 1. Exit 1 (stale or blocked) -> refresh per the printed remediation. Exit 2 (no bootstrap) -> run `task triage:bootstrap` first.
+2. ~ Refresh path: `task cache:fetch-all -- --source=github-issue --repo OWNER/NAME` for an already-bootstrapped project (idempotent, TTL-aware, re-applies the #883 scanner v2 quarantine rules); `task triage:bootstrap` for a first-time seed.
+3. ~ If `vbrief/active/*.vbrief.json` references are in play, run `task triage:refresh-active` to compare cached `meta.json.fetched_at` against live upstream `updatedAt` and surface drift before the queue is rendered.
+4. ~ When the one-liner emitted by the session-start ritual carries a `[scope-drift] N` segment (D14 / #1133), run `task triage:scope-drift` to see the per-label / per-milestone breakdown of upstream signals on cached open issues that fall outside the active `plan.policy.triageScope[]` subscription. The output documents both opt-in (`task triage:subscribe -- --label=<L>`) and opt-out (`task triage:scope-drift -- --ignore-label=<L>`) paths -- pick one before walking the queue so the cohort reflects the operator's current intent rather than a stale subscription.
+5. ⊗ Walk the queue against a stale cache -- the audit log will record decisions against bodies the operator never actually saw.
+
+## Phase 1 -- Classify
+
+! Inspect the auto-classification audit log so manually-decided items are not re-walked, and surface anomalies before the queue render.
+
+1. ! Run `task triage:classify --list` (D10 / #1129) to render the effective universal + consumer auto-classification rules and the active hold-marker list.
+2. ! Walk recent entries in `vbrief/.eval/candidates.jsonl` for anomalies: classifier disagreements against the operator's prior decisions, repeated `defer` cycles on the same issue, or `needs-ac` records older than the freshness window. Surface anomalies to the operator before Phase 2; do NOT auto-fix.
+3. ~ When the operator wants to widen / narrow the corpus, consult `task triage:scope --list` (D12 / #1131) to see the active `plan.policy.triageScope[]` subscription. Subscription edits belong in PROJECT-DEFINITION.vbrief.json, not in this skill.
+4. ~ Issue-label hygiene: labels feed triage queue ranking, issue gauges, hygiene sweeps, and lifecycle reconciliation. When this skill exposes an unlabeled issue or a downstream issue-creation step, recommend choosing one or more suitable labels from the repository's existing label set via `gh label list` or the labels API, or explicitly note that no label was applied. This is a recommendation, not a gate.
+5. ⊗ Re-classify items already terminally decided (accept / reject / mark-duplicate) without explicit operator approval -- the audit log is append-only and supersession runs through Layer 5 (`task triage:reset <N>`), not through silent re-walks.
+6. ⊗ Block issue creation solely because no label was selected, or invent ad hoc labels outside the repository's existing label set.
+
+## Phase 2 -- Present
+
+! Render the ranked queue before suggesting any specific issue. The cache-as-authoritative rule in AGENTS.md (`## Cache-as-authoritative work selection (#1149)`) is binding: the agent ! MUST consult `task triage:queue` and surface the result before proposing work from memory.
+
+1. ! Run `task triage:queue --limit=N` (D11 / #1128) -- default `N=10` per the umbrella Current Shape v3 WIP cap. Output is grouped `[RESUME]` -> `[URGENT]` -> untriaged -> other; within-group ordering follows the consumer-supplied `plan.policy.triageRankingLabels[]` (framework default empty per §12 boundary), tiebroken by `updated_at` descending.
+2. ! For per-item detail, run `task triage:show <N>` -- prints the cached upstream payload, the latest triage decision, the audit timeline, and the active-vBRIEF reference flag. Exit 0 on hit, 1 on cache miss (re-sync per Phase 0).
+3. ~ Present the ranked queue verbatim; do NOT silently re-rank, drop, or annotate beyond what the canonical renderer emits. If the operator wants a different ordering they edit `plan.policy.triageRankingLabels[]` and re-run.
+4. ⊗ Recommend a specific issue without consulting `task triage:queue` first, or recommend an issue absent from the queue without first running `task triage:show` to surface why (cache miss / outside subscription / terminal decision).
+
+## Phase 3 -- Decide
+
+! Walk per-item decisions through the canonical `task triage:*` verbs. The skill does NOT reimplement the audit-log append, schema validation, or `vbrief/proposed/` write inline -- the tasks are the canonical implementation (mirrors the #537 ingest-task discipline).
+
+For each candidate the operator selects from the Phase 2 queue, render the canonical numbered action menu and dispatch the matching verb:
+
+```
+What would you like to do with this candidate?
+  1. Accept         -- `task triage:accept <N>`         (writes proposed/ vBRIEF + audit-log entry)
+  2. Reject         -- `task triage:reject <N>`         (audit-log entry only; terminal)
+  3. Defer          -- `task triage:defer <N> [--resume-on <event>]`  (non-terminal; resurfaces)
+  4. Needs-AC       -- `task triage:needs-ac <N>`       (non-terminal; flags missing acceptance criteria)
+  5. Mark duplicate -- `task triage:mark-duplicate <N> <of-issue>`  (terminal; cross-links target)
+  6. Discuss
+  7. Back
+```
+
+- ! `--resume-on <event>` on `task triage:defer` (D3 / #1123 -- ships in parallel; reference but do not hard-depend) records a resume condition with the defer entry; the resume condition surfaces in `task triage:queue` once met. When D3 has not landed yet, omit the flag -- the verb stays terminal-shape-compatible.
+- ! Map user replies only to the displayed number (`1`-`7`) or exact displayed option text. ⊗ Do NOT infer from alphabetic host affordances or bare letters such as `d` / `b` unless those letters were visibly rendered as choices.
+- ! On `Discuss`, halt the action sequence immediately, prompt `What would you like to discuss?`, and resume only on an explicit user signal. ⊗ Implicit resumption.
+- ! On `Back`, un-buffer the prior candidate's selection and re-render its action menu -- permitted only before the action has dispatched to a `task triage:*` command. Once dispatched, the audit entry is committed; revisions go through Layer 5 (`task triage:reset`).
+- ~ Bulk patterns: `task triage:bulk-{accept,reject,defer,needs-ac}` (#845 Story 4) for clear label-driven sweeps; bulk results still flow through the audit log so history stays coherent.
+- ⊗ Write to `vbrief/proposed/` directly -- only `task triage:accept` (which delegates to `task issue:ingest`) is authorised for that surface.
+
+## Phase 4 -- Audit
+
+! Confirm the session's decisions landed coherently before exiting the skill.
+
+1. ! Run `task triage:audit --format=json` (D11 / #1128) -- emits the stable `{generated_at, repo, vbrief_staleness, entry_count, entries: [...]}` schema; pipe through `jq` to surface this session's appended entries. For historical look-back, add the #1180 filters: `task triage:audit --since=30d --action=demote --format=json | jq` answers "how many demotes in the last 30 days?" in one call. `--since=<window>` accepts the framework duration grammar (`Nd` / `Nh` / `Nm` / `Nw` / `Ns` or ISO-8601 `PnDTnHnMnS`); `--action=<verb>` filters to a single decision verb (`accept` / `reject` / `defer` / `needs-ac` / `mark-duplicate` / `reset` / `resume-eligible`). Both filters compose with `--format=text` and `--format=json`. The framework deliberately does NOT compute trend lines or apply falsification gates -- the contract is read raw, transform with `jq`.
+2. ! Run `task triage:summary` (D2 / #1122) -- prints the canonical one-liner `[triage] N untriaged · S stale-defer · M in-flight · WIP X/Y [⚠] [· [scope-drift] N]`. The WIP cap default is 10 per the umbrella Current Shape v3 (overridable via typed `plan.policy.wipCap`). The `⚠` glyph fires only at-or-above cap. The `[scope-drift] N` segment (D14 / #1133) appears only when at least one unsubscribed label/milestone meets the framework `_DRIFT_MIN_ISSUES = 3` threshold; suppressed at zero.
+3. ~ When the summary surfaces a non-zero `[scope-drift] N` (D14 / #1133), surface it to the operator alongside `task triage:scope-drift` output and the matching `task triage:subscribe` / `task triage:unsubscribe` / `task triage:scope-drift -- --ignore-label=<L>` remediation. Subscription mutations record a `subscription-change` audit entry under `vbrief/.eval/subscription-history.jsonl` (sidecar of the existing `candidates.jsonl` audit surface) so future operators can replay how the subscription evolved. After every mutation, run `task triage:bootstrap -- --resume` to backfill newly-subscribed entries / mark newly-out-of-scope entries.
+4. ~ When the audit surfaces a stale acceptance (`accept` decision whose issue is no longer referenced by any `vbrief/active/`), surface it to the operator -- the typical fix is a fresh ingest via `task issue:ingest -- <N>` or a `task triage:reset <N>` if the acceptance was in error.
+5. ⊗ Skip the Phase 4 audit -- silent exit leaves the operator without a record of what landed in `vbrief/proposed/` this session, which is the typical recurrence vector for "what did I just accept?" confusion.
+
+## Reversibility
+
+! To undo a decision, run `task triage:reset <N>`. This writes a `reset` audit entry referencing the prior decision id; history is **never** deleted. `task triage:reset` is the canonical Layer 5 reversibility verb (resolves the V3 audit from 2026-05-13). After a reset, the candidate re-enters the untriaged group on the next `task triage:queue` render so it can be re-walked through Phase 3.
+
+⊗ Edit or delete prior entries in `vbrief/.eval/candidates.jsonl` to "undo" a decision -- the log is append-only by design and any external mutation breaks the `merge=union` rebase ergonomic (#1144 / N4).
+
+## Anti-Patterns
+
+- ⊗ Recommend a specific issue without first consulting `task triage:queue` (binding under AGENTS.md `## Cache-as-authoritative work selection (#1149)`).
+- ⊗ Walk the queue against a stale cache (Phase 0 gate skipped).
+- ⊗ Reimplement audit-log append / `proposed/` write inline -- the `task triage:*` verbs own those surfaces (#845, #883).
+- ⊗ Treat `defer` / `needs-ac` as terminal -- they intentionally resurface on the next pass.
+- ⊗ Edit `vbrief/.eval/candidates.jsonl` directly to revoke a decision -- use `task triage:reset <N>`.
+
+## EXIT
+
+! When the operator opts out (queue exhausted, mid-session stop, or explicit "done"), confirm skill exit with the canonical phrasing: `deft-directive-triage complete -- exiting skill.`
+
+! Provide chaining instructions:
+
+- **Ingestion / evaluation of accepted items**: chain into `skills/deft-directive-refinement/SKILL.md` -- refinement's Phase 1 ingests the `vbrief/proposed/` items this skill just wrote into the rest of the lifecycle.
+- **Cohort dispatch**: chain into `skills/deft-directive-swarm/SKILL.md` -- swarm Phase 0 is queue-driven (N2 / #1142) and consumes the same `task triage:queue` ordering you just walked.
+- **Fresh-state refresh before re-entry**: run `task cache:fetch-all -- --source=github-issue --repo OWNER/NAME` then re-enter this skill when ready to continue.
+
+⊗ Exit silently without the canonical confirmation + chaining instruction -- the Skill Completion Gate in AGENTS.md is binding.
+
+## References
+
+- Umbrella: #1119 (Wave-1 D6, this skill)
+- D2 #1122 (`task triage:summary`), D3 #1123 (`--resume-on`, parallel), D5 #1127 (`task verify:cache-fresh`), D10 #1129 (auto-classification), D11 #1128 (`task triage:queue` / `triage:show` / `triage:audit`), D12 #1131 (subscription scope)
+- Layer 5 reversibility verb: `scripts/triage_actions.py::reset` (already shipped under #845)
+- Sibling skills: `skills/deft-directive-refinement/SKILL.md`, `skills/deft-directive-swarm/SKILL.md`, `skills/deft-directive-sync/SKILL.md`
+- Stub author (replaced): #1149 (N9)

package/skills/deft-directive-write-skill/SKILL.md

@@ -0,0 +1,169 @@
+---
+name: deft-directive-write-skill
+description: >-
+  Create new deft skills with proper structure, RFC2119 notation, triggers,
+  and progressive disclosure. Use when user wants to create, write, or build a
+  new deft skill.
+triggers:
+  - write a skill
+  - create a skill
+  - new skill
+  - build a skill
+---
+<!-- AUTO-GENERATED by task packs:render -- DO NOT EDIT MANUALLY -->
+<!-- Purpose: rendered skill -->
+<!-- Source of truth: packs/skills/skills-pack-0.1.json -->
+<!-- Regenerate with: task packs:render -->
+<!-- Edit the source, not this file. Slice instead of loading every SKILL.md: task packs:slice skills by-trigger --trigger <kw> (or list) -->
+
+# Deft Write Skill
+
+Create new deft skills that follow directive's conventions: RFC2119 notation, YAML frontmatter with triggers, clear When-to-Use sections, and proper naming.
+
+Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
+
+> Inspired by [write-a-skill](https://github.com/mattpocock/skills/tree/main/write-a-skill) from [mattpocock/skills](https://github.com/mattpocock/skills). Adapted to deft's SKILL.md conventions, RFC2119 notation, and naming patterns.
+
+## When to Use
+
+- User wants to create a new skill for a workflow directive doesn't cover yet
+- Formalizing an ad-hoc process that keeps repeating into a reusable skill
+- Extending directive with project-specific or domain-specific skills
+
+---
+
+## Deft Skill Naming Conventions
+
+| Skill type | Naming pattern | Example |
+|---|---|---|
+| Framework / meta | `deft-{verb}` | `deft-build`, `deft-setup` |
+| GitHub-integrated | `deft-directive-gh-{verb}` | `deft-directive-gh-slice` (triage verb reclaims to `deft-directive-refinement`) |
+| Domain / project-specific | `{project}-{verb}` | `my-app-deploy` |
+
+---
+
+## Process
+
+### Step 1: Gather requirements
+
+Ask the user (one question at a time):
+
+1. What task or domain does this skill cover?
+2. What specific use cases should it handle?
+3. Does it require external tools (e.g., `gh`, `docker`, database CLIs)?
+4. Should it produce files, run commands, or guide a conversation?
+5. Any reference material or existing workflows to model from?
+
+### Step 2: Draft the skill
+
+- ! Follow the deft SKILL.md template below
+- ! Keep SKILL.md under 150 lines — split long templates into `references/*.md` (see [`references/composer-skill-porting.md`](../../references/composer-skill-porting.md))
+- ! Write the `description` field as if it's the only thing the agent will see when deciding whether to invoke this skill
+- ! Include negative triggers in `description` (`Do NOT trigger on …`) so near-miss phrases do not load the wrong skill
+- ~ Use the trigger words the user would naturally say
+- ! Use RFC2119 notation throughout (!=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY)
+- ~ Include attribution blockquote if inspired by an external source
+- ~ When porting Warp-tuned playbooks, read [`references/composer-skill-porting.md`](../../references/composer-skill-porting.md) for fast-path vs isolation, short-chat expectations, and Composer naming
+
+### Step 3: Review with user
+
+Present the draft and ask:
+- Does this cover your use cases?
+- Anything missing or unclear?
+- Should any section be more or less detailed?
+
+Iterate until approved.
+
+### Step 4: Create the skill
+
+- ! Create the directory `skills/{skill-name}/`
+- ! Write `skills/{skill-name}/SKILL.md`
+- ~ Create `skills/{skill-name}/REFERENCE.md` or `references/{topic}.md` if content exceeds 150 lines
+- ~ Create `skills/{skill-name}/scripts/` for deterministic helper scripts
+- ! When the skill creates GitHub issues or PRs, instruct authors to use `--body-file` with OS-temp paths — never inline multi-line `--body` strings (see `scm/github.md`)
+
+---
+
+## Deft SKILL.md Template
+
+```markdown
+---
+name: {skill-name}
+description: >
+  {What it does in 1–2 sentences}. Use when {specific triggers —
+  what the user would say or what context activates this skill}.
+  Do NOT trigger on {near-miss phrase 1} or {near-miss phrase 2}.
+triggers:
+  - {trigger phrase 1}
+  - {trigger phrase 2}
+[metadata:
+  clawdbot:
+    requires:
+      bins: ["gh"]   # only if external CLI is needed]
+---
+
+# {Skill Title}
+
+{One-line description of what this skill does.}
+
+Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
+
+[> Inspired by ... — optional attribution]
+
+## When to Use
+
+- {Use case 1}
+- {Use case 2}
+
+[## Prerequisites
+
+- ! Verify {tool} is available — stop and report if not]
+
+---
+
+## Process
+
+### Step 1: {Name}
+
+- ! {mandatory action}
+- ~ {recommended action}
+- ⊗ {forbidden action}
+
+### Step 2: {Name}
+
+...
+
+---
+
+## Anti-Patterns
+
+- ⊗ {what NOT to do}
+- ⊗ {what NOT to do}
+```
+
+---
+
+## Description Writing Rules
+
+The description is **the only thing the agent sees** when deciding whether to load this skill. Write it to answer:
+1. What capability does this provide?
+2. When should it trigger? (use "Use when..." pattern)
+3. What near-miss phrases must NOT trigger it? (use "Do NOT trigger on..." pattern)
+
+- ! Max 1024 characters
+- ! Include "Use when [specific triggers]" in the description
+- ! Include "Do NOT trigger on [near-miss phrases]" when triggers could overlap another skill
+- ⊗ Vague descriptions ("helps with things") — the agent can't distinguish between skills
+- ! First sentence: what it does. Second sentence: when to use it. Third (when needed): what not to trigger on.
+
+---
+
+## Anti-Patterns
+
+- ⊗ Omitting RFC2119 notation — deft skills use it consistently
+- ⊗ Putting all content in SKILL.md when it exceeds 150 lines — split into `references/*.md` or `REFERENCE.md`
+- ⊗ Vague trigger phrases — use phrases the user would actually type
+- ⊗ Overlapping triggers without negative triggers — add `Do NOT trigger on …` to the description
+- ⊗ Naming a GitHub-integrated skill without `gh` in the name
+- ⊗ Writing the description without a "Use when..." clause
+- ⊗ Inline multi-line `gh --body` strings in skill steps — use `--body-file` per `scm/github.md`

package/skills/deft-interview/SKILL.md

@@ -0,0 +1,16 @@
+# Deprecated skill path — v0.19 → v0.20 bridge
+
+<!-- deft:deprecated-skill-redirect -->
+
+This skill path is deprecated. Read `deft/QUICK-START.md` for current routing.
+The current replacement skill is `deft-directive-interview` (at `skills/deft-directive-interview/SKILL.md`).
+
+Do not add real content here. This file exists so that stale v0.19 `AGENTS.md` files
+that reference old `deft/skills/deft-*` paths keep working through one release cycle.
+QUICK-START.md refreshes the Deft-managed section of `AGENTS.md` to the current
+v0.20 `deft-directive-*` skill paths.
+
+See:
+- [../../QUICK-START.md](../../QUICK-START.md) — agent bootstrap + upgrade detection
+- [../../UPGRADING.md](../../UPGRADING.md) — version-by-version upgrade guide
+- [../../docs/BROWNFIELD.md](../../docs/BROWNFIELD.md) — brownfield adoption / migration

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

@@ -0,0 +1,16 @@
+# Deprecated skill path — v0.19 → v0.20 bridge
+
+<!-- deft:deprecated-skill-redirect -->
+
+This skill path is deprecated. Read `deft/QUICK-START.md` for current routing.
+The current replacement skill is `deft-directive-pre-pr` (at `skills/deft-directive-pre-pr/SKILL.md`).
+
+Do not add real content here. This file exists so that stale v0.19 `AGENTS.md` files
+that reference old `deft/skills/deft-*` paths keep working through one release cycle.
+QUICK-START.md refreshes the Deft-managed section of `AGENTS.md` to the current
+v0.20 `deft-directive-*` skill paths.
+
+See:
+- [../../QUICK-START.md](../../QUICK-START.md) — agent bootstrap + upgrade detection
+- [../../UPGRADING.md](../../UPGRADING.md) — version-by-version upgrade guide
+- [../../docs/BROWNFIELD.md](../../docs/BROWNFIELD.md) — brownfield adoption / migration

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

@@ -0,0 +1,16 @@
+# Deprecated skill path — v0.19 → v0.20 bridge
+
+<!-- deft:deprecated-skill-redirect -->
+
+This skill path is deprecated. Read `deft/QUICK-START.md` for current routing.
+The current replacement skill is `deft-directive-review-cycle` (at `skills/deft-directive-review-cycle/SKILL.md`).
+
+Do not add real content here. This file exists so that stale v0.19 `AGENTS.md` files
+that reference old `deft/skills/deft-*` paths keep working through one release cycle.
+QUICK-START.md refreshes the Deft-managed section of `AGENTS.md` to the current
+v0.20 `deft-directive-*` skill paths.
+
+See:
+- [../../QUICK-START.md](../../QUICK-START.md) — agent bootstrap + upgrade detection
+- [../../UPGRADING.md](../../UPGRADING.md) — version-by-version upgrade guide
+- [../../docs/BROWNFIELD.md](../../docs/BROWNFIELD.md) — brownfield adoption / migration