@deftai/directive-content 0.73.0 → 0.74.0

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

@@ -24,6 +24,22 @@ Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
 - User asks to create USER.md, PROJECT-DEFINITION.xbrief.json, or a specification
 - User clones a deft-enabled repo for the first time with no config
 
+## Consumer-first default (#1813)
+
+! Assume the operator is **using Deft in their project** (consumer path). Proceed directly to the Pre-Cutover Detection Guard and Phase 1 — do NOT open with a contributor-vs-consumer fork.
+
+~ The overwhelming majority of setup sessions are consumer installs; contributor onboarding is a separate, opt-in path (see below).
+
+## Contributor / framework-maintainer path (secondary)
+
+? Only enter this branch when the user **explicitly** says they are working on Deft itself (framework source checkout, `deftai/directive` clone, or maintainer tooling).
+
+When that happens:
+
+1. ! Tell the user: "Contributor setup lives in [`CONTRIBUTING.md`](../../../CONTRIBUTING.md) and this repo's root [`AGENTS.md`](../../../AGENTS.md). Use the maintainer installer: `deft-install --yes --upgrade --maintainer --repo-root . --json`."
+2. ⊗ Continue the consumer USER.md / PROJECT-DEFINITION interview — the maintainer path does not use the first-session consumer flow.
+3. **Stop here** unless the user explicitly asks to continue with consumer setup anyway.
+
 ## Pre-Cutover Detection Guard
 
 ! Before proceeding with any setup phase, detect whether the project uses the pre-v0.20 document model and redirect to migration if so.

package/tasks/engine.yml

@@ -10,6 +10,76 @@ vars:
   DEFT_ROOT: '{{joinPath .TASKFILE_DIR ".."}}'
 
 tasks:
+  pm-run:
+    internal: true
+    desc: "Run a package.json script via pnpm (bare or Corepack pin) or explicit DEFT_PACKAGE_MANAGER=npm (#2410)."
+    dir: '{{.DEFT_ROOT}}'
+    cmds:
+      - |
+        set -eu
+        node -e "
+          const {execFileSync}=require('child_process');
+          const fs=require('fs');
+          const root=process.argv[1];
+          const script=process.argv[2];
+          const pkgPath=root+'/package.json';
+          if(!fs.existsSync(pkgPath)){
+            console.error('deft: package.json missing at '+root);
+            process.exit(2);
+          }
+          const pkg=JSON.parse(fs.readFileSync(pkgPath,'utf8'));
+          // Cross-platform probe (#2415): do NOT use Unix `sh -c 'command -v'` —
+          // Windows native Task often has no `sh` on PATH, so Corepack.cmd was
+          // invisible after #2411. Prefer a direct spawn (POSIX / real binaries);
+          // fall back to shell:true so PATHEXT resolves .cmd/.exe on win32.
+          const hasCmd=(name)=>{
+            try{
+              execFileSync(name,['--version'],{stdio:'ignore'});
+              return true;
+            }catch{
+              try{
+                execFileSync(name,['--version'],{stdio:'ignore',shell:true});
+                return true;
+              }catch{
+                return false;
+              }
+            }
+          };
+          const run=(cmd,args)=>{
+            execFileSync(cmd,args,{cwd:root,stdio:'inherit',shell:true});
+          };
+          const trySteps=(steps)=>{
+            for(const [cmd,args] of steps){
+              try{
+                run(cmd,args);
+                process.exit(0);
+              }catch{
+                // fall through to Corepack / next resolver
+              }
+            }
+          };
+          const envPm=String(process.env.DEFT_PACKAGE_MANAGER||'').trim().toLowerCase();
+          if(envPm==='npm'){
+            run('npm',['run',script]);
+            process.exit(0);
+          }
+          const pin=String(pkg.packageManager||'').trim();
+          const match=pin.match(/^pnpm@(.+)$/);
+          const steps=[];
+          if(hasCmd('pnpm')) steps.push(['pnpm',['run',script]]);
+          if(hasCmd('corepack')&&match) steps.push(['corepack',['pnpm@'+match[1],'run',script]]);
+          if(hasCmd('corepack')) steps.push(['corepack',['pnpm','run',script]]);
+          trySteps(steps);
+          console.error('deft: neither pnpm nor corepack is available to run \"'+script+'\".');
+          if(pin){
+            console.error('  Enable Corepack for the pinned manager: corepack enable && corepack prepare '+pin+' --activate');
+          }else{
+            console.error('  Install pnpm or enable Corepack (see package.json#packageManager).');
+          }
+          console.error('  Or set DEFT_PACKAGE_MANAGER=npm for an explicit npm build path.');
+          process.exit(127);
+        " "{{.DEFT_ROOT}}" "{{.PM_SCRIPT}}"
+
   _ts-build:
     internal: true
     desc: "Build CLI dist from the framework source checkout; no-op on npm consumer deposits that ship no packages/ source (#2022 Phase 3 / #2126)."
