@deftai/directive-content 0.94.0 → 0.96.0

package/docs/consumer-issue-label-kit.md

@@ -0,0 +1,211 @@
+# Consumer issue-label kit
+
+**Audience:** consumer projects that use Directive (not the `deftai/directive` maintainer repo).  
+**Status:** recommended starter set -- not a mandate.  
+**Related:** [#2611](https://github.com/deftai/directive/issues/2611) (this kit) · [#2609](https://github.com/deftai/directive/issues/2609) (maintainer taxonomy only) · [#3124](https://github.com/deftai/directive/issues/3124) (session discovery tips) · [#1423](https://github.com/deftai/directive/issues/1423) (SCM label mirror)
+
+Directive agents label issues from the **repo's existing** label set. They must not invent labels. This guide ships a **thin portable kit** so capacity and triage matchers have something real to use.
+
+⊗ Import the full `deftai/directive` maintainer catalog (dozens of facets such as `ts-migration`, `swarm`, `area:vbrief`, full `patterns:*`). That catalog is maintainer-only ([`.github/ISSUE_LABELS.md`](https://github.com/deftai/directive/blob/master/.github/ISSUE_LABELS.md) / #2609).
+
+---
+
+## Recommended kit
+
+Create these labels in your forge (GitHub/GitLab/etc.) when you adopt Directive, or when your backlog is bare. Prefer existing project names when you already have equivalents (`defect` for `bug`, a single docs label for `documentation`).
+
+### Core (always recommend)
+
+| Label | Role |
+|-------|------|
+| `bug` | Defect / incorrect behavior |
+| `enhancement` | New capability or improvement |
+| `documentation` | Docs-only work |
+| `duplicate` | Already tracked elsewhere |
+| `wontfix` | Declined / out of scope |
+
+Optional priority: `urgent` (or your project's priority label).
+
+### Role (if you run multi-issue programs)
+
+| Label | Role |
+|-------|------|
+| `epic` | Multi-ship **product** initiative root (rare) |
+| `status:tracker` | Long-lived coordination home (plan / children), not one PR |
+| `status:child` | Has a parent -- not a root queue item |
+
+### Triage / mirror (if you use Directive triage + label mirror)
+
+| Label | Role |
+|-------|------|
+| `triaged` | Machine idempotency -- classify/mirror already ran (**include if you recommend mirror**) |
+| `triage` | Optional human "area of work" chip (not a machine `triage:*` label) |
+
+Optional action chips (only if you set `plan.policy.triageLabelMirror.actionLabels`). Use the **same names** as the maintainer machine set -- do not invent a second vocabulary:
+
+| Label | Typical `actionLabels` key |
+|-------|----------------------------|
+| `triage:deferred` | `defer` |
+| `triage:archived` | `archive` |
+
+Richer chips (`triage:lifecycle-linked`, `triage:needs-human`) exist in the maintainer set; adopt them only when your policy maps those actions.
+
+---
+
+## Story / PR (MUST)
+
+- Prefer **one issue ≈ one story ≈ one PR**.
+- Do **not** open an "epic" for two tiny checklist tasks.
+- Epic/tracker issues stay open across many PRs; **each child** closes with its PR.
+- Epics are **not** the PR unit.
+
+---
+
+## When to use `epic` (short rule)
+
+Apply **`epic` only** when this issue is a **multi-ship product initiative**: multiple shippable units by design, and this issue is the program home.
+
+**Not** "has two children." Children are normal stories with optional **`status:child`**, never `epic`.
+
+| Situation | Labels |
+|-----------|--------|
+| Product multi-ship root | `epic` + `status:tracker` |
+| Process / coordination board | `status:tracker` (epic optional / discouraged) |
+| Leaf under a parent | type label + optional `status:child` |
+| Standalone one-PR story | type label only |
+
+Parent identity lives in **links** (and current-shape / body text), not in labels. Nested mid-trackers may wear both `status:tracker` and `status:child`. Do not invent depth labels (`tracker-l2`, …).
+
+---
+
+## Document your labels
+
+~ Keep a short project catalog so agents and humans share one vocabulary. A common pattern is `.github/ISSUE_LABELS.md` in the **consumer** repo (name is a convention; any stable path works if AGENTS.md or CONTRIBUTING points at it).
+
+Example stub:
+
+```markdown
+# Issue labels (this repo)
+
+Recommended starter set from Deft Directive consumer kit:
+https://github.com/deftai/directive/blob/master/content/docs/consumer-issue-label-kit.md
+
+## Core
+- bug, enhancement, documentation, duplicate, wontfix
+- optional: urgent
+
+## Role (multi-issue programs)
+- epic (rare multi-ship product root)
+- status:tracker, status:child
+
+## Mirror (if using triage:classify -- --mirror)
+- triaged
+- optional action chips: triage:deferred, triage:archived
+  (only if plan.policy.triageLabelMirror.actionLabels maps them)
+
+Do not invent labels outside this file. Prefer existing names over twins.
+```
+
+! When creating issues, apply at least one appropriate label from the **existing** set.
+
+---
+
+## Optional: label mirror appendix
+
+After SCM label mirror Waves 1–2 (#1423 / #3125):
+
+| Topic | Guidance |
+|-------|----------|
+| Defaults | Mirror is available; on match it stamps **`triaged`** (idempotency). Action chips only when configured. |
+| Dry-run | `deft triage:classify -- --mirror` (open-only default). Review the digest before `--apply`. |
+| Apply | `deft triage:classify -- --mirror --apply` writes labels in batches; re-run is a no-op for already-`triaged` issues. |
+| More matches | Add rules under `plan.policy.triageAutoClassify` in `xbrief/PROJECT-DEFINITION.xbrief.json`. |
+| Richer chips | Set `plan.policy.triageLabelMirror.actionLabels` **and** create those GitHub labels first. |
+| Accept path | ⊗ Never auto-`triage:accept` / never auto-write `proposed/` from mirror. Accept stays an operator decision. |
+
+Minimal policy sketch (clone and edit; broader triage field examples live in the framework repo at [`docs/example-project-definition.md`](https://github.com/deftai/directive/blob/master/docs/example-project-definition.md) — not deposited under `.deft/core/`):
+
+```json
+{
+  "plan": {
+    "policy": {
+      "triageAutoClassify": [
+        {
+          "match": { "labels": { "any-of": ["wontfix"] } },
+          "action": "defer",
+          "reason": "wontfix"
+        },
+        {
+          "match": { "labels": { "any-of": ["duplicate"] } },
+          "action": "archive",
+          "reason": "duplicate"
+        }
+      ],
+      "triageLabelMirror": {
+        "actionLabels": {
+          "defer": ["triage:deferred"],
+          "archive": ["triage:archived"]
+        }
+      }
+    }
+  }
+}
+```
+
+If you only want the default `triaged` stamp, you can omit `actionLabels` entirely.
+
+Validate with:
+
+```bash
+deft triage:classify -- --validate
+deft triage:classify -- --mirror
+```
+
+---
+
+## Capacity and ranking
+
+Labels only help ranking and auto-classify when they **exist** on the forge and appear on issues. After the kit is created:
+
+- Point `plan.policy.triageRankingLabels` at labels you care about first (for example `urgent`, `bug`).
+- Point `plan.policy.triageScope` at the open-work envelope you want in cache.
+- Run `deft triage:welcome` (or your host's triage onboarding) so subscription and WIP policy match the kit.
+
+---
+
+## What not to copy from directive
+
+Do **not** treat the maintainer catalog as a consumer default. Examples of maintainer-only names:
+
+- `ts-migration`, `swarm`, `area:vbrief`, full `patterns:*` trees
+- Large `area:*` / platform / process zoos built for the framework monorepo
+- `legacy:*` quarantine names (closed history only on the framework repo)
+
+Name alignment for the thin shared set (`bug`, `enhancement`, `documentation`, `epic`, `status:tracker`, `status:child`, `triaged`, optional `triage:*` action chips) follows **#2609** so mirror and classify stay portable. Full facet depth stays maintainer-only.
+
+---
+
+## Discovery
+
+Installed deposit (consumer tree):
+
+| Surface | Path after deposit |
+|---------|-------------------|
+| This doc | `.deft/core/docs/consumer-issue-label-kit.md` |
+| SCM guide | `.deft/core/scm/github.md` (section Issue Labels) |
+| Getting started | `.deft/core/docs/getting-started.md` (backlog section) |
+
+Framework source / GitHub (browse when not in a deposit):
+
+| Surface | URL / path |
+|---------|------------|
+| This doc | [`content/docs/consumer-issue-label-kit.md`](https://github.com/deftai/directive/blob/master/content/docs/consumer-issue-label-kit.md) |
+| Session tip packaging | **#3124** (after this kit) |
+
+---
+
+## Related reading
+
+- Maintainer taxonomy (do not import wholesale): [`.github/ISSUE_LABELS.md`](https://github.com/deftai/directive/blob/master/.github/ISSUE_LABELS.md) (#2609)
+- Label mirror behavior: deposit `.deft/core/commands.md` (or framework `content/commands.md`) / `deft triage:classify -- --mirror` (#1423, #3125)
+- Example PROJECT-DEFINITION triage fields: [`docs/example-project-definition.md`](https://github.com/deftai/directive/blob/master/docs/example-project-definition.md) (#1186; framework repo only, not deposited)

package/docs/freshness-contract.md

@@ -0,0 +1,139 @@
+# Freshness contract: bound vs live generation (#3117)
+
+Long-lived multi-agent sessions can keep executing the pre-upgrade payload they
+loaded earlier even after `directive update` / deposit apply succeeds and disk
+probes report "up to date." This product **freshness contract** is host-agnostic:
+it does not depend on any single host session-key mechanism.
+
+## Readiness rule
+
+Disk-only freshness is **insufficient**. A session is ready only when its
+**bound** generation matches the **live** deposit generation for the surfaces
+it uses.
+
+## Generation token
+
+On successful deposit apply (`directive init`) or payload refresh
+(`directive update` when content swaps), Directive stamps a **monotonic** live
+generation under:
+
+```text
+.deft/GENERATION.json
+```
+
+The file is outside `.deft/core/` so a full-tree payload replace does not wipe
+the counter. Fields include `generation` (integer ≥ 1), `contentVersion`,
+`stampedAt`, `stampedBy`, and per-surface fingerprints (`payload`, `version`,
+`templates`, `skills`, `docs`).
+
+Already-current update paths ensure the token exists without advancing the
+counter when the content version is unchanged.
+
+## Session bind
+
+When a mutation `session:start` (cold or re-arm) loads payload surfaces into
+runtime context, it binds the live generation:
+
+```text
+.deft/session-binds/<safe-session-id>.json   # multi-agent isolation (preferred)
+.deft/session-bind.json                      # default / last-bind convenience
+```
+
+Multi-agent hosts **must** pin session identity so one session cannot certify
+another as current:
+
+1. Prefer `DEFT_SESSION_ID=<id>` in the process environment (printed by
+   `session:start`), or
+2. Pass `--session-id <id>` on every `freshness:report` / `freshness:bind`.
+
+Trusted readiness (`state=current`, exit 0) requires a **pinned** identity
+(explicit flag or `DEFT_SESSION_ID`). Bare report without a pin never returns
+`ready=true` even if a ritual-recovered bind matches live — that prevents
+cross-session false current when multiple agents share a worktree.
+
+`session:start` binds the ritual `session_id` path and prints the
+`DEFT_SESSION_ID=…` line for the operator or host to adopt.
+
+Hosts and operators can rebind without restarting the shared host runtime:
+
+```bash
+# After re-loading payload surfaces into the session:
+deft freshness:bind -- --confirm-payload-loaded
+# multi-agent hosts MUST pin identity:
+deft freshness:bind -- --session-id <host-session-id> --confirm-payload-loaded
+export DEFT_SESSION_ID=<host-session-id>
+deft freshness:report
+# or
+deft freshness:report -- --session-id <host-session-id>
+```
+
+`session:start` attests `payloadLoaded` automatically (payload load ceremony).
+A bare bind without `--confirm-payload-loaded` never yields trusted readiness.
+
+API (TypeScript): `bindSessionGeneration(projectRoot, options)` /
+`reportFreshness(projectRoot, { sessionId })` from
+`@deftai/directive-core/freshness`.
+
+## Freshness report
+
+```bash
+deft freshness:report
+task freshness:report
+task session:freshness
+deft freshness:report -- --json
+```
+
+Exit codes:
+
+| Code | Meaning |
+|------|---------|
+| 0 | `current` — bound matches live for used surfaces |
+| 1 | `stale_soft` or `unbound` — caution / not yet bound |
+| 2 | `stale_hard` — rebind before trusted work |
+
+Report fields: bound generation, live generation, state, differing surfaces
+(hard vs soft), rebind guidance, mid-mission safety note.
+
+## State meanings
+
+| State | Meaning | Operator action |
+|-------|---------|-----------------|
+| `current` | Bound matches live | Ready for trusted work |
+| `stale_soft` | Additive / advisory drift (e.g. docs-only) | Safe to continue with caution; rebind when convenient |
+| `stale_hard` | Evidence-untrustworthy drift (payload / version / templates / skills, or generation advance) | **Must rebind** before trusted work |
+| `unbound` | No session bind recorded | Bind after loading surfaces |
+
+Hard surfaces: `payload`, `version`, `templates`, `skills`.  
+Soft surfaces: `docs` (advisory).
+
+## Rebind without host restart
+
+1. Park in-flight mission work (see mid-mission safety).
+2. Re-load skill, ritual, template, and command bodies from the live deposit into
+   the session context (host-specific load; product does not restart the host).
+3. Run `deft freshness:bind` (or cold/re-arm `session:start`, which binds
+   automatically).
+4. Confirm with `deft freshness:report` → `current`.
+
+Prefer `session:start --rearm` or `session:ready` when ritual state is still
+valid on the same worktree — re-arm also rebinds generation.
+
+## Mid-mission safety
+
+- **Park and hand off** before a hard refresh or hard rebind.
+- An empty session after refresh is **not** "work complete." Resume from the
+  handoff artifact, not from a blank context.
+- Consumer policy decides *when* to refresh; this product owns generation +
+  honesty of bound-vs-live.
+
+## Non-goals
+
+- Restarting the whole shared runtime as the freshness mechanism.
+- Auto-resetting sessions on any file mtime change.
+- Bound proof for remote PR claims (see #3120).
+
+## Related
+
+- `content/commands.md` § Session-start ritual / freshness pointer
+- Doctor `payload-staleness` (disk/registry currency) — complementary, not a substitute
+- Issue #3117

package/docs/getting-started.md

@@ -80,6 +80,8 @@ checks tools without rewriting consumer-managed files.
 
 If you are adopting Deft on a project that already has an issue tracker (existing repo, brownfield migration, an upstream bug list that has been accumulating), you do not have to start from an empty `xbrief/proposed/`. The refinement skill's **Phase 0 triage workflow** lets you walk an existing backlog locally, decide what to keep, and let only the **accepted** items land in `xbrief/proposed/`. Trigger words: **"triage"**, **"work the cache"**, **"pre-ingest"**, **"action menu"**.
 
+**Labels first:** capacity and triage matchers only help when labels exist. For a bare or thin label set, adopt the [consumer issue-label kit](./consumer-issue-label-kit.md) (#2611) before you rely on ranking or `triage:classify -- --mirror`.
+
 ### Step 1 — Scoped first populate
 
 A real-sized backlog can drain the shared GitHub GraphQL bucket if you fetch everything at once (see [#976](https://github.com/deftai/directive/issues/976) for the recurring symptom). Scope the first populate so it lands in seconds rather than minutes:

package/docs/openclaw-agent-host.md

@@ -204,7 +204,7 @@ deft doctor --fix --openclaw-all-agents
 
 ---
 
-## Swarm on OpenClaw (#2929 / #2934 / #2943)
+## Swarm on OpenClaw (#2929 / #2934 / #2943 / #3131)
 
 ! For **parallel** swarm leaves on OpenClaw:
 
@@ -214,16 +214,20 @@ deft doctor --fix --openclaw-all-agents
 
 ! After a coding cohort completes, dispatch the next phase with a **real tool call in the same turn**, or write explicit terminal status (`blocked` / `awaiting-human` / `done`). Do not end on narrative-only “I will spawn…”.
 
-### Parent-monitor after `subagent_announce` (#2943)
+### Parent-monitor after `subagent_announce` (#2943 / hard-stop #3131)
 
-OpenClaw parents can lock into a **text-only repetition hang** after thin leaf completions: the model regenerates the same “checking worktrees / open PRs next” sentence with **zero tool calls** until length cap or abort. Subagents may still be healthy; only the parent appears hung.
+OpenClaw parents can lock into a **text-only repetition hang** after thin leaf completions: the model regenerates the same “checking worktrees / open PRs next” sentence with **zero tool calls** until length cap or abort. Subagents may still be healthy; only the parent appears hung. Soft skill prose alone is **not** enough (#2943 closed; recurrence under production → **#3131**).
 
-! After any leaf completion event (`subagent_announce` / parent-push completion), the parent’s **first response** MUST be **tool-first** or **yield**:
+! After any leaf completion event (`subagent_announce` / parent-push completion), the parent’s **first response** MUST be exactly one of:
 
-1. **Tool-first ground-truth batch** — one same-turn tool batch that inspects reality (`gh` PR/issue status, `git` / worktree status, or file/xBRIEF state), **or**
-2. **`sessions_yield`** (or host equivalent yield) — leave the turn steerable without narrating unfinished work.
+1. **Tool-first ground-truth batch** — one same-turn tool batch that inspects reality (`gh` PR/issue status, `git` / worktree status, or file/xBRIEF state), then one consolidate, **or**
+2. **`sessions_yield`** (or host equivalent yield / wait) — leave the turn steerable without narrating unfinished work, **or**
+3. **One short user answer** that is **not** a repeated progress line.
 
 ⊗ Open the first response after announce with multi-sentence progress-only prose (“Two leaves look unfinished…”, “Checking worktrees next…”, “Implementing both myself…”) and **zero** tool calls / yield.
+⊗ Emit **N>2** near-identical assistant sentences (or streaming text chunks) in one turn with no `tool_use` / yield — **FC14 text-repetition hang** (illegal turn shape; hard-stop).
+
+! **Machine check (hard-stop, not prose-only):** `evaluateParentTurnShape` in `@deftai/directive-core` / `@deftai/directive-core/parent-turn-shape` (`packages/core/src/parent-turn-shape/`). Hosts and parents SHOULD feed ordered turn events (`assistant_text` / `tool_use` / `yield`) mid-stream; when `ok === false` and `failClass` is `FC14` (or `progress-only-no-tool` after announce), **abort the turn** / force tool-or-yield — do not burn the output budget. Soft skill text is **not** the sole mitigation.
 
 ! **Thin DONE = failed leaf:** a completion without PR URL / merge evidence (and without a structured `BLOCKED` / `FAILED` terminal) is **not** success. Treat as failed: re-dispatch or take over after the ground-truth batch. Do not celebrate thin DONE as shipped.
 
@@ -231,6 +235,16 @@ OpenClaw parents can lock into a **text-only repetition hang** after thin leaf c
 
 Full rules: [`skills/deft-directive-swarm/references/host-openclaw.md`](../skills/deft-directive-swarm/references/host-openclaw.md), thin swarm SKILL hard-gates, and [`templates/agent-prompt-preamble.md`](../templates/agent-prompt-preamble.md) §11. This page does not fork a second source of truth.
 
+### Operator recovery — FC14 parent hang on current OpenClaw beta pins (#3131)
+
+When the Control UI / parent seat is stuck replaying the same progress sentence with no tools:
+
+1. **Abort the parent turn** (Control UI stop / interrupt / cancel generation). Do **not** wait for length-cap.
+2. **Do not assume leaves failed.** Check worktrees, open PRs, and xBRIEF state with a **tool-first** batch from a fresh parent turn (`gh` / `git` / files). Leaves may already be DONE or mid-review.
+3. **Resume with a legal shape only:** tool-first ground truth, `sessions_yield`, or one short non-repeated answer. ⊗ Restart by pasting more “checking next…” prose.
+4. **If the hang returns immediately:** refresh Directive deposit (`npm i -g @deftai/directive@latest` then `directive update` / `deft update` / `deft doctor --fix` for OpenClaw skill pins — see § Wire skills into OpenClaw workspace), re-open the parent with current `openclaw-agent-host` + swarm host adapter text, and re-dispatch only after ground truth.
+5. **Host pin note:** On OpenClaw beta pins that do not yet call `evaluateParentTurnShape` in the stream, the operator abort in step 1 **is** the hard stop. Directive still ships the machine-check library + skill/docs so soft prose is not the only mitigation once the host wires it (or an agent-side gate evaluates a recorded turn). Surface `FC14` in notes when reporting the incident.
+
 ## Anti-patterns
 
 - ⊗ Main-session `gh` poll + **cron** as the default babysit path when the installed skill offers a Tier 1 / background monitor.
@@ -239,9 +253,11 @@ Full rules: [`skills/deft-directive-swarm/references/host-openclaw.md`](../skill
 - ⊗ Substituting host-native review theater for `deft-directive-review-cycle` on Deft-managed repos.
 - ⊗ Claiming this doc alone makes `sessions_spawn` a shipped register/matrix primitive — that is epic skill/engine work (#2875 / #2876).
 - ⊗ Multi-sentence progress-only first response after `subagent_announce` with zero tools / yield (#2943 text-repetition hang).
+- ⊗ N>2 near-identical assistant sentences in one turn with no tool_use / yield (FC14 / #3131 hard-stop).
 - ⊗ Treating thin DONE (no PR URL / merge evidence) as success (#2943).
 - ⊗ Assuming package install alone populates OpenClaw `available_skills` — wire main workspace pins via `deft doctor --fix` (#3001).
 - ⊗ Auto-enumerating every `workspace-*` seat without `--openclaw-all-agents` (#3001).
+- ⊗ Relying on soft skill prose alone as the sole mitigation for the parent hang (#3131).
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deftai/directive-content",
-  "version": "0.94.0",
+  "version": "0.96.0",
   "description": "Shippable Directive framework content in the consumer .deft/core/ layout (C1 flatten), plus the engine surfaces (.githooks/, Taskfile.yml, tasks/) the deposit wires. Python-free per #2022 Phase 3. Refs #11, #1669, #1967.",
   "license": "MIT",
   "type": "module",