@synity/bitrix-skills 1.3.0

package/src/features/task-sync/commands/install.ts

@@ -0,0 +1,296 @@
+// Install command — copies managed files + merges .claude/settings.json + sets up githooks.
+// Idempotent: re-run is safe. Brownfield-safe: never overwrites user-modified files without --force.
+import { copyFile, chmod } from 'node:fs/promises';
+import { assertNotSymlink } from '../../../lib/fs-safety.js';
+import path from 'node:path';
+import kleur from 'kleur';
+import { execa } from 'execa';
+import type { CliOptions, InstallStats, InstallResult } from '../types.js';
+import { detectProjectRoot, hasGitDir } from '../lib/project-root.js';
+import { loadManifest, resolveAssetsDir } from '../lib/manifest.js';
+import { buildDestMap, type DestEntry } from '../lib/dest-map.js';
+import { fileExists, sha256File, ensureDir } from '../lib/file-ops.js';
+import {
+  BITRIX_HOOKS_TEMPLATE,
+  loadSettingsFile,
+  mergeSettings,
+  writeSettingsFile,
+} from '../lib/settings-merge.js';
+import { addProjectRef } from '../lib/skill-refs.js';
+
+interface InstallContext {
+  cwd: string;
+  assetsDir: string;
+  opts: CliOptions;
+}
+
+export async function installFile(
+  entry: DestEntry,
+  ctx: InstallContext,
+): Promise<InstallResult> {
+  const srcAbs = path.join(ctx.assetsDir, entry.manifestEntry.src);
+  const destAbs = entry.destAbs;
+
+  await assertNotSymlink(destAbs);
+
+  if (await fileExists(destAbs)) {
+    const destSha = await sha256File(destAbs);
+    if (destSha === entry.manifestEntry.sha256) {
+      return 'skipped';
+    }
+    if (!ctx.opts.force) {
+      return 'skipped'; // user-modified — preserve
+    }
+    if (ctx.opts.dryRun) {
+      console.log(`  ${kleur.yellow('[dry-run]')} overwrite ${entry.destRel}`);
+      return 'planned';
+    }
+    await ensureDir(path.dirname(destAbs));
+    await copyFile(srcAbs, destAbs);
+    await chmod(destAbs, entry.manifestEntry.mode);
+    return 'overwritten';
+  }
+
+  if (ctx.opts.dryRun) {
+    console.log(`  ${kleur.yellow('[dry-run]')} copy → ${entry.destRel}`);
+    return 'planned';
+  }
+
+  await ensureDir(path.dirname(destAbs));
+  await copyFile(srcAbs, destAbs);
+  await chmod(destAbs, entry.manifestEntry.mode);
+  return 'copied';
+}
+
+export async function installManifestFiles(
+  entries: DestEntry[],
+  ctx: InstallContext,
+): Promise<InstallStats> {
+  const stats: InstallStats = {
+    copied: 0,
+    skipped: 0,
+    overwritten: 0,
+    planned: 0,
+    filtered: 0,
+    warnings: [],
+  };
+
+  for (const entry of entries) {
+    if (entry.optionalFlag && ctx.opts[entry.optionalFlag]) {
+      stats.filtered += 1;
+      continue;
+    }
+    const result = await installFile(entry, ctx);
+    if (result === 'skipped') {
+      // Differentiate between sha-match-skip vs user-modified-skip via re-check
+      const destSha = (await fileExists(entry.destAbs))
+        ? await sha256File(entry.destAbs)
+        : null;
+      if (destSha && destSha !== entry.manifestEntry.sha256 && !ctx.opts.force) {
+        stats.warnings.push(`skipped (user-modified): ${entry.destRel}`);
+      }
+    }
+    stats[result] += 1;
+  }
+  return stats;
+}
+
+async function mergeSettingsStep(ctx: InstallContext): Promise<{ added: boolean; alreadyMerged: boolean }> {
+  const settingsPath = path.join(ctx.cwd, '.claude/settings.json');
+  const existing = await loadSettingsFile(settingsPath);
+  const merged = mergeSettings(existing, BITRIX_HOOKS_TEMPLATE);
+
+  // Detect "already merged" case: existing already deep-equal to merged.
+  const alreadyMerged = JSON.stringify(existing) === JSON.stringify(merged);
+
+  if (ctx.opts.dryRun) {
+    if (alreadyMerged) {
+      console.log(`  ${kleur.yellow('[dry-run]')} settings.json: already up-to-date`);
+    } else {
+      console.log(`  ${kleur.yellow('[dry-run]')} settings.json: would merge 4 Bitrix hooks`);
+    }
+    return { added: !alreadyMerged, alreadyMerged };
+  }
+
+  if (!alreadyMerged) {
+    await writeSettingsFile(settingsPath, merged);
+  }
+  return { added: !alreadyMerged, alreadyMerged };
+}
+
+async function ensureUfTokensTotal(
+  cwd: string,
+  stats: InstallStats,
+): Promise<void> {
+  const webhookUrl = process.env['BITRIX_WEBHOOK_URL'];
+  if (!webhookUrl) return; // no webhook configured — skip silently
+
+  const libPath = path.join(cwd, '.claude/scripts/bitrix-lib.sh');
+  if (!(await fileExists(libPath))) return;
+
+  // Inline bash: source lib, call task.item.userfield.add, treat ERROR_CORE as success
+  const script = `
+    set -e
+    source "$1"
+    result=$(b24_call "task.item.userfield.add" \
+      "$(jq -n '{PARAMS:{USER_TYPE_ID:"double",FIELD_NAME:"UF_AI_TOKENS_TOTAL",XML_ID:"UF_AI_TOKENS_TOTAL",LABEL:"AI Tokens (cumulative)",SORT:500,MULTIPLE:"N",MANDATORY:"N",SETTINGS:{DEFAULT_VALUE:0,PRECISION:0}}}')")
+    err=$(echo "$result" | jq -r '.error // empty')
+    # ERROR_CORE = already exists → treat as success
+    if [[ -n "$err" && "$err" != "ERROR_CORE" ]]; then
+      echo "warn:$err" >&2
+    fi
+    exit 0
+  `;
+
+  try {
+    const result = await execa('bash', ['-c', script, '--', libPath], {
+      cwd,
+      reject: false,
+      env: { ...process.env },
+    });
+    if (result.stderr && !result.stderr.includes('ERROR_CORE')) {
+      const warnLine = (result.stderr.match(/warn:(.+)/) ?? [])[1];
+      if (warnLine) stats.warnings.push(`UF_AI_TOKENS_TOTAL: ${warnLine.trim()}`);
+    }
+  } catch {
+    stats.warnings.push('UF_AI_TOKENS_TOTAL: ensure skipped (bash error)');
+  }
+}
+
+async function runGitHooksInstall(ctx: InstallContext): Promise<{ run: boolean; warning?: string }> {
+  const hooksScript = path.join(ctx.cwd, '.githooks/install.sh');
+  if (!(await fileExists(hooksScript))) {
+    return { run: false, warning: 'githooks install.sh not found (skipped)' };
+  }
+  if (!(await hasGitDir(ctx.cwd))) {
+    return { run: false, warning: 'no .git/ in project root — skipped githooks setup' };
+  }
+  if (ctx.opts.dryRun) {
+    console.log(`  ${kleur.yellow('[dry-run]')} would run: bash .githooks/install.sh`);
+    return { run: false };
+  }
+  try {
+    await chmod(hooksScript, 0o755);
+    await execa('bash', [hooksScript], { cwd: ctx.cwd, stdio: 'pipe' });
+    return { run: true };
+  } catch (err) {
+    return { run: false, warning: `githooks install failed: ${(err as Error).message}` };
+  }
+}
+
+export async function run(opts: CliOptions): Promise<number> {
+  let cwd: string;
+  try {
+    cwd = await detectProjectRoot(opts.cwd);
+  } catch (err) {
+    console.error(kleur.red(`error: ${(err as Error).message}`));
+    return 2;
+  }
+
+  const assetsDir = resolveAssetsDir();
+  const ctx: InstallContext = { cwd, assetsDir, opts };
+
+  console.log('');
+  console.log(kleur.bold().cyan('  ⚡ bitrix-skills task-sync install'));
+  console.log(kleur.gray(`  project root: ${cwd}`));
+  console.log(kleur.gray(`  assets:       ${assetsDir}`));
+  if (opts.dryRun) console.log(kleur.yellow('  mode: --dry-run (no FS changes)'));
+  console.log('');
+
+  let manifest;
+  try {
+    manifest = await loadManifest();
+  } catch (err) {
+    console.error(kleur.red(`error: ${(err as Error).message}`));
+    return 1;
+  }
+
+  const dests = buildDestMap(manifest, cwd);
+
+  // Step 1: copy managed files
+  let stats: InstallStats;
+  try {
+    stats = await installManifestFiles(dests, ctx);
+  } catch (err) {
+    console.error(kleur.red(`copy error: ${(err as Error).message}`));
+    return 1;
+  }
+
+  // Step 2: merge .claude/settings.json
+  let settingsResult: { added: boolean; alreadyMerged: boolean };
+  try {
+    settingsResult = await mergeSettingsStep(ctx);
+  } catch (err) {
+    console.error(kleur.red(`settings merge error: ${(err as Error).message}`));
+    return 3;
+  }
+
+  // Step 2.5: ensure UF_AI_TOKENS_TOTAL user field exists on TASKS_TASK entity
+  if (!opts.noSkill && !opts.dryRun) {
+    await ensureUfTokensTotal(cwd, stats);
+  }
+
+  // Step 3: run .githooks/install.sh
+  const githooksResult = opts.noGithooks
+    ? { run: false, warning: '--no-githooks: skipped' }
+    : await runGitHooksInstall(ctx);
+
+  // Step 4: register this project as a referrer of the shared user-scope skill.
+  // Skipped under --no-skill (no skill files were copied) and --dry-run.
+  let skillRefCount: number | null = null;
+  if (!opts.noSkill && !opts.dryRun) {
+    try {
+      const refs = await addProjectRef(cwd);
+      skillRefCount = refs.length;
+    } catch (err) {
+      stats.warnings.push(`skill ref registry: ${(err as Error).message}`);
+    }
+  }
+
+  // Summary
+  console.log('');
+  if (opts.dryRun) {
+    const parts = [
+      `${stats.planned} would be copied/overwritten`,
+      `${stats.skipped} skipped`,
+      stats.filtered > 0 ? `${stats.filtered} filtered (--no-* flags)` : null,
+    ].filter(Boolean);
+    console.log(kleur.yellow(`  [dry-run] ${parts.join(', ')}`));
+  } else {
+    const parts = [
+      `${stats.copied} copied`,
+      stats.overwritten > 0 ? `${stats.overwritten} overwritten` : null,
+      `${stats.skipped} skipped`,
+      stats.filtered > 0 ? `${stats.filtered} filtered (--no-* flags)` : null,
+    ].filter(Boolean);
+    console.log(kleur.green(`  ✓ files: ${parts.join(', ')}`));
+  }
+  if (settingsResult.alreadyMerged) {
+    console.log(kleur.gray('  · settings.json: already up-to-date'));
+  } else if (settingsResult.added && !opts.dryRun) {
+    console.log(kleur.green('  ✓ settings.json: 4 Bitrix hooks merged'));
+  }
+  if (githooksResult.run) {
+    console.log(kleur.green('  ✓ git hooks: core.hooksPath = .githooks (local)'));
+  } else if (githooksResult.warning) {
+    console.log(kleur.yellow(`  ! ${githooksResult.warning}`));
+  }
+  if (skillRefCount !== null) {
+    const noun = skillRefCount === 1 ? 'project' : 'projects';
+    console.log(kleur.gray(`  · skill: shared across ${skillRefCount} ${noun}`));
+  }
+  for (const w of stats.warnings) {
+    console.log(kleur.yellow(`  ! ${w}`));
+  }
+
+  if (!opts.dryRun) {
+    console.log('');
+    console.log(kleur.bold('  Next steps:'));
+    console.log('    1. Set TASK_ID in CLAUDE.md (see docs/bitrix-task-sync.md §2)');
+    console.log('    2. Export BITRIX_WEBHOOK_URL in your shell rc');
+    console.log('    3. Run: npx @synity/bitrix-skills verify');
+    console.log('');
+  }
+
+  return 0;
+}