@@ -32,12 +102,69 @@ tasks:
         if [ -f "{{.DEFT_ROOT}}/packages/cli/package.json" ] \
            && [ -f "{{.DEFT_ROOT}}/package.json" ] \
            && node -e "const fs=require('fs');const j=JSON.parse(fs.readFileSync(process.argv[1],'utf8'));process.exit(j.scripts&&j.scripts.build?0:1)" "{{.DEFT_ROOT}}/package.json"; then
-          pnpm --dir "{{.DEFT_ROOT}}" run build
+          node -e "
+            const {execFileSync}=require('child_process');
+            const fs=require('fs');
+            const root=process.argv[1];
+            const script='build';
+            const pkgPath=root+'/package.json';
+            const pkg=JSON.parse(fs.readFileSync(pkgPath,'utf8'));
+            // Cross-platform probe (#2415): do NOT use Unix `sh -c 'command -v'` —
+            // Windows native Task often has no `sh` on PATH, so Corepack.cmd was
+            // invisible after #2411. Prefer a direct spawn (POSIX / real binaries);
+            // fall back to shell:true so PATHEXT resolves .cmd/.exe on win32.
+            const hasCmd=(name)=>{
+              try{
+                execFileSync(name,['--version'],{stdio:'ignore'});
+                return true;
+              }catch{
+                try{
+                  execFileSync(name,['--version'],{stdio:'ignore',shell:true});
+                  return true;
+                }catch{
+                  return false;
+                }
+              }
+            };
+            const run=(cmd,args)=>{
+              execFileSync(cmd,args,{cwd:root,stdio:'inherit',shell:true});
+            };
+            const trySteps=(steps)=>{
+              for(const [cmd,args] of steps){
+                try{
+                  run(cmd,args);
+                  process.exit(0);
+                }catch{
+                  // fall through to Corepack / next resolver
+                }
+              }
+            };
+            const envPm=String(process.env.DEFT_PACKAGE_MANAGER||'').trim().toLowerCase();
+            if(envPm==='npm'){
+              run('npm',['run',script]);
+              process.exit(0);
+            }
+            const pin=String(pkg.packageManager||'').trim();
+            const match=pin.match(/^pnpm@(.+)$/);
+            const steps=[];
+            if(hasCmd('pnpm')) steps.push(['pnpm',['run',script]]);
+            if(hasCmd('corepack')&&match) steps.push(['corepack',['pnpm@'+match[1],'run',script]]);
+            if(hasCmd('corepack')) steps.push(['corepack',['pnpm','run',script]]);
+            trySteps(steps);
+            console.error('deft: neither pnpm nor corepack is available to run \"'+script+'\".');
+            if(pin){
+              console.error('  Enable Corepack for the pinned manager: corepack enable && corepack prepare '+pin+' --activate');
+            }else{
+              console.error('  Install pnpm or enable Corepack (see package.json#packageManager).');
+            }
+            console.error('  Or set DEFT_PACKAGE_MANAGER=npm for an explicit npm build path.');
+            process.exit(127);
+          " "{{.DEFT_ROOT}}"
         fi
 
   invoke:
     internal: true
