@deftai/directive-content 0.71.0 → 0.71.1

package/UPGRADING.md

@@ -261,6 +261,7 @@ runs the doctor first gets pointed at this exact two-step before touching `init`
 - **From v0.27.x — mostly auto-handled.** Pick up the install manifest and the `deft/` → `.deft/core/` layout: [From v0.27.x → v0.28](#from-v027x---v028-canonical-install-manifest-at-installversion), [From deft/ → .deft/core/](#from-deft---deftcore), and [From drifted AGENTS.md → current install](#from-drifted-agentsmd---current-install-task-upgrade-repair-path-1061).
 - **From v0.60.x — manual (hook refresh).** After #2049, consumer `.githooks/` dispatch through the `deft` CLI only. Run [From v0.60.0 → v0.61.x (refresh project-root git hooks, #2049)](#from-v0600--v061x-refresh-project-root-git-hooks-2049) after every framework upgrade that touches hook templates.
 - **From v0.28–v0.36 (and the final hop to current) — auto-handled.** If still on the Go-installer layout, follow the [One-time migration from the Go installer](#one-time-migration-from-the-go-installer-legacy--npm) above, then `npm i -g @deftai/directive@latest` for all future upgrades.
+- **From v0.70.x — auto-handled (lazy).** The triage working-set cache moved off `.eval/` to `.triage-cache/`; run any triage/scope/doctor command once after upgrade to trigger the lazy migration: [From v0.70.x → v0.71.0 (triage cache relocation, #1703)](#from-v070x--v0710-triage-cache-relocation-1703).
 
 **Final step for every bucket.** Finish on the canonical npm upgrade path, then let the doctor confirm you are current:
 
@@ -275,6 +276,31 @@ Run those from your project root after any bucket-specific hops (`deft update` r
 
 ---
 
+## From v0.70.x → v0.71.0 (triage cache relocation, #1703)
+
+- **Applies when:** any project on deft v0.70.x (or earlier releases that stored the triage working-set under `<lifecycle-root>/.eval/`) that upgrades to v0.71.0+. Detection: after upgrade, triage append-only logs (`candidates.jsonl`, `slices.jsonl`, `summary-history.jsonl`, `scope-lifecycle.jsonl`, `subscription-history.jsonl`, `doctor-state.json`, `decompositions/`, `README.md`) still live under `<lifecycle-root>/.eval/` instead of `<lifecycle-root>/.triage-cache/`. The `<lifecycle-root>` is `xbrief/` or legacy `vbrief/` depending on your layout.
+- **Safe to auto-run:** Yes (lazy, idempotent). The engine migrates each known legacy file/dir from `.eval/` → `.triage-cache/` the first time any triage/scope/doctor path is resolved after upgrade — for example `deft triage:summary`, `deft triage:bootstrap`, `deft doctor`, or any scope transition that touches the triage cache. Nothing to do manually beyond running one of those commands once; re-runs are no-ops.
+- **Restart required:** No for the filesystem migration itself. Start a **new agent session** after upgrade if your session still cites the old `.eval/` triage paths in AGENTS.md or skill prose loaded before the deposit refresh.
+- **Commands:**
+  - `deft triage:summary` (or any other triage/scope/doctor verb — triggers lazy migration on first resolve)
+  - `deft doctor` (also resolves triage-cache paths during install-integrity checks)
+  - `ls <lifecycle-root>/.triage-cache/` (confirm relocated files after the first trigger)
+
+### What changed
+
+- **Triage working-set moved.** Append-only triage logs, decomposition scratch, and the deposited triage README now resolve under `<lifecycle-root>/.triage-cache/` instead of `<lifecycle-root>/.eval/`.
+- **`.eval/` reclaimed for framework eval.** The `.eval/` namespace is now the version-eval results store at `<lifecycle-root>/.eval/results/` (health/golden/crud ledgers from #1703). This store had no prior home — it is not a rename of the triage cache.
+- **Lazy migration, not upgrade-triggered.** `deft update`, `deft migrate`, and `deft migrate:xbrief` do **not** relocate the triage working-set. The last copies `vbrief/.eval/` → `xbrief/.eval/` as-is when crossing the xbrief rename; the triage relocation fires only on triage/scope/doctor path resolve. There is no dedicated `migrate:triage-cache` verb.
+- **Conflict policy (canonical wins).** When both a legacy `.eval/` copy and a canonical `.triage-cache/` copy of the same basename exist, the legacy `.eval/` entry is skipped — the canonical `.triage-cache/` file wins. The migration is idempotent.
+
+### References
+
+- [#1703](https://github.com/deftai/directive/issues/1703) — triage working-set relocation + framework-eval results store.
+- [#2349](https://github.com/deftai/directive/issues/2349) — operator-facing upgrade documentation for this relocation.
+- [`packages/core/src/triage/cache-path.ts`](../packages/core/src/triage/cache-path.ts) — `migrateLegacyTriageCacheFromEval()` implementation.
+
+---
+
 ## From v0.60.0 → v0.61.x (refresh project-root git hooks, #2049)
 
 - **Applies when:** your project was on deft v0.60.x (or earlier) with `.githooks/` installed via `deft setup` / the npm deposit path, and hooks still invoke legacy Python scripts (`scripts/preflight_branch.py`, `scripts/preflight_gh.py`, etc.). Detection: `deft verify:hooks-installed` fails with "still dispatches through Python scripts (expected deft CLI only, #2049)" or pre-commit/pre-push errors mentioning missing `scripts/*.py` on Python-free installs.

package/contracts/deterministic-questions.md

@@ -1,5 +1,5 @@
 # Deterministic Questions Contract
-Canonical rule for every structured `ask_user_question` prompt and every numbered-menu prompt rendered in skill prose. Lives once here so individual skills can `!` cross-reference instead of duplicating the rule body. Surfaced by #767 after the 2026-04-30 swarm-planning session where users typed `discuss (user-provided)` to break out of a deterministic question and `wait` at a hard gate -- both honored by convention only.
+Canonical rule for every structured `ask_user_question` prompt, every agent-initiated ad-hoc structured question outside any skill (orchestration approvals, dispatch confirmations, decision walkthroughs), and every numbered-menu prompt rendered in skill prose. Lives once here so individual skills and always-loaded policy surfaces can `!` cross-reference instead of duplicating the rule body. Surfaced by #767 after the 2026-04-30 swarm-planning session where users typed `discuss (user-provided)` to break out of a deterministic question and `wait` at a hard gate -- both honored by convention only. Runtime enforcement for agent-initiated prompts is #1470 (AGENTS.md managed section + orchestrator preamble self-check).
 Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
 **See also**: [main.md](../../main.md) | [glossary.md](../glossary.md) (deterministic mode entry) | [skills/deft-directive-interview/SKILL.md](../skills/deft-directive-interview/SKILL.md) (canonical interview loop) | [vbrief/completed/2026-04-20-431-deterministic-questions-rc2-defects.vbrief.json](../../vbrief/completed/2026-04-20-431-deterministic-questions-rc2-defects.vbrief.json) (RC2 prior art)
 ## Prior art reviewed (#431)
@@ -9,12 +9,12 @@ The RC2 work in #431 (closed; "Deterministic questions (RC2): confirm step, back
 3. **Confirmation step before destructive write** -- post-interview confirmation gates (e.g. `skills/deft-directive-setup/SKILL.md` Post-Interview Confirmation Gate) are independent of the option list and ride on top of every deterministic flow.
 This contract EXTENDS that surface by promoting `Discuss` to a peer of `Back` (both are now mandatory final options) and by codifying the Discuss-pause semantic verbatim. It does NOT introduce a separate `Other` option; this contract is purely about adding `Discuss` + `Back` as canonical numbered options. The pre-#767 surface (back navigation, confirm step, Other-vs-escape distinction) remains intact.
 ## The rule
-- ! Every structured `ask_user_question` prompt (single-select OR multi-select) and every numbered-menu prompt rendered in skill prose MUST include `Discuss` and `Back` as the final two numbered options, in that order. The numbering is local to the prompt (it does not need to be the literal "N-1" / "N" -- it just needs to be the last two entries presented to the user).
+- ! Every structured `ask_user_question` prompt (single-select OR multi-select), every agent-initiated ad-hoc structured question emitted outside any skill flow, and every numbered-menu prompt rendered in skill prose MUST include `Discuss` and `Back` as the final two numbered options, in that order. The numbering is local to the prompt (it does not need to be the literal "N-1" / "N" -- it just needs to be the last two entries presented to the user).
 - ! `Discuss` MUST be a top-level numbered option, NOT a sub-choice of any `Other` / `Custom` option. Honoring #431's escape-hatch principle.
 - ! `Back` MUST return to the prior question or decision point. Selecting `Back` from the very first question of a flow returns to the calling skill's entry-point (or surfaces "Nothing earlier to go back to" and re-asks the current question).
 - ⊗ Render a deterministic numbered menu without `Discuss` and `Back` as the final two options.
 - ⊗ Combine `Discuss` and `Other` into one option. They serve different roles -- `Other` widens the question's answer space; `Discuss` exits the question entirely.
-- ⊗ Render `Discuss` or `Back` only in some skills -- the rule is universal across every deterministic-mode skill.
+- ⊗ Render `Discuss` or `Back` only in some skills or only in skill prose -- the rule is universal across every deterministic question, including agent-initiated ad-hoc `ask_user_question` prompts outside any skill.
 ## Host-UI portability rule (#1563)
 Host-native structured question tools are allowed only when they preserve the deterministic menu the user actually sees. The visible labels and the fallback mapping are the contract; host UI affordances are not.
 - ! Deterministic flows MUST render the canonical numbered menu in plain chat text unless the host-native structured UI is known to visibly preserve the canonical numeric option labels and return numeric selections or exact displayed option text.
@@ -56,4 +56,4 @@ Each affected skill carries a `!` cross-reference pointing here, mirroring the R
 - `skills/deft-directive-release/SKILL.md`
 The `interview` and `build` skills are deliberately not edited under #767 (Agents 2 / 3 own those surfaces); the cross-reference will land there in their PRs and read this contract.
 ## Test surface
-`tests/content/test_deterministic_questions.py` scans skill prose for documented numbered menus and asserts that `Discuss` and `Back` are the final two options. The test also asserts that this contract file exists, contains the verbatim Discuss-pause semantic, and is cross-referenced from each affected skill.
+`packages/core/src/content-contracts/skills/deterministic_questions.test.ts` (port of `tests/content/test_deterministic_questions.py`) scans skill prose for documented numbered menus and asserts that `Discuss` and `Back` are the final two options. The test also asserts that this contract file exists, contains the verbatim Discuss-pause semantic, names agent-initiated ad-hoc prompts in scope, and is cross-referenced from each affected skill. Always-loaded runtime obligation markers are enforced separately via `agents_entry_contract.test.ts` (AGENTS.md managed section + template) and the orchestrator preamble self-check section in `templates/agent-prompt-preamble.md` (#1470).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deftai/directive-content",
-  "version": "0.71.0",
+  "version": "0.71.1",
   "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.",
   "type": "module",
   "files": [

package/tasks/slice.yml

@@ -56,7 +56,7 @@ tasks:
           ENGINE_CMD: 'slice record-existing {{.CLI_ARGS}} --project-root "{{.USER_WORKING_DIR}}"'
 
   list:
-    desc: "List recorded slices in vbrief/.eval/slices.jsonl (umbrella + child count + actor + sliced_at). -- task slice:list [-- --json]"
+    desc: "List recorded slices in <lifecycle-root>/.triage-cache/slices.jsonl (umbrella + child count + actor + sliced_at). -- task slice:list [-- --json]"
     internal: true
     dir: '{{.USER_WORKING_DIR}}'
     deps:

package/tasks/triage-summary.yml

@@ -21,7 +21,7 @@ vars:
 
 tasks:
   summary:
-    desc: "Emit the D2 (#1122) one-line triage state for the session-start ritual (N9 / #1149). Always exits 0; appends a JSONL record to vbrief/.eval/summary-history.jsonl. -- task triage:summary -- [--json] [--no-history]"
+    desc: "Emit the D2 (#1122) one-line triage state for the session-start ritual (N9 / #1149). Always exits 0; appends a JSONL record to <lifecycle-root>/.triage-cache/summary-history.jsonl. -- task triage:summary -- [--json] [--no-history]"
     internal: true
     # Runtime/session dispatch: no engine:_ts-build / pnpm build (#2181).
     dir: '{{.USER_WORKING_DIR}}'

package/templates/agent-prompt-preamble.md

@@ -271,6 +271,17 @@ Value attribution, budgeted session readbacks, and upstream gap escalation are g
 
 Reference: AGENTS.md `## Value feedback and attribution (#1709)`, issue #1709.
 
+## 5.8 Deterministic questions runtime self-check (#1470)
+
+The #767 contract applies to skill prose AND to agent-initiated structured questions at runtime. Prose-scanning tests cannot observe host `ask_user_question` tool calls — workers and orchestrators MUST self-enforce before every structured prompt.
+
+- ! Before calling any host structured-question tool (`ask_user_question`, Cursor `AskQuestion`, or equivalent) OR rendering any numbered decision menu in chat — inside or outside a skill — verify the final two options are `Discuss` then `Back`, in that order.
+- ! On `Discuss` selection, halt immediately per the verbatim Discuss-pause semantic in `content/contracts/deterministic-questions.md`: no further tool calls beyond acknowledging the pause; prompt `What would you like to discuss?`; resume only on an explicit user signal (re-asking the original question, saying `resume`/`continue`, or re-issuing the prior selection).
+- ⊗ Rely on the host UI's `Other` affordance as the Discuss escape — it widens the answer space; `Discuss` exits the deterministic flow entirely (#767).
+- ⊗ Omit `Discuss`/`Back` on ad-hoc orchestration prompts (swarm approval, routing decisions, scope confirmations) — the highest-traffic runtime surface (#1470 recurrence).
+
+Reference: AGENTS.md `## Deterministic questions runtime obligation (#1470)`, `content/contracts/deterministic-questions.md`, issue #1470. Refs #767.
+
 ## 6. No Draft re-toggling within a single review cycle
 
 Once a PR transitions Draft -> Ready, keep it Ready unless a P0 finding requires re-Draft. Repeated Draft<->Ready toggles cost GraphQL mutations and trigger stale CheckRun states downstream (Greptile re-runs, branch-protection re-evaluations).

package/templates/agents-entry.md

@@ -99,6 +99,15 @@ Rationale + cross-references: `.deft/core/docs/analysis/2026-07-02-agents-md-inc
 - ! Fetch issue comments via REST (`gh api repos/<owner>/<repo>/issues/<N>/comments`), read the `## Current shape (as of pass-N)` comment, and any linked context or `LockedDecisions` xBRIEF referenced there — following the reading order body -> current-shape comment -> amendment comments (claim-cites-state-surface, #2066). Prefer the deterministic read path: `deft umbrella:current-shape <N>` (or `task umbrella:current-shape <N>`) — it locates the canonical comment, validates #1152 sections, and never falls back to the issue body.
 - ⊗ Conclude umbrella or epic status from the issue body alone. Any "X is done" / "X is the blocker" assertion about an umbrella MUST cite the current-shape comment or another state artifact, not the body.
 
+## Deterministic questions runtime obligation (#1470)
+
+Rationale + cross-references: `.deft/core/content/contracts/deterministic-questions.md` (#767); closes the agent-runtime enforcement gap on issue #1470.
+
+- ! ANY agent-initiated structured question — whether via host `ask_user_question` / `AskQuestion` tooling or a numbered menu rendered in chat — inside OR outside any skill flow MUST include `Discuss` and `Back` as the final two options, in that order, and MUST obey the Discuss-pause semantic documented verbatim in `.deft/core/content/contracts/deterministic-questions.md`.
+- ! Before emitting any structured or numbered question, self-check: confirm `Discuss` and `Back` are present as the final two options; if not, add them before calling the tool or rendering the menu. Host-native `Other` / free-text affordances are NOT substitutes for `Discuss` (#767 / #431).
+- ⊗ Emit a structured or numbered question without `Discuss` and `Back` as the final two options — including ad-hoc orchestration approvals, dispatch confirmations, and decision walkthroughs outside interview/setup/refinement skills.
+- ⊗ Treat the host UI's automatic `Other` option as the stop-and-discuss escape hatch — `Other` widens the answer space; `Discuss` exits the deterministic flow entirely (see contract).
+
 ## Issue body→comments reading (#2143)
 
 Rationale + cross-references: `.deft/core/docs/analysis/2026-07-02-agents-md-incident-rule-rationale.md` § Issue body→comments reading (#2143); preamble § 5.6 in `.deft/core/content/templates/agent-prompt-preamble.md`.