package/src/features/task-sync/commands/uninstall.ts

@@ -0,0 +1,189 @@
+// Uninstall command — removes managed files (only if sha256 matches manifest), cleans settings.
+// Preserves user-modified files + user's other hooks.
+import { unlink } from 'node:fs/promises';
+import path from 'node:path';
+import kleur from 'kleur';
+import { execa } from 'execa';
+import type { CliOptions } from '../types.js';
+import { detectProjectRoot, hasGitDir } from '../lib/project-root.js';
+import { loadManifest } from '../lib/manifest.js';
+import { buildDestMap } from '../lib/dest-map.js';
+import { fileExists, sha256File } from '../lib/file-ops.js';
+import { loadSettingsFile, removeBitrixHooks, writeSettingsFile } from '../lib/settings-merge.js';
+import { clearAllRefs, getRefs, removeProjectRef } from '../lib/skill-refs.js';
+
+export async function run(opts: CliOptions): Promise<number> {
+  let cwd: string;
+  try {
+    cwd = await detectProjectRoot(opts.cwd);
+  } catch (err) {
+    console.error(kleur.red(`error: ${(err as Error).message}`));
+    return 2;
+  }
+
+  console.log('');
+  console.log(kleur.bold().cyan('  ⚡ bitrix-skills task-sync uninstall'));
+  console.log(kleur.gray(`  project root: ${cwd}`));
+  if (opts.dryRun) console.log(kleur.yellow('  mode: --dry-run (no FS changes)'));
+  console.log('');
+
+  let manifest;
+  try {
+    manifest = await loadManifest();
+  } catch (err) {
+    console.error(kleur.red(`error: ${(err as Error).message}`));
+    return 1;
+  }
+
+  const dests = buildDestMap(manifest, cwd);
+  let removed = 0;
+  let preserved = 0;
+  let absent = 0;
+  let filtered = 0;
+  const warnings: string[] = [];
+
+  // Decide skill-file fate up front based on the ref registry.
+  // Skill files at ~/.claude/skills/bitrix-sync-install/ are shared across all
+  // Synity projects on this machine. We only delete them when:
+  //   (a) --remove-skill — user explicitly demands a global wipe, OR
+  //   (b) this is the LAST registered project AND the registry is non-empty.
+  // Empty registry = ambiguous state (skill installed pre-ref-counting?). Treat
+  // as "don't know who else uses it" → preserve unless --remove-skill.
+  const cwdAbs = path.resolve(cwd);
+  const refsBefore = await getRefs();
+  const otherProjects = refsBefore.filter((p) => p !== cwdAbs);
+  const isLastRegisteredReferrer =
+    refsBefore.length > 0 && otherProjects.length === 0;
+  const shouldRemoveSkillFiles =
+    !opts.noSkill && (opts.removeSkill || isLastRegisteredReferrer);
+
+  for (const d of dests) {
+    if (d.category === 'doc' && opts.keepDocs) {
+      filtered += 1;
+      continue;
+    }
+    // User-scope skill is shared across all projects on the machine.
+    // Default = preserve unless we're the last referrer or --remove-skill.
+    if (d.category === 'skill' && !shouldRemoveSkillFiles) {
+      filtered += 1;
+      continue;
+    }
+    // Honor install-time skip flags so uninstall doesn't try to remove
+    // files that were never copied.
+    if (d.optionalFlag && opts[d.optionalFlag]) {
+      filtered += 1;
+      continue;
+    }
+    if (!(await fileExists(d.destAbs))) {
+      absent += 1;
+      continue;
+    }
+    const actual = await sha256File(d.destAbs);
+    if (actual !== d.manifestEntry.sha256) {
+      preserved += 1;
+      warnings.push(`preserved (user-modified): ${d.destRel}`);
+      continue;
+    }
+    if (opts.dryRun) {
+      console.log(`  ${kleur.yellow('[dry-run]')} remove ${d.destRel}`);
+      removed += 1;
+      continue;
+    }
+    await unlink(d.destAbs);
+    removed += 1;
+  }
+
+  // Settings subtraction
+  const settingsPath = path.join(cwd, '.claude/settings.json');
+  let settingsChanged = false;
+  if (await fileExists(settingsPath)) {
+    try {
+      const existing = await loadSettingsFile(settingsPath);
+      const cleaned = removeBitrixHooks(existing);
+      const before = JSON.stringify(existing);
+      const after = JSON.stringify(cleaned);
+      if (before !== after) {
+        settingsChanged = true;
+        if (!opts.dryRun) {
+          await writeSettingsFile(settingsPath, cleaned);
+        }
+      }
+    } catch (err) {
+      warnings.push(`settings.json: ${(err as Error).message}`);
+    }
+  }
+
+  // Mutate skill ref registry. Done after the file loop so dry-run never writes.
+  // --remove-skill nukes the entire ref list (other projects' refs become orphaned
+  // anyway since we deleted shared files). Default just removes this project.
+  let skillRefRemaining: number | null = null;
+  if (!opts.noSkill && !opts.dryRun) {
+    try {
+      if (opts.removeSkill) {
+        await clearAllRefs();
+        skillRefRemaining = 0;
+      } else {
+        const result = await removeProjectRef(cwdAbs);
+        skillRefRemaining = result.remaining;
+      }
+    } catch (err) {
+      warnings.push(`skill ref registry: ${(err as Error).message}`);
+    }
+  }
+
+  // Unset core.hooksPath if pointed to .githooks
+  let hooksPathUnset = false;
+  if (await hasGitDir(cwd)) {
+    try {
+      const { stdout } = await execa('git', ['config', '--local', '--get', 'core.hooksPath'], {
+        cwd,
+        reject: false,
+      });
+      if (stdout.trim() === '.githooks') {
+        if (!opts.dryRun) {
+          await execa('git', ['config', '--local', '--unset', 'core.hooksPath'], { cwd, reject: false });
+        }
+        hooksPathUnset = true;
+      }
+    } catch {
+      // non-fatal
+    }
+  }
+
+  // Summary
+  console.log('');
+  const filteredSuffix = filtered > 0 ? `, ${filtered} filtered (--keep-docs / no --remove-skill / --no-*)` : '';
+  if (opts.dryRun) {
+    console.log(kleur.yellow(`  [dry-run] would remove ${removed} files, preserve ${preserved}, ${absent} already absent${filteredSuffix}`));
+  } else {
+    console.log(kleur.green(`  ✓ files: ${removed} removed, ${preserved} preserved, ${absent} already absent${filteredSuffix}`));
+  }
+  if (settingsChanged) {
+    console.log(kleur.green('  ✓ settings.json: Bitrix hooks removed'));
+  } else {
+    console.log(kleur.gray('  · settings.json: nothing to remove'));
+  }
+  if (hooksPathUnset) {
+    console.log(kleur.green('  ✓ git hooks: core.hooksPath unset'));
+  }
+  if (skillRefRemaining !== null) {
+    if (opts.removeSkill) {
+      console.log(kleur.green('  ✓ skill: ~/.claude/skills/bitrix-sync-install removed (--remove-skill)'));
+    } else if (skillRefRemaining === 0) {
+      console.log(kleur.green('  ✓ skill: last project unlinked, files removed'));
+    } else {
+      const noun = skillRefRemaining === 1 ? 'project' : 'projects';
+      console.log(
+        kleur.gray(
+          `  · skill: preserved (still used by ${skillRefRemaining} other ${noun}); pass --remove-skill to force`,
+        ),
+      );
+    }
+  }
+  for (const w of warnings) {
+    console.log(kleur.yellow(`  ! ${w}`));
+  }
+  console.log('');
+
+  return 0;
+}