-    desc: "Run a deft-ts verb from vendored bin.js (source checkout) or global deft (npm consumer deposit). Source checkouts without a built dist fail fast (#2181) -- runtime/session tasks must not trigger engine:_ts-build / pnpm."
+    desc: "Run a deft-ts verb from vendored bin.js (source checkout) or global deft (npm consumer deposit / runtime fallback #2409). Runtime/session verbs must not trigger engine:_ts-build / pnpm (#2181)."
     # Run from the operator project root so deft verbs resolve USER_WORKING_DIR
     # correctly; without this, included engine.yml defaults cwd to tasks/ (#2022).
     dir: '{{.USER_WORKING_DIR}}'
@@ -69,11 +196,67 @@ tasks:
           fi
           node "$bin" {{.ENGINE_CMD}}
         elif [ "$is_buildable_source" = 1 ]; then
-          echo "deft: CLI artifact missing at {{.DEFT_ROOT}}/packages/cli/dist/bin.js" >&2
-          echo "  Run \`task build\` first (framework source checkout)." >&2
-          exit 2
+          engine_cmd='{{.ENGINE_CMD}}'
+          first_token="${engine_cmd%% *}"
+          is_runtime_verb=0
+          case " ${first_token} " in
+            " session:start "|" session-start "|\
+            " verify:session-ritual "|" verify-session-ritual "|\
+            " verify:tools "|" verify-tools "|\
+            " triage:summary "|" triage-summary "|\
+            " triage:welcome "|" triage-welcome "|\
+            " verify:cache-fresh "|" verify-cache-fresh "|\
+            " preflight-cache ")
+              is_runtime_verb=1
+              ;;
+          esac
+          if [ "${DEFT_USE_GLOBAL_CLI:-}" = "1" ]; then
+            is_runtime_verb=1
+          fi
+          global_cli=""
+          if command -v deft >/dev/null 2>&1; then
+            global_cli=deft
+          elif command -v directive >/dev/null 2>&1; then
+            global_cli=directive
+          fi
+          if [ "$is_runtime_verb" = 1 ] && [ -n "$global_cli" ]; then
+            node -e "
+              const {execFileSync}=require('child_process');
+              const root=process.argv[1];
+              const cli=process.argv[2];
+              let srcVer='0.0.0-dev';
+              try{
+                if(process.env.DEFT_RELEASE_VERSION){
+                  srcVer=process.env.DEFT_RELEASE_VERSION;
+                }else{
+                  srcVer=execFileSync('git',['describe','--tags','--abbrev=0'],{cwd:root,encoding:'utf8'}).trim().replace(/^v/,'');
+                }
+              }catch{}
+              let globalVer='unknown';
+              try{
+                globalVer=execFileSync(cli,['--version'],{encoding:'utf8'}).trim();
+              }catch{}
+              const m=globalVer.match(/@([0-9]+\\.[0-9]+\\.[0-9]+)/)||globalVer.match(/([0-9]+\\.[0-9]+\\.[0-9]+)/);
+              const gv=m?m[1]:globalVer;
+              if(srcVer!=='0.0.0-dev'&&gv!=='unknown'&&gv!==srcVer){
+                console.error('deft: using global '+cli+' ('+gv+'); source checkout is v'+srcVer+' — run task build for a local engine match.');
+              }
+            " "{{.DEFT_ROOT}}" "$global_cli" >&2 || true
+            "$global_cli" {{.ENGINE_CMD}}
+          else
+            echo "deft: CLI artifact missing at {{.DEFT_ROOT}}/packages/cli/dist/bin.js" >&2
+            if [ "$is_runtime_verb" = 1 ]; then
+              echo "  Install global deft: npm i -g @deftai/directive" >&2
+              echo "  Or run \`task build\` first (framework source checkout)." >&2
+            else
+              echo "  Run \`task build\` first (framework source checkout)." >&2
+            fi
+            exit 2
+          fi
         elif command -v deft >/dev/null 2>&1; then
           deft {{.ENGINE_CMD}}
