@cspeach/cli 0.9.0 → 1.0.0

package/dist/skills/promotion-dispatch.js

@@ -1,3 +1,5 @@
+import { basename } from 'node:path';
+import { isAttachableFilename } from '../projects/workspace.js';
 /**
  * Parse `--from @<path>` from a slash-command argument string. The leading `@`
  * is the file-attach convention used elsewhere in the CLI; supports
@@ -22,3 +24,24 @@ export function parseFromFlag(args) {
     const rest = (before + after).replace(/^\s+|\s+$/g, '');
     return { fromPath, rest };
 }
+/**
+ * Forgiveness for the common `--from @<document>` slip.
+ *
+ * `--from` chains a saved `.cspeach.json` envelope into a downstream skill, but
+ * users naturally type it to point at a Word/PDF/text spec ("use this file") —
+ * which used to error with a cryptic "unknown target skill" and cancel the
+ * whole turn. A document is NEVER a valid `--from` source, so when the token is
+ * an attachable doc/text file we silently rewrite `--from @<file>` to a plain
+ * `@<file>` attachment (handled by expandTextFileAttachments) and let the turn
+ * proceed.
+ *
+ * Returns the rewritten message + filename, or null when `--from` should run
+ * normally (no flag, or the token is a bare envelope fragment / *.cspeach.json).
+ */
+export function coerceDocFromFlagToAttachment(message) {
+    const { fromPath } = parseFromFlag(message);
+    if (!fromPath || !isAttachableFilename(fromPath))
+        return null;
+    const rewritten = message.replace(/--from\s+(@(?:"[^"]+"|\S+))/, '$1');
+    return { rewritten, filename: basename(fromPath) };
+}

package/dist/tools/_command-shared.js

@@ -52,23 +52,47 @@ export async function loadSafelist() {
         return new Set(DEFAULT_SAFELIST);
     }
 }
+/**
+ * Build the ordered list of filename extensions to probe for a given
+ * platform. On Windows, PATHEXT extensions (.EXE, .CMD, .BAT, ...) come
+ * BEFORE the bare name — npm drops an extensionless Unix shim next to
+ * `pnpm.cmd` (e.g. ...\npm\pnpm) that is NOT spawnable with shell:false,
+ * so preferring the real .cmd/.exe makes the existence check report a
+ * launchable binary. On Unix, only the bare name (shebang scripts and
+ * ELF binaries spawn directly).
+ *
+ * Exported for tests so the ordering invariant can be asserted without
+ * touching the filesystem.
+ */
+export function executableExtensions(platform, pathextRaw) {
+    if (platform === 'win32') {
+        const pathext = (pathextRaw ?? '.COM;.EXE;.BAT;.CMD')
+            .toLowerCase()
+            .split(';')
+            .filter((e) => e.length > 0);
+        // PATHEXT extensions FIRST, bare name LAST. The bare name still gets
+        // probed (commands that ship only an extensionless binary remain
+        // findable) but loses to a co-located .exe/.cmd.
+        return [...pathext, ''];
+    }
+    return [''];
+}
 /**
  * Resolve a bare command name to an absolute executable path by walking
- * PATH. Tries the bare name + PATHEXT extensions on Windows. Returns
- * null if nothing matches anywhere on PATH. Identical to Chunk 3B's
- * inlined function — extracted verbatim.
+ * PATH. Tries PATHEXT extensions before the bare name on Windows. Returns
+ * null if nothing matches anywhere on PATH.
+ *
+ * This is used ONLY as a pre-flight "is it installed?" existence check so
+ * the tool can return a friendly "not installed" error. The ACTUAL spawn
+ * goes through cross-spawn with the bare command name — cross-spawn does
+ * its own PATH + PATHEXT resolution and invokes .cmd via cmd.exe with
+ * correct per-arg escaping (which Node's spawn(shell:false) refuses to do
+ * since CVE-2024-27980). `platform`/`pathext` overridable for tests.
  */
-export async function resolveExecutable(name) {
+export async function resolveExecutable(name, platform = process.platform, pathext = process.env.PATHEXT) {
     const PATH = process.env.PATH ?? process.env.Path ?? '';
     const dirs = PATH.split(path.delimiter).filter((d) => d.length > 0);
-    let extensions;
-    if (process.platform === 'win32') {
-        const pathext = (process.env.PATHEXT ?? '.COM;.EXE;.BAT;.CMD').toLowerCase().split(';');
-        extensions = ['', ...pathext];
-    }
-    else {
-        extensions = [''];
-    }
+    const extensions = executableExtensions(platform, pathext);
     for (const dir of dirs) {
         for (const ext of extensions) {
             const candidate = path.join(dir, name + ext);

package/dist/tools/_filesystem-shared.js

@@ -9,11 +9,125 @@
  */
 import * as path from 'node:path';
 import { promises as fsPromises } from 'node:fs';
-/** Phase 3 sensitive in-root paths — refused by all filesystem tools. */
-export const BLOCKED_PREFIXES = ['.cspeach', '.env', '.git', '.cspeach-design'];
 /**
- * True if `realAbsPath` falls under one of BLOCKED_PREFIXES relative to root.
- * Caller should refuse the operation when `blocked` is true.
+ * Phase 3 sensitive in-root directory prefixes — refused by all filesystem
+ * tools. Matched as `rel === prefix` or `rel` starts with `prefix + '/'`.
+ *
+ * NOTE: the `.env` family is handled separately (by BASENAME, see
+ * BLOCKED_BASENAME_RE) so that `.env.local`, `.env.production`, etc. — the
+ * files that actually hold secrets in JS projects — are caught too. It is
+ * NOT in this list.
+ */
+export const BLOCKED_PREFIXES = ['.cspeach', '.git', '.cspeach-design'];
+/**
+ * Skill working subdirectories under `.cspeach/` that are CARVED OUT of the
+ * denylist so the upgrade/cca/modernize/test skills can read AND write their
+ * own detail files (e.g. `.cspeach/upgrades/ZTEST_..._.json`). The namespace
+ * cleanup that moved working files from `.abapforge/<domain>/` to
+ * `.cspeach/<domain>/` would otherwise be defeated by the `.cspeach` prefix
+ * block. See the carve-out in isDenylistedPath for the exact predicate.
+ */
+export const CSPEACH_WORK_SUBDIRS = ['cca', 'upgrades', 'modernize', 'tests'];
+/**
+ * Phase 3 sensitive BASENAMES — refused regardless of directory depth.
+ *
+ * Matches `.env` exactly or `.env.<suffix>` (e.g. `.env.local`,
+ * `.env.production`, `.env.development`, `.env.test`). The `(\.|$)` boundary
+ * means `.environment` / `.envrc` are NOT caught — only the real dotenv
+ * family. Case-insensitive (NTFS/APFS resolve `.ENV` to the same inode).
+ */
+export const BLOCKED_BASENAME_RE = /^\.env(\.|$)/i;
+/**
+ * Human-readable summary of the denylist for error messages.
+ * Note: `.cspeach/{cca,upgrades,modernize,tests}/` working files are permitted
+ * (skill detail files) — only the rest of `.cspeach/` is blocked.
+ */
+export const DENYLIST_DESCRIPTION = [...BLOCKED_PREFIXES, '.env*'].join(', ');
+/**
+ * Executable / script file extensions the filesystem write tools refuse to
+ * create. Defense-in-depth: shell_exec / background_run only run a safelisted
+ * set of commands, but cross-spawn resolves bare names cwd-first on Windows.
+ * If the model could write `<safelisted>.cmd` (e.g. git.cmd) into the project
+ * tree it could shadow a real PATH binary. Spawning the absolute PATH-resolved
+ * path already neutralizes that at the spawn site; this denylist independently
+ * stops the executable shim from ever being planted in the first place — see
+ * blockedExecutableExtension, which normalizes Windows filename quirks (trailing
+ * dots/spaces, alternate data streams) so a name like `git.cmd ` or `git.cmd::$DATA`
+ * cannot slip a real `git.cmd` onto disk past the extension check.
+ *
+ * Legitimate project scaffolding (Fiori writes .js/.json/.xml/.properties/
+ * .yaml/.ts) never needs these, so the block does not impede normal work.
+ *
+ * Case-insensitive — NTFS/APFS resolve `.CMD` to the same file as `.cmd`.
+ */
+export const BLOCKED_EXECUTABLE_EXTS = new Set([
+    '.cmd', '.bat', '.com', '.exe', '.ps1', '.sh', '.msi', '.scr',
+]);
+/** Human-readable summary of the executable-extension block for error messages. */
+export const EXECUTABLE_EXT_DESCRIPTION = [...BLOCKED_EXECUTABLE_EXTS].join(', ');
+/** Sentinel ext returned when the basename carries a `:` (ADS / drive-relative). */
+const BLOCKED_STREAM_SENTINEL = ':stream';
+/**
+ * Normalize a Windows basename the way the filesystem does on access:
+ *   - strip ALL trailing dots and spaces (`git.cmd `, `git.cmd.`, `git.cmd...`
+ *     all open the file `git.cmd`).
+ * Returns the normalized basename. A name that is entirely dots/spaces
+ * collapses to '' (which extname() then reports as no extension — safe).
+ */
+function normalizeWindowsBasename(base) {
+    return base.replace(/[. ]+$/, '');
+}
+/**
+ * Returns the offending extension (lowercased, with leading dot) if `targetPath`
+ * names a file the write tools must refuse, else null. Used by file_write /
+ * file_edit to refuse planting an executable shim.
+ *
+ * Accepts a full path or a bare basename (both call sites pass a resolved
+ * absolute path; the directory part is irrelevant — only the basename decides).
+ *
+ * Two pre-extname normalizations close Windows filename-normalization bypasses
+ * that would otherwise land an executable-named file on disk while slipping
+ * past a naive `path.extname` check:
+ *
+ *   1. Trailing dots/spaces — Windows strips these on access, so `git.cmd `
+ *      and `git.cmd.` / `git.cmd...` all resolve to `git.cmd`. We strip them
+ *      from the basename before taking the extension.
+ *
+ *   2. A `:` anywhere in the basename — alternate data stream (`git.cmd:foo`,
+ *      `git.cmd::$DATA`) or drive-relative path. Either way the on-disk file
+ *      is executable-named; reject outright. (A drive letter's `:` lives in
+ *      the DIRECTORY part — e.g. basename of `C:\proj\foo.js` is `foo.js` —
+ *      so legit absolute paths never false-positive here.)
+ */
+export function blockedExecutableExtension(targetPath) {
+    const rawBase = path.basename(targetPath);
+    // (2) Alternate data stream / drive-relative — the basename must never carry ':'.
+    if (rawBase.includes(':'))
+        return BLOCKED_STREAM_SENTINEL;
+    // (1) Strip trailing dots/spaces the way Windows does on access, THEN take ext.
+    const base = normalizeWindowsBasename(rawBase);
+    const ext = path.extname(base).toLowerCase();
+    return BLOCKED_EXECUTABLE_EXTS.has(ext) ? ext : null;
+}
+/**
+ * True if `realAbsPath` is denylisted relative to root — either it falls under
+ * one of BLOCKED_PREFIXES (directory prefixes) or its basename is in the
+ * `.env` family. Caller should refuse the operation when `blocked` is true.
+ *
+ * CARVE-OUT — the four skill working subdirectories under `.cspeach/`
+ * (CSPEACH_WORK_SUBDIRS = cca/upgrades/modernize/tests) are ALLOWED so skills
+ * can read+write their own detail files. A path is carved out (NOT blocked)
+ * iff ALL hold:
+ *   1. its root-relative path (lowercased, '/'-separated) starts with
+ *      `.cspeach/<sub>/` for some <sub> in CSPEACH_WORK_SUBDIRS — i.e. it is
+ *      STRICTLY INSIDE one of those subdirs (the subdir entry itself is not
+ *      carved out), AND
+ *   2. its basename does NOT end with `.cspeach.json` (those envelopes are
+ *      CLI-owned — direct writes stay blocked), AND
+ *   3. its basename is NOT in the `.env` secret family (BLOCKED_BASENAME_RE).
+ * The carve-out short-circuits ONLY the `.cspeach` prefix. `.git`,
+ * `.cspeach-design`, the `.cspeach` root, non-work subdirs, and `.env*`
+ * everywhere else remain blocked.
  */
 export function isDenylistedPath(realAbsPath, root) {
     const relFromRoot = path.relative(path.resolve(root), realAbsPath).replace(/\\/g, '/');
@@ -24,12 +138,33 @@ export function isDenylistedPath(realAbsPath, root) {
     // `relFromRoot` keeps its ORIGINAL case so callers can log what the model
     // actually requested.
     const relLower = relFromRoot.toLowerCase();
+    const base = path.basename(relFromRoot);
+    const baseLower = base.toLowerCase();
+    // ── CARVE-OUT: .cspeach/<work-subdir>/… — short-circuits ONLY .cspeach. ──
+    // Must be strictly INSIDE a work subdir, not a CLI-owned envelope, and not
+    // an .env secret. Placed before the prefix loop so it can return early, but
+    // gated so it can never bypass .git / .cspeach-design / the .env block.
+    for (const sub of CSPEACH_WORK_SUBDIRS) {
+        if (relLower.startsWith('.cspeach/' + sub + '/')) {
+            if (!baseLower.endsWith('.cspeach.json') && !BLOCKED_BASENAME_RE.test(base)) {
+                return { blocked: false, relFromRoot };
+            }
+            break; // inside a work subdir but failed an exclusion → fall through to block
+        }
+    }
+    // Directory-prefix denylist (.cspeach, .git, .cspeach-design).
     for (const prefix of BLOCKED_PREFIXES) {
         const prefixLower = prefix.toLowerCase();
         if (relLower === prefixLower || relLower.startsWith(prefixLower + '/')) {
             return { blocked: true, relFromRoot };
         }
     }
+    // Basename denylist — the .env family at ANY depth (.env, .env.local, …).
+    // Using the basename (not a prefix) is what catches `.env.production` while
+    // still excluding `.environment-notes.md` and `.envrc`.
+    if (BLOCKED_BASENAME_RE.test(base)) {
+        return { blocked: true, relFromRoot };
+    }
     return { blocked: false, relFromRoot };
 }
 export class PathOutsideRootError extends Error {

package/dist/tools/_flag.js

@@ -15,7 +15,32 @@
 export const TOOL_FLAG_PREFIX = 'CSPEACH_TOOL_';
 /** One-shot per process — set of flag-names we've already warned about. */
 const warnedFlags = new Set();
+/**
+ * In-memory force-enable set, mirroring renderer/tty.ts's headless-override
+ * pattern: consulted BEFORE env detection. A startup hook (REPL + one-shot)
+ * calls `enableToolFlags([...])` when the persisted `local_files` config key
+ * is true, so the flag-gated filesystem tools become visible to listTools()
+ * without the user exporting CSPEACH_TOOL_* env vars.
+ *
+ * Stored by lowercase tool name (the same name listTools()/registerTool use),
+ * so `enableToolFlags(['file_read'])` and `isToolFlagOn('FILE_READ')` agree.
+ */
+const overrideEnabled = new Set();
+/** Force-enable the named tools' flags for this process (override beats env). */
+export function enableToolFlags(toolNames) {
+    for (const name of toolNames)
+        overrideEnabled.add(name.toLowerCase());
+}
+/** Clear all in-memory flag overrides. Test-resettable; safe at runtime too. */
+export function clearToolFlagOverrides() {
+    overrideEnabled.clear();
+}
 export function isToolFlagOn(toolName) {
+    // Override wins: a startup-applied force-enable makes the tool visible
+    // regardless of env. The env path below still runs for un-overridden tools,
+    // preserving the CSPEACH_TOOL_<NAME>=on dogfood mechanism + misconfig warn.
+    if (overrideEnabled.has(toolName.toLowerCase()))
+        return true;
     const flag = `${TOOL_FLAG_PREFIX}${toolName.toUpperCase()}`;
     const raw = process.env[flag];
     if (raw === undefined)

package/dist/tools/approval.js

@@ -1,6 +1,9 @@
+import chalk from 'chalk';
 import { registerTool } from './index.js';
+import { isHeadless } from '../renderer/tty.js';
 import { effectiveRisk } from '../approvals/risk-floor.js';
-import { mintApprovalId } from '../approvals/jwt.js';
+import { mintChangeApproval } from '../approvals/jwt.js';
+import { canonicalApprovalObject } from '../approvals/canonical.js';
 import { renderPlanGate, renderPerChangeApprovalV3 } from '../approvals/render.js';
 import { loadConfig } from '../config/loader.js';
 import { maybeShowAutoApproveNag } from '../approvals/approval-prompt.js';
@@ -20,6 +23,22 @@ import { markPlanGateApproved } from '../repl/rule8-detector.js';
  */
 export async function handleAdvisoryApproval(args, _ctx) {
     const render = renderAdvisoryProposal(args);
+    // B5 (2026-06-11) — headless: the advisory prompt blocks on stdin that
+    // will never answer. Render the proposal (it IS the run's deliverable —
+    // the developer reads the captured output and applies manually), skip
+    // the prompt, and report a headless-specific directive. NEVER 'applied':
+    // nobody confirmed anything.
+    if (isHeadless()) {
+        console.log(render.displayText);
+        console.error(chalk.dim('headless: advisory proposal recorded in output — no prompt, developer applies manually'));
+        return {
+            content: JSON.stringify({
+                advisory_outcome: 'skipped',
+                headless: true,
+                ai_directive: 'Advisory mode (headless run): the proposal has been rendered into the run output for the developer to review and apply manually later. Nobody confirmed it. Do not attempt any write operations. Summarise what you proposed and continue.',
+            }),
+        };
+    }
     const outcome = await promptAdvisory({
         displayText: render.displayText,
         clipboardText: render.clipboardText,
@@ -88,24 +107,25 @@ registerTool({
         const changes = args.changes;
         const declared = args.risk;
         const eff = effectiveRisk(declared, changes, riskCtx);
-        // Progressive-disclosure: offer to upgrade never→low on first low-risk encounter.
-        await maybeShowAutoApproveNag({ sapAlias: ctx.sapAlias, effectiveRisk: eff.level });
-        // Refresh cfg so this approval benefits from a just-enabled auto_approve.
-        cfg = await loadConfig();
-        sapCfg = cfg.sap[ctx.sapAlias];
-        riskCtx.autoApprovePolicy = sapCfg?.auto_approve ?? 'never';
+        // Progressive-disclosure: offer to upgrade never→low on first low-risk
+        // encounter. B5: skipped in headless — the nag's raw-mode keypress wait
+        // would hang on piped/closed stdin just like any other prompt.
+        if (!isHeadless()) {
+            await maybeShowAutoApproveNag({ sapAlias: ctx.sapAlias, effectiveRisk: eff.level });
+            // Refresh cfg so this approval benefits from a just-enabled auto_approve.
+            cfg = await loadConfig();
+            sapCfg = cfg.sap[ctx.sapAlias];
+            riskCtx.autoApprovePolicy = sapCfg?.auto_approve ?? 'never';
+        }
         // Auto-approve caps — never auto-approve at high, cap change count per risk level.
         const autoApproveAllowed = ((sapCfg?.auto_approve === 'low' && eff.level === 'low' && changes.length <= 5) ||
             (sapCfg?.auto_approve === 'medium' && (eff.level === 'low' || eff.level === 'medium') && changes.length <= 2));
         if (autoApproveAllowed) {
             const ids = [];
             for (const c of changes) {
-                ids.push(await mintApprovalId({
-                    object: c.object,
-                    type: c.type,
-                    op: c.op,
-                    session_id: ctx.session.id,
-                }));
+                // Task A3: mint via the canonical path — the JWT stores the same
+                // object string the write tools' validators will compare against.
+                ids.push(await mintChangeApproval(c, ctx.session.id));
             }
             // Tell Rule 8 the user has already covered this batch — they
             // configured auto-approve, so no per-dispatch re-prompts.
@@ -120,6 +140,29 @@ registerTool({
                 }),
             };
         }
+        // B5 (2026-06-11) — headless fail-fast. Everything below this point
+        // prompts on stdin (plan gate, per-change approvals) and would hang a
+        // headless run forever. The headless policy NEVER auto-approves writes:
+        // the only non-interactive approval path is the user's own pre-configured
+        // auto_approve (handled above — it asks nothing). Return an error RESULT
+        // so the model can wrap up gracefully instead of the process hanging.
+        if (isHeadless()) {
+            console.error(chalk.red('headless: approval requested but headless runs cannot approve writes — ' +
+                'use advisory mode (write_mode = "advisory-only") or run interactively.'));
+            return {
+                content: JSON.stringify({
+                    approved: false,
+                    headless: true,
+                    reason: 'headless_no_approval',
+                    message: 'Headless run: writes cannot be approved without a user at the terminal, and headless runs never auto-approve. ' +
+                        'No approval IDs were minted — do not attempt any write operations. ' +
+                        'Summarise the proposed changes so the user can re-run interactively or switch write_mode to "advisory-only".',
+                    effective_risk: eff.level,
+                    raised_by: eff.raisedBy,
+                }),
+                is_error: true,
+            };
+        }
         // Plan-gate: for multi-change requests, ask once whether to apply all,
         // review each, or cancel. Apply-all is the default and the happy path —
         // it skips the redundant per-change prompts that produced the "3 prompts
@@ -159,13 +202,16 @@ registerTool({
         const rejections = [];
         const autoApproveActivateFor = new Set();
         const autoSkipActivateFor = new Set();
+        // Sibling matching keys are canonicalized (Task A3) so a decorated modify
+        // row ("ZBP_FOO (testclasses include)") still pairs with its bare-named
+        // activate sibling ("ZBP_FOO").
         const writeKeys = new Set();
         for (const c of changes) {
             if (c.op === 'modify' || c.op === 'create')
-                writeKeys.add(`${c.type}:${c.object}`);
+                writeKeys.add(`${c.type}:${canonicalApprovalObject(c.object)}`);
         }
         for (const c of changes) {
-            const objKey = `${c.type}:${c.object}`;
+            const objKey = `${c.type}:${canonicalApprovalObject(c.object)}`;
             let outcome;
             if (skipPerChangeGates) {
                 outcome = { approved: true };
@@ -182,12 +228,9 @@ registerTool({
             if (outcome.approved) {
                 if (c.op === 'modify' || c.op === 'create')
                     autoApproveActivateFor.add(objKey);
-                approvalIds.push(await mintApprovalId({
-                    object: c.object,
-                    type: c.type,
-                    op: c.op,
-                    session_id: ctx.session.id,
-                }));
+                // Task A3: mint via the canonical path (same code path the write
+                // tools' validators compare against).
+                approvalIds.push(await mintChangeApproval(c, ctx.session.id));
             }
             else {
                 if (outcome.reason === '__cancel_turn__') {

package/dist/tools/ask-question.js

@@ -25,8 +25,55 @@ import chalk from 'chalk';
 import { registerTool } from './index.js';
 import { input, select, checkbox } from '@inquirer/prompts';
 import { withInquirer } from '../repl/inquirer-guard.js';
-import { shouldUseInk } from '../renderer/tty.js';
+import { shouldUseInk, isHeadless } from '../renderer/tty.js';
 import { askQuestionEmitter } from '../ui/ask-question-emitter.js';
+/**
+ * Label heuristic for rule 2 of pickHeadlessChoices: a string counts as
+ * "recommended" only when it contains the word AND that word is not part of
+ * a negation — skills write both "RAP (recommended)" and "SEGW (not
+ * recommended)" and the latter must NEVER win the auto-pick.
+ */
+function labelSaysRecommended(s) {
+    return /\brecommended\b/i.test(s) && !/\b(?:not|non|never)[\s-]+recommended\b/i.test(s);
+}
+/**
+ * B5 (2026-06-11) — headless auto-pick rule for choice/multi questions.
+ *
+ * Rule order (the fired rule is reported so logs and the tool result are
+ * honest about WHY an option was picked):
+ *   1. `recommended: true` on one or more choices → those choices
+ *      (rule: 'recommended').
+ *   2. No explicit flag, but a label/value contains the word "recommended"
+ *      (skills frequently write "RAP (recommended)") → those choices
+ *      (rule: 'recommended-label'). Negated forms ("not recommended",
+ *      "non-recommended", "never recommended") do NOT match.
+ *   3. Nothing marked → the FIRST option (rule: 'first-option').
+ *
+ * For kind=choice only the first match is taken; for kind=multi the whole
+ * recommended set is taken (or the first option when nothing is marked).
+ *
+ * Contract: `choices` must be non-empty — the handler guards with
+ * `choices.length > 0` before calling (an empty array means there is nothing
+ * to pick and the headless path returns the free-text error instead). An
+ * empty array here is a programming error, so this throws rather than
+ * returning `[undefined]`.
+ *
+ * Exported for unit testing.
+ */
+export function pickHeadlessChoices(kind, choices) {
+    if (choices.length === 0) {
+        throw new Error('pickHeadlessChoices requires at least one choice — callers must guard (see ask_question handler)');
+    }
+    const flagged = choices.filter((c) => c.recommended === true);
+    if (flagged.length > 0) {
+        return { picked: kind === 'multi' ? flagged : [flagged[0]], rule: 'recommended' };
+    }
+    const labelled = choices.filter((c) => labelSaysRecommended(c.label) || labelSaysRecommended(c.value));
+    if (labelled.length > 0) {
+        return { picked: kind === 'multi' ? labelled : [labelled[0]], rule: 'recommended-label' };
+    }
+    return { picked: [choices[0]], rule: 'first-option' };
+}
 registerTool({
     name: 'ask_question',
     description: "Ask the user a clarifying question and get their answer. Use this for ANY user-decision point in a skill conversation — object names, design choices, approval checkpoints, etc. The CLI renders a formatted prompt, waits for the user's answer, and returns it as the tool result. Prefer this over emitting a text question — it is the only reliable mechanism for mid-turn user interaction.",
@@ -59,6 +106,10 @@ registerTool({
                     properties: {
                         value: { type: 'string', description: 'Machine value returned if the user picks this.' },
                         label: { type: 'string', description: 'Human-readable label shown in the picker.' },
+                        recommended: {
+                            type: 'boolean',
+                            description: 'Mark the option you would recommend. In headless (non-interactive) runs this option is auto-picked; in interactive runs it is informational only.',
+                        },
                     },
                     required: ['value', 'label'],
                 },
@@ -71,9 +122,50 @@ registerTool({
         const question = String(args.question);
         const context = args.context ? String(args.context) : undefined;
         const kind = args.kind;
-        const choices = Array.isArray(args.choices)
-            ? args.choices
-            : [];
+        const choices = Array.isArray(args.choices) ? args.choices : [];
+        // B5 (2026-06-11) — headless answer policy (defects D1/D1b). In a
+        // headless run (one-shot / piped stdin) NO prompt may ever block on
+        // stdin: battery S2 Pass A stalled forever on exactly this path.
+        //   - choice/multi WITH options: auto-pick (recommended > recommended-
+        //     label > first option), log to stderr, and tell the model via
+        //     `auto_answered: true` that the user did NOT really answer.
+        //   - free text (or choice/multi without options): no auto-answer is
+        //     possible — return an error RESULT to the model (not a hard exit)
+        //     so it can finish gracefully with documented assumptions, the way
+        //     S2 Pass B completed when answers were supplied up front.
+        if (isHeadless()) {
+            if ((kind === 'choice' || kind === 'multi') && choices.length > 0) {
+                const { picked, rule } = pickHeadlessChoices(kind, choices);
+                const answer = picked.map((c) => c.value).join(',');
+                console.error(chalk.dim(`headless: auto-answered '${question}' → '${answer}' (${rule})`));
+                return {
+                    content: JSON.stringify({
+                        id,
+                        kind,
+                        answer,
+                        headless: true,
+                        auto_answered: true,
+                        auto_answer_rule: rule,
+                        note: 'Headless run: the user did not actually answer — this option was auto-selected ' +
+                            `(${rule}). Proceed with it and clearly note the assumption in your final output.`,
+                    }),
+                };
+            }
+            console.error(chalk.yellow(`headless: cannot answer free-text question '${question}' — ` +
+                'provide this detail in the prompt or run interactively.'));
+            return {
+                content: JSON.stringify({
+                    id,
+                    kind,
+                    headless: true,
+                    error: 'headless_unanswerable',
+                    message: `Headless run: no user is available to answer this free-text question: "${question}". ` +
+                        'Either proceed with a sensible assumption and CLEARLY document it in your final output, ' +
+                        'or finish by telling the user to include this detail in the prompt or run interactively.',
+                }),
+                is_error: true,
+            };
+        }
         // 2026-05-01 redesign: when the LLM provides choices, use a real
         // arrow-key picker (select / checkbox) instead of free-text input.
         // The previous "always free-text, smart-resolve digits" pattern produced

package/dist/tools/capability/tool.js

@@ -0,0 +1,74 @@
+/**
+ * `system_capability` — the data-driven capability gate behind Pillar A.
+ *
+ * Given a capability id (cds.viewEntity | rap.managed | abap.filterExpr |
+ * abap.inlineData) or a raw ABAP feature name, returns a yes/no/with-fallback
+ * verdict for the CONNECTED SAP release, read out of the committed ABAP
+ * feature-matrix snapshot. Skills call this instead of hardcoding version
+ * prose like "FILTER needs 7.50".
+ *
+ * Read-only: it consults system-info (which caches/queries CVERS once) and a
+ * static snapshot — it never writes to SAP. Flag-gated with the other
+ * local-build tools (rides the `local_build` switch via LOCAL_BUILD_TOOLS).
+ *
+ * See docs/superpowers/specs/2026-06-24-revision-aware-cspeach-design.md.
+ */
+import { registerTool } from '../index.js';
+import { getSapSystemInfo } from '../../sap/system-info.js';
+import { loadCapabilityMatrix } from '../../sap/capability-matrix.js';
+import { resolveCapability, CAPABILITY_REGISTRY, } from '../../sap/capability.js';
+function isRegistryId(s) {
+    return Object.prototype.hasOwnProperty.call(CAPABILITY_REGISTRY, s);
+}
+async function systemCapabilityHandler(args, ctx) {
+    const capability = args?.capability;
+    if (typeof capability !== 'string' || capability.trim() === '') {
+        return { content: 'error: capability (non-empty string) is required', is_error: true };
+    }
+    const info = await getSapSystemInfo(ctx.adt, ctx.sapAlias);
+    if (!info) {
+        // Release undetectable. Build a minimal verdict-like JSON: with-fallback
+        // when the caller asked for a registry id that HAS a fallback, else no.
+        const fallback = isRegistryId(capability)
+            ? CAPABILITY_REGISTRY[capability].fallback || undefined
+            : undefined;
+        const feature = isRegistryId(capability) ? CAPABILITY_REGISTRY[capability].feature : capability;
+        const verdict = {
+            capability,
+            feature,
+            status: fallback ? 'with-fallback' : 'no',
+            reason: 'SAP release could not be detected — verify the system manually before relying on this feature',
+            release: 'unknown',
+            column: null,
+            source: 'matrix-snapshot',
+            ...(fallback ? { fallback } : {}),
+        };
+        return { content: JSON.stringify(verdict) };
+    }
+    const verdict = resolveCapability(info, loadCapabilityMatrix(), capability);
+    return { content: JSON.stringify(verdict) };
+}
+registerTool({
+    name: 'system_capability',
+    description: 'Returns yes / no / with-fallback for whether the CONNECTED SAP release supports a given ABAP '
+        + 'capability, read out of the committed ABAP feature-matrix snapshot — so skills stop hardcoding '
+        + 'version prose like "FILTER needs 7.50". Pass a capability gate id (cds.viewEntity | rap.managed | '
+        + 'abap.filterExpr | abap.inlineData) OR a raw ABAP feature name from the matrix. The verdict carries '
+        + 'the feature consulted, the matrix column used, the reason, and (only for with-fallback) a concrete '
+        + 'fallback instruction. Read-only — never writes to SAP.',
+    isMutating: false,
+    category: 'sap',
+    flagGated: true,
+    input_schema: {
+        type: 'object',
+        properties: {
+            capability: {
+                type: 'string',
+                description: 'A capability gate id (cds.viewEntity | rap.managed | abap.filterExpr | abap.inlineData) '
+                    + 'OR a raw ABAP feature name from the matrix.',
+            },
+        },
+        required: ['capability'],
+    },
+    handler: systemCapabilityHandler,
+});