package/src/features/task-sync/commands/update.ts

@@ -0,0 +1,11 @@
+// Update command — force re-install of managed files only (preserves user files outside manifest).
+// Equivalent to install --force, but never touches user-modified files outside the manifest scope.
+import type { CliOptions } from '../types.js';
+import * as install from './install.js';
+
+export async function run(opts: CliOptions): Promise<number> {
+  // Update = install with force, preserving the user's other settings + files.
+  // The install command already only touches manifest-managed files; force makes it
+  // overwrite drifted ones.
+  return install.run({ ...opts, force: true });
+}

package/src/features/task-sync/commands/verify.ts

@@ -0,0 +1,141 @@
+// Verify command — drift check + env validation + (optional) live webhook smoke test.
+// Spawns bash to source bitrix-lib.sh + invoke b24_comment, ensuring 1:1 with runtime.
+import path from 'node:path';
+import kleur from 'kleur';
+import { execa } from 'execa';
+import type { CliOptions } from '../types.js';
+import { detectProjectRoot } from '../lib/project-root.js';
+import { loadManifest } from '../lib/manifest.js';
+import { checkDrift } from '../lib/drift-check.js';
+import { findTaskId, isValidTaskId } from '../lib/task-id-finder.js';
+import { fileExists } from '../lib/file-ops.js';
+
+// Replace any occurrence of the webhook URL (and tail token segment) with a placeholder.
+function redactWebhook(text: string): string {
+  let out = text;
+  const url = process.env['BITRIX_WEBHOOK_URL'];
+  if (url) {
+    out = out.split(url).join('<BITRIX_WEBHOOK_URL>');
+    // Also redact bare /rest/<id>/<token>/ patterns in case lib emits parts of the URL.
+    out = out.replace(/\/rest\/\d+\/[A-Za-z0-9]+/g, '/rest/<redacted>');
+  }
+  return out;
+}
+
+export async function run(opts: CliOptions): Promise<number> {
+  let cwd: string;
+  try {
+    cwd = await detectProjectRoot(opts.cwd);
+  } catch (err) {
+    console.error(kleur.red(`error: ${(err as Error).message}`));
+    return 2;
+  }
+
+  console.log('');
+  console.log(kleur.bold().cyan('  ⚡ bitrix-skills task-sync verify'));
+  console.log(kleur.gray(`  project root: ${cwd}`));
+  console.log('');
+
+  // 1. Manifest integrity
+  let manifest;
+  try {
+    manifest = await loadManifest();
+  } catch (err) {
+    console.error(kleur.red(`error: ${(err as Error).message}`));
+    return 1;
+  }
+
+  const drift = await checkDrift(manifest, cwd, {
+    noGithooks: opts.noGithooks,
+    noWorkflow: opts.noWorkflow,
+    noSkill: opts.noSkill,
+  });
+  if (drift.length > 0) {
+    console.error(kleur.red('  ✗ drift detected — run `bitrix-skills update` to fix:'));
+    for (const d of drift) {
+      console.error(`    - ${d.path} (${d.reason})`);
+    }
+    return 4;
+  }
+  console.log(kleur.green('  ✓ manifest: all managed files match expected sha256'));
+
+  // 2. Env: TASK_ID
+  const taskId = await findTaskId(cwd);
+  if (!taskId) {
+    console.error(kleur.red('  ✗ TASK_ID not found in any CLAUDE.md (walk-up from project root)'));
+    console.error(kleur.gray('     add to root or feature CLAUDE.md:\n       ## Bitrix Task\n       TASK_ID: 12345'));
+    return 1;
+  }
+  if (!isValidTaskId(taskId)) {
+    console.error(kleur.red(`  ✗ TASK_ID "${taskId}" is not a valid numeric Bitrix task ID`));
+    console.error(kleur.gray('     expected digits only (e.g. TASK_ID: 12345)'));
+    return 1;
+  }
+  console.log(kleur.green(`  ✓ TASK_ID found: ${taskId}`));
+
+  // 3. Env: BITRIX_WEBHOOK_URL
+  if (!process.env['BITRIX_WEBHOOK_URL']) {
+    console.error(kleur.red('  ✗ BITRIX_WEBHOOK_URL not set in env'));
+    console.error(kleur.gray('     export BITRIX_WEBHOOK_URL="https://your.bitrix24.com/rest/USER_ID/TOKEN/"'));
+    return 2;
+  }
+  console.log(kleur.green('  ✓ BITRIX_WEBHOOK_URL is set'));
+
+  if (opts.quiet) {
+    console.log(kleur.gray('  · --quiet: skipping live webhook test'));
+    console.log('');
+    return 0;
+  }
+
+  // 4. Live smoke test
+  const libPath = path.join(cwd, '.claude/scripts/bitrix-lib.sh');
+  if (!(await fileExists(libPath))) {
+    console.error(kleur.red(`  ✗ ${libPath} missing — run install first`));
+    return 1;
+  }
+
+  const stamp = new Date().toISOString();
+  const message = `🔧 [bitrix-skills verify] ${stamp}`;
+  // Pass libPath/taskId/message as positional args ($1/$2/$3) so they are not
+  // re-parsed by the shell — prevents injection if any value contains metachars.
+  const script = 'set -e; source "$1"; b24_comment "$2" "$3"';
+  const result = await execa('bash', ['-c', script, '--', libPath, taskId, message], {
+    cwd,
+    reject: false,
+  });
+
+  if (result.exitCode !== 0 || !/"result"/.test(result.stdout || '')) {
+    console.error(kleur.red('  ✗ webhook call failed'));
+    if (result.stderr) console.error(kleur.gray(`     stderr: ${redactWebhook(result.stderr).slice(0, 500)}`));
+    if (result.stdout) console.error(kleur.gray(`     stdout: ${redactWebhook(result.stdout).slice(0, 500)}`));
+    return 3;
+  }
+
+  console.log(kleur.green(`  ✓ live webhook OK — comment posted to TASK_ID=${taskId}`));
+
+  // 5. Disk scope probe — file-attach feature degrades gracefully if missing
+  const diskScript = `
+    set -e
+    source "$1"
+    result=$(b24_call "disk.storage.getlist" '{}')
+    err=$(echo "$result" | jq -r '.error // empty')
+    if [[ "$err" == *"insufficient_scope"* || "$err" == *"ACCESS_DENIED"* ]]; then
+      echo "missing_scope"
+    else
+      echo "ok"
+    fi
+  `;
+  const diskResult = await execa('bash', ['-c', diskScript, '--', libPath], {
+    cwd,
+    reject: false,
+  });
+  if ((diskResult.stdout || '').trim() === 'missing_scope') {
+    console.log(kleur.yellow('  ! disk scope missing — file-attach feature degraded'));
+    console.log(kleur.gray('     add "disk" to webhook permissions to enable plan/brainstorm file sync'));
+  } else {
+    console.log(kleur.green('  ✓ disk scope OK — file-attach feature available'));
+  }
+
+  console.log('');
+  return 0;
+}

package/src/features/task-sync/feature.json

@@ -0,0 +1,12 @@
+{
+  "name": "task-sync",
+  "displayName": "Bitrix Task Sync (hooks)",
+  "version": "0.3.0-pre",
+  "target": "project",
+  "description": "AI session sync to Bitrix task chat via hooks",
+  "needs": ["bash-lib"],
+  "requires": {
+    "env": ["BITRIX_WEBHOOK_URL"],
+    "task_id": true
+  }
+}