+        elif command -v directive >/dev/null 2>&1; then
+          directive {{.ENGINE_CMD}}
         else
           echo "deft: neither {{.DEFT_ROOT}}/packages/cli/dist/bin.js nor a global deft command is available." >&2
           echo "  Install with: npm i -g @deftai/directive" >&2

package/tasks/ts.yml

@@ -8,21 +8,24 @@ vars:
 tasks:
   build:
     desc: "Build the TypeScript engine monorepo (tsc -b project references, #1717)"
-    dir: '{{.DEFT_ROOT}}'
     cmds:
-      - pnpm run build
+      - task: :engine:pm-run
+        vars:
+          PM_SCRIPT: build
 
   test:
     desc: "Run the TypeScript engine test suite with coverage (vitest, #1717)"
-    dir: '{{.DEFT_ROOT}}'
     cmds:
-      - pnpm run test
+      - task: :engine:pm-run
+        vars:
+          PM_SCRIPT: test
 
   lint:
     desc: "Lint + format-check the TypeScript engine (biome, #1717)"
-    dir: '{{.DEFT_ROOT}}'
     cmds:
-      - pnpm run lint
+      - task: :engine:pm-run
+        vars:
+          PM_SCRIPT: lint
 
   check-lane:
     desc: "Run the TS lane (lint+build+test) when a Node toolchain is present; skip with a notice otherwise (#1530, #1790)."

package/templates/agents-entry.md

@@ -96,23 +96,21 @@ Projects on the legacy `vbrief/` tree are still read-accepted; run `deft migrate
 
 ## Umbrella status reading (#1152 / #2066)
 
-Rationale + cross-references: `.deft/core/docs/analysis/2026-07-02-agents-md-incident-rule-rationale.md` § Umbrella current-shape convention (#1152).
-
 - ! 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.
+Rationale + cross-references: `.deft/core/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`.
+- ! 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/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`.
+Rationale + cross-references: preamble § 5.6 in `.deft/core/templates/agent-prompt-preamble.md` (#2143).
 
 - ! Fetch both the issue body and `repos/<owner>/<repo>/issues/<N>/comments` via REST before concluding what the issue asks for or building a worker dispatch envelope. Read body first, then the comment thread in chronological order.
 - ! `deft issue:ingest` / `task issue:ingest` fetches `/comments` by default and folds the thread into the ingested overview (#2143).
@@ -192,7 +190,7 @@ Override paths (`deft policy:show` / `deft policy:enforce-branches` / `deft poli
 
 ## Platform-conditional rules (PowerShell / Windows)
 
-Platform/tool/runtime-specific rules are lazy-loaded, not rendered here, so they don't crowd context for sessions that can't trigger them (#2157 / #1882). If your session matches a trigger below, load `.deft/core/content/scm/github.md` § "PowerShell platform-conditional rules for agents" **before** the risky operation:
+Platform/tool/runtime-specific rules are lazy-loaded, not rendered here, so they don't crowd context for sessions that can't trigger them (#2157 / #1882). If your session matches a trigger below, load `.deft/core/scm/github.md` § "PowerShell platform-conditional rules for agents" **before** the risky operation:
 
 - ! Editing files with non-ASCII glyphs from PowerShell (especially PS 5.1) -- enforced at commit by `deft verify:encoding` (#798).
 - ! Running shell commands under the Grok Build Windows + pwsh 7+ runtime -- piped/redirected commands leak wrapper text (#1353); PTY-based Warp + Claude are exempt.
@@ -222,7 +220,7 @@ Platform/tool/runtime-specific rules are lazy-loaded, not rendered here, so they
 
 ## Commands
 
-Directive product commands use the `/deft:directive:*` namespace (#418 / #1670). Prior `/deft:*` product forms remain as deprecation-warning aliases — see `content/commands.md` for the full alias table. Cross-product session commands stay at the umbrella `/deft:*` level.
+Directive product commands use the `/deft:directive:*` namespace (#418 / #1670). Prior `/deft:*` product forms remain as deprecation-warning aliases — see `.deft/core/commands.md` for the full alias table. Cross-product session commands stay at the umbrella `/deft:*` level.
 
 **Directive product (`/deft:directive:*`):**