@vodmal/vdx-cli 0.2.1 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vodmal/vdx-cli",
-  "version": "0.2.1",
+  "version": "0.4.0",
   "description": "vdx — unified lifecycle interface (up/down/build/test/check/fix) + versioned maturity audit with drift detection. Pairs with the vdx Claude Code plugin.",
   "keywords": [
     "vdx",
@@ -39,7 +39,9 @@
     "audit": "tsx src/index.ts audit",
     "smoke": "bash smoke.sh",
     "typecheck": "tsc --noEmit",
-    "test": "tsc --noEmit"
+    "test": "vitest run",
+    "test:unit": "vitest run tests/unit",
+    "coverage": "vitest run --coverage"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
@@ -51,7 +53,9 @@
   "devDependencies": {
     "@types/js-yaml": "^4.0.9",
     "@types/node": "^22.0.0",
-    "typescript": "^5.6.0"
+    "@vitest/coverage-v8": "^4.1.7",
+    "typescript": "^5.6.0",
+    "vitest": "^4.1.7"
   },
   "publishConfig": {
     "access": "public"

package/rubric/vdx-rubric.yaml

@@ -11,7 +11,7 @@ schema_version: "0.2"
 
 metadata:
   name: vdx-rubric-vodmal
-  version: "0.2.2"
+  version: "0.3.1"
   description: "Personal maturity rubric for multi-stack projects (vodmal)"
   owner: vodmal
   homepage: "https://github.com/vodmal/vdx-rubric"
@@ -534,3 +534,84 @@ axes:
           file_contains:
             paths: [misc/traefik-global/README.md, misc/traefik-global/start.sh]
             pattern: "@v\\d+\\.\\d+\\.\\d+"          # semver pin
+
+  - id: release-artifact
+    class: supporting
+    description: "Publish-readiness: metadata completeness + entry points + registry signals (O34, v0.3.0). Применяется только к проектам, заявляющим publish-intent (O35, v0.3.1) — иначе excluded."
+    applies_to: [node, php, ruby, python]
+    # O35 (v0.3.1): ось применяется только если проект декларирует намерение
+    # публиковать артефакт. Чистые app'ы (private:true в package.json или
+    # composer type:project) → excluded.
+    applies_when:
+      any_of:
+        # Node-сторона: НЕ private И есть хоть один entry-point/publish-signal.
+        - all_of:
+            - has_file: package.json
+            - not:
+                config_value: { path: package.json, jsonpath: "private", equals: true }
+            - any_of:
+                - config_value: { path: package.json, jsonpath: "publishConfig", op: present }
+                - config_value: { path: package.json, jsonpath: "bin",           op: present }
+                - config_value: { path: package.json, jsonpath: "main",          op: present }
+                - config_value: { path: package.json, jsonpath: "exports",       op: present }
+                - config_value: { path: package.json, jsonpath: "module",        op: present }
+        # PHP-сторона: composer.json есть, name задан, type ≠ project (project = app).
+        - all_of:
+            - has_file: composer.json
+            - config_value: { path: composer.json, jsonpath: "name", op: present }
+            - not:
+                config_value: { path: composer.json, jsonpath: "type", op: equals, equals: "project" }
+    storage: level
+    default_target: L4
+    fact_sources:
+      - package.json
+      - composer.json
+      - LICENSE
+      - LICENSE.md
+      - LICENSE.txt
+    levels:
+      L1:
+        requires:
+          any_of:
+            - all_of:
+                - config_value: { path: package.json, jsonpath: "name",    op: present }
+                - config_value: { path: package.json, jsonpath: "version", op: present }
+                - config_value: { path: package.json, jsonpath: "license", op: present }
+            - all_of:
+                - config_value: { path: composer.json, jsonpath: "name",    op: present }
+                - config_value: { path: composer.json, jsonpath: "license", op: present }
+      L2:
+        requires:
+          any_of:
+            - all_of:
+                - config_value: { path: package.json, jsonpath: "description", op: present }
+                - config_value: { path: package.json, jsonpath: "repository",  op: present }
+                - any_of:
+                    - has_file: LICENSE
+                    - has_file: LICENSE.md
+                    - has_file: LICENSE.txt
+            - all_of:
+                - config_value: { path: composer.json, jsonpath: "description", op: present }
+                - any_of:
+                    - has_file: LICENSE
+                    - has_file: LICENSE.md
+      L3:
+        requires:
+          any_of:
+            - all_of:
+                - config_value: { path: package.json, jsonpath: "files", op: present }
+                - any_of:
+                    - config_value: { path: package.json, jsonpath: "bin",     op: present }
+                    - config_value: { path: package.json, jsonpath: "main",    op: present }
+                    - config_value: { path: package.json, jsonpath: "exports", op: present }
+            - all_of:
+                - config_value: { path: composer.json, jsonpath: "autoload", op: present }
+                - config_value: { path: composer.json, jsonpath: "type",     op: present }
+      L4:
+        requires:
+          any_of:
+            - all_of:
+                - config_value: { path: package.json, jsonpath: "publishConfig", op: present }
+                - config_value: { path: package.json, jsonpath: "homepage",      op: present }
+                - config_value: { path: package.json, jsonpath: "bugs",          op: present }
+            - config_value: { path: composer.json, jsonpath: "extra.publish", op: present }

package/src/audit.ts

@@ -2,6 +2,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import type { Rubric, LevelName } from './rubric.ts';
 import { findSubPackages, stackForDir, type Ctx } from './facts.ts';
+import { evalPredicate } from './evaluator.ts';
 import type { Override, VdxManifest } from './manifest.ts';
 import { evalAxis, projectLevel, type AxisResult } from './scoring.ts';
 
@@ -115,6 +116,16 @@ export function audit(
       });
       continue;
     }
+    if (axis.applies_when && !evalPredicate(axis.applies_when, evalCtx)) {
+      perAxis.push({
+        axis_id: axis.id,
+        class: axis.class,
+        achieved: 'L0',
+        target: axis.default_target,
+        drift_kind: 'excluded',
+      });
+      continue;
+    }
     const achieved = evalAxis(axis, evalCtx);
     const ov = overrideByAxis.get(axis.id);
     const target = (ov?.target as LevelName) ?? axis.default_target;

package/src/index.ts

@@ -6,6 +6,13 @@ import { autoDetectStack, type Ctx } from './facts.ts';
 import { audit } from './audit.ts';
 import { reportMarkdown, reportJson } from './report.ts';
 import { planInit, writeInit, renderPlanSummary } from './init.ts';
+import {
+  planPublish,
+  renderPublishPlan,
+  executePublish,
+  type BumpKind,
+  type PublishOptions,
+} from './publish.ts';
 import { resolveDefaultRubric } from './defaults.ts';
 
 const DEFAULT_RUBRIC = resolveDefaultRubric();
@@ -13,8 +20,9 @@ const DEFAULT_RUBRIC = resolveDefaultRubric();
 function usage(): never {
   process.stderr.write(
     `Usage:
-  vdx audit <project_path> [--rubric <path>] [--stack <stack>] [--json]
-  vdx init  <project_path> [--baseline <ref>] [--dry-run] [--force]
+  vdx audit   <project_path> [--rubric <path>] [--stack <stack>] [--json]
+  vdx init    <project_path> [--stack <id>] [--baseline <ref>] [--dry-run] [--force]
+  vdx publish <patch|minor|major> [--dry-run] [--force]
 `,
   );
   process.exit(1);
@@ -86,10 +94,19 @@ function cmdInit(opts: ParsedArgs): void {
 
   const baselineFlag = opts.flags.baseline;
   const baseline = typeof baselineFlag === 'string' ? baselineFlag : undefined;
-  const plan = planInit(projectRoot, baseline ? { baseline } : {});
+  const stackFlag = opts.flags.stack;
+  const stackOverride = typeof stackFlag === 'string' ? stackFlag : undefined;
+  const plan = planInit(projectRoot, {
+    ...(baseline ? { baseline } : {}),
+    ...(stackOverride ? { stack: stackOverride } : {}),
+  });
 
   process.stdout.write(renderPlanSummary(plan));
 
+  for (const w of plan.warnings) {
+    process.stderr.write(`\n⚠ ${w}\n`);
+  }
+
   if (opts.flags['dry-run']) {
     process.stderr.write('\n[dry-run] mise.toml / AGENTS.md не записаны.\n');
     return;
@@ -105,7 +122,62 @@ function cmdInit(opts: ParsedArgs): void {
   }
 }
 
+function cmdPublish(opts: ParsedArgs): void {
+  const bumpArg = opts.positionals[0];
+  if (!bumpArg || !['patch', 'minor', 'major'].includes(bumpArg)) {
+    process.stderr.write(
+      'Usage: vdx publish <patch|minor|major> [--dry-run] [--force]\n',
+    );
+    process.exit(1);
+  }
+  const bump = bumpArg as BumpKind;
+  const projectRoot = process.cwd();
+
+  const manifest = loadManifest(projectRoot);
+  const overrides = loadOverrides(projectRoot);
+  const rubric = loadRubric(DEFAULT_RUBRIC);
+  const stack = manifest?.stack || autoDetectStack(projectRoot);
+  const ctx: Ctx = { projectRoot, stack, cache: new Map() };
+  const baselineRef = manifest?.baseline ?? `file://${DEFAULT_RUBRIC}`;
+  const auditResult = audit(rubric, ctx, overrides, baselineRef, manifest);
+
+  const planOpts: PublishOptions = {
+    projectRoot,
+    bump,
+    dryRun: Boolean(opts.flags['dry-run']),
+    force: Boolean(opts.flags.force),
+  };
+
+  let plan;
+  try {
+    plan = planPublish(planOpts, auditResult, ctx);
+  } catch (e: any) {
+    process.stderr.write(`error: ${e?.message ?? String(e)}\n`);
+    process.exit(2);
+  }
+
+  process.stdout.write(renderPublishPlan(plan));
+
+  if (planOpts.dryRun) {
+    process.stderr.write('\n[dry-run] не выполнено.\n');
+    return;
+  }
+
+  if (!plan.preflightPassed && !planOpts.force) {
+    process.stderr.write('\nerror: pre-flight failed (use --force to bypass)\n');
+    process.exit(2);
+  }
+
+  try {
+    executePublish(plan);
+  } catch (e: any) {
+    process.stderr.write(`\nerror: ${e?.message ?? String(e)}\n`);
+    process.exit(3);
+  }
+}
+
 const parsed = parseArgs(process.argv);
 if (parsed.cmd === 'audit') cmdAudit(parsed);
 else if (parsed.cmd === 'init') cmdInit(parsed);
+else if (parsed.cmd === 'publish') cmdPublish(parsed);
 else usage();

package/src/init.ts

@@ -7,20 +7,72 @@ import {
   readText,
   listAllTasks,
   autoDetectStack,
+  findSubPackages,
+  type SubPackage,
 } from './facts.ts';
 
 export const STANDARD_VERBS = ['up', 'down', 'build', 'test', 'check', 'fix'] as const;
 export type Verb = (typeof STANDARD_VERBS)[number];
 
-export const DEFAULT_BASELINE = 'github.com/VoDmAl/vdx-rubric-vodmal@v0.2.2';
+export const DEFAULT_BASELINE = 'github.com/VoDmAl/vdx-rubric-vodmal@v0.3.1';
 
 const VERB_ALIASES: Record<Verb, string[]> = {
-  up: ['docker:up', 'docker-up', 'docker:up:detached', 'start'],
+  up: ['docker:up', 'docker-up', 'docker:up:detached', 'start', 'dev', 'serve'],
   down: ['docker:down', 'docker-down', 'stop'],
-  build: ['docker:build', 'build:prod', 'build-prod', 'build:dev', 'build-dev', 'build:assets'],
-  test: ['phpunit', 'test:unit', 'test-unit', 'test:unit:phpunit', 'jest', 'vitest'],
-  check: ['lint', 'check:config', 'check:before:commit', 'check:code:static', 'check:code:lint'],
-  fix: ['fix:ecs', 'format', 'lint:fix'],
+  build: [
+    'docker:build',
+    'build:prod',
+    'build-prod',
+    'build:dev',
+    'build-dev',
+    'build:assets',
+    'compile',
+    'dist',
+  ],
+  test: [
+    'phpunit',
+    'pest',
+    'test:unit',
+    'test-unit',
+    'test:unit:phpunit',
+    'tests',
+    'unit',
+    'jest',
+    'vitest',
+    'mocha',
+    'ava',
+    'spec',
+    'coverage',
+  ],
+  check: [
+    'lint',
+    'check:before:commit',
+    'check:before:push',
+    'check:config',
+    'check:code:static',
+    'check:code:lint',
+    'typecheck',
+    'tsc',
+    'eslint',
+    'prettier:check',
+    'format:check',
+    'qa',
+    'phpstan',
+    'psalm',
+  ],
+  fix: [
+    'fix:ecs',
+    'fix:rector',
+    'format',
+    'lint:fix',
+    'eslint:fix',
+    'prettier',
+    'prettier:write',
+    'prettier:fix',
+    'format:write',
+    'cs-fix',
+    'cs:fix',
+  ],
 };
 
 const VERB_PREFIX_GROUPS: Record<Verb, string[]> = {
@@ -32,15 +84,41 @@ const VERB_PREFIX_GROUPS: Record<Verb, string[]> = {
   fix: ['fix:', 'fix-'],
 };
 
+// Suffix-based monorepo fallback: lets us pick up `server:test`, `api:lint`, etc.
+// when no exact/alias/prefix-group match exists.
+const VERB_SUFFIX_GROUPS: Record<Verb, string[]> = {
+  up: [':up', '-up'],
+  down: [':down', '-down'],
+  build: [':build', '-build'],
+  test: [':test', '-test'],
+  check: [':check', '-check', ':lint', ':typecheck'],
+  fix: [':fix', '-fix', ':format'],
+};
+
+export type MatchReason = 'exact' | 'alias' | 'prefix-group' | 'suffix-group' | 'not-found';
+
 export interface VerbMapping {
   verb: Verb;
   nativeTask: string | null;
   runCommand: string | null;
+  reason: MatchReason;
+  /** Other candidate tasks that also matched but weren't chosen — useful for tuning. */
+  alternatives: string[];
+}
+
+export interface VerbMatch {
+  task: string | null;
+  reason: MatchReason;
+  alternatives: string[];
 }
 
 export interface InitPlan {
   projectRoot: string;
   stack: string;
+  /** Was `stack` derived from autoDetectStack (false) or supplied via --stack (true). */
+  stackOverridden: boolean;
+  /** Non-null only when stack === 'meta' and resolved a single nested manifest. */
+  primarySubpackage: string | null;
   pkgManager: 'composer' | 'npm' | 'pnpm' | 'yarn' | null;
   tools: Record<string, string>;
   mappings: VerbMapping[];
@@ -49,6 +127,8 @@ export interface InitPlan {
   agentsMdPath: string;
   agentsMdContent: string;
   baseline: string;
+  /** Human-readable advisories for the user — printed to stderr by the CLI. */
+  warnings: string[];
 }
 
 function detectNodePackageManager(projectRoot: string): 'pnpm' | 'yarn' | 'npm' {
@@ -67,6 +147,15 @@ function renderRunCommand(task: string, stack: string, projectRoot: string): str
   return task;
 }
 
+function renderRunCommandInSubpackage(
+  task: string,
+  subStack: string,
+  subAbs: string,
+  subRel: string,
+): string {
+  return `cd ${subRel} && ${renderRunCommand(task, subStack, subAbs)}`;
+}
+
 function pickPrefixGroup(prefixes: string[], tasks: Set<string>, verb: Verb): string | null {
   if (prefixes.length === 0) return null;
   // Prefer entries that look like a canonical "prod/dist/release" first, then any.
@@ -89,12 +178,74 @@ function pickPrefixGroup(prefixes: string[], tasks: Set<string>, verb: Verb): st
   return candidates[0] ?? null;
 }
 
-export function mapVerb(verb: Verb, tasks: Set<string>): string | null {
-  if (tasks.has(verb)) return verb;
-  for (const alt of VERB_ALIASES[verb]) {
-    if (tasks.has(alt)) return alt;
+function collectPrefixCandidates(prefixes: string[], tasks: Set<string>, verb: Verb): string[] {
+  if (prefixes.length === 0) return [];
+  const candidates: string[] = [];
+  for (const t of tasks) {
+    if (t === verb) continue;
+    for (const pfx of prefixes) {
+      if (t.startsWith(pfx)) {
+        candidates.push(t);
+        break;
+      }
+    }
   }
-  return pickPrefixGroup(VERB_PREFIX_GROUPS[verb], tasks, verb);
+  return candidates;
+}
+
+function collectSuffixCandidates(suffixes: string[], tasks: Set<string>, verb: Verb): string[] {
+  if (suffixes.length === 0) return [];
+  const candidates: string[] = [];
+  for (const t of tasks) {
+    if (t === verb) continue;
+    for (const sfx of suffixes) {
+      if (t.endsWith(sfx)) {
+        candidates.push(t);
+        break;
+      }
+    }
+  }
+  return candidates;
+}
+
+export function selectVerbTask(verb: Verb, tasks: Set<string>): VerbMatch {
+  // 1) exact match wins; siblings (aliases / prefix-group) reported as alternatives.
+  if (tasks.has(verb)) {
+    const alts = new Set<string>();
+    for (const a of VERB_ALIASES[verb]) if (tasks.has(a)) alts.add(a);
+    for (const c of collectPrefixCandidates(VERB_PREFIX_GROUPS[verb], tasks, verb)) alts.add(c);
+    return { task: verb, reason: 'exact', alternatives: [...alts].sort() };
+  }
+
+  // 2) alias hit (curated common alternates per stack).
+  const aliasHits = VERB_ALIASES[verb].filter((a) => tasks.has(a));
+  if (aliasHits.length > 0) {
+    const [chosen, ...rest] = aliasHits;
+    return { task: chosen!, reason: 'alias', alternatives: rest.slice().sort() };
+  }
+
+  // 3) prefix-group with canonical hint (prod/release/all preferred, then shortest).
+  const prefixCandidates = collectPrefixCandidates(VERB_PREFIX_GROUPS[verb], tasks, verb);
+  if (prefixCandidates.length > 0) {
+    const chosen = pickPrefixGroup(VERB_PREFIX_GROUPS[verb], tasks, verb)!;
+    const alts = prefixCandidates.filter((c) => c !== chosen).sort();
+    return { task: chosen, reason: 'prefix-group', alternatives: alts };
+  }
+
+  // 4) suffix-group (monorepo fallback: `server:test` -> verb 'test').
+  const suffixCandidates = collectSuffixCandidates(VERB_SUFFIX_GROUPS[verb], tasks, verb);
+  if (suffixCandidates.length > 0) {
+    suffixCandidates.sort((a, b) => a.length - b.length);
+    const [chosen, ...rest] = suffixCandidates;
+    return { task: chosen!, reason: 'suffix-group', alternatives: rest.slice().sort() };
+  }
+
+  return { task: null, reason: 'not-found', alternatives: [] };
+}
+
+/** Kept for back-compat with potential external callers; prefer `selectVerbTask`. */
+export function mapVerb(verb: Verb, tasks: Set<string>): string | null {
+  return selectVerbTask(verb, tasks).task;
 }
 
 function collectTools(ctx: Ctx): Record<string, string> {
@@ -135,12 +286,23 @@ export function renderMiseToml(
   mappings: VerbMapping[],
   stack: string,
   baseline: string,
+  primarySubpackage: string | null = null,
 ): string {
   const out: string[] = [];
   out.push('# Generated by vdx init. The [vdx] block is metadata for vdx audit.');
   out.push('# Lifecycle verbs follow the vdx contract: up/down/build/test/check/fix.');
   out.push('');
 
+  if (stack === 'unknown' || stack === 'monorepo') {
+    out.push(
+      '# TODO(vdx): stack auto-detection вернул "' +
+        stack +
+        '". Замени на php/node/go/python/meta',
+    );
+    out.push('#   и заполни [tasks.*] блоки руками, либо перегенери: vdx init . --stack <id>.');
+    out.push('');
+  }
+
   if (Object.keys(tools).length > 0) {
     out.push('[tools]');
     for (const [k, v] of Object.entries(tools)) {
@@ -151,6 +313,10 @@ export function renderMiseToml(
 
   for (const m of mappings) {
     if (!m.runCommand) continue;
+    if (m.reason !== 'exact' || m.alternatives.length > 0) {
+      const altPart = m.alternatives.length > 0 ? `; alt: ${m.alternatives.join(', ')}` : '';
+      out.push(`# vdx: matched "${m.nativeTask}" via ${m.reason}${altPart}`);
+    }
     out.push(`[tasks.${m.verb}]`);
     out.push(`description = ${quoteToml(VERB_DESCRIPTIONS[m.verb])}`);
     out.push(`run = ${quoteToml(m.runCommand)}`);
@@ -161,6 +327,9 @@ export function renderMiseToml(
   out.push('schema_version = "0.2"');
   out.push(`baseline = ${quoteToml(baseline)}`);
   out.push(`stack = ${quoteToml(stack)}`);
+  if (primarySubpackage) {
+    out.push(`primary_subpackage = ${quoteToml(primarySubpackage)}`);
+  }
   const verbsList = mappings
     .filter((m) => m.runCommand)
     .map((m) => quoteToml(m.verb))
@@ -217,36 +386,99 @@ export function buildAgentsMd(existing: string | null, section: string): string
   return existing + sep + section + '\n';
 }
 
-export function planInit(projectRoot: string, opts: { baseline?: string } = {}): InitPlan {
-  const stack = autoDetectStack(projectRoot);
-  const ctx: Ctx = { projectRoot, stack, cache: new Map() };
-  const tasks = listAllTasks(ctx);
+export function planInit(
+  projectRoot: string,
+  opts: { baseline?: string; stack?: string } = {},
+): InitPlan {
+  const detectedStack = autoDetectStack(projectRoot);
+  const stackOverridden = opts.stack !== undefined && opts.stack !== detectedStack;
+  const stack = opts.stack ?? detectedStack;
+  const warnings: string[] = [];
+
+  // For meta-stack — try to resolve a single nested subpackage and scan it for tasks.
+  let primarySubpackage: string | null = null;
+  let scanRoot = projectRoot;
+  let scanStack = stack;
+
+  if (stack === 'meta') {
+    const subs: SubPackage[] = findSubPackages(projectRoot);
+    if (subs.length === 1) {
+      primarySubpackage = subs[0]!.relPath;
+      scanRoot = path.join(projectRoot, primarySubpackage);
+      scanStack = subs[0]!.stack;
+    } else if (subs.length === 0) {
+      warnings.push(
+        'stack="meta", но nested manifest не найден. mise.toml будет иметь пустой verbs[]; ' +
+          'заполни [tasks.*] руками.',
+      );
+    } else {
+      const list = subs.map((s) => `${s.relPath}(${s.stack})`).join(', ');
+      warnings.push(
+        `stack="meta", найдено несколько subpackages: ${list}. ` +
+          'primary_subpackage не выбран; укажи его руками в [vdx] блоке.',
+      );
+    }
+  } else if (!stackOverridden && (detectedStack === 'unknown' || detectedStack === 'monorepo')) {
+    if (detectedStack === 'unknown') {
+      warnings.push(
+        'autoDetectStack вернул "unknown" — в корне нет manifest и нет subpackages. ' +
+          'Передай --stack <id> (php|node|go|python|meta) либо отредактируй mise.toml вручную.',
+      );
+    } else {
+      const subs = findSubPackages(projectRoot);
+      const list = subs.map((s) => `${s.relPath}(${s.stack})`).join(', ');
+      warnings.push(
+        `autoDetectStack вернул "monorepo": ${list}. ` +
+          'Передай --stack <id> чтобы выбрать конкретный стек, либо --stack meta + укажи primary_subpackage.',
+      );
+    }
+  }
+
+  const scanCtx: Ctx = { projectRoot: scanRoot, stack: scanStack, cache: new Map() };
+  const tasks = listAllTasks(scanCtx);
 
   const mappings: VerbMapping[] = STANDARD_VERBS.map((verb) => {
-    const native = mapVerb(verb, tasks);
+    const sel = selectVerbTask(verb, tasks);
+    let runCommand: string | null = null;
+    if (sel.task) {
+      runCommand =
+        primarySubpackage !== null
+          ? renderRunCommandInSubpackage(sel.task, scanStack, scanRoot, primarySubpackage)
+          : renderRunCommand(sel.task, stack, projectRoot);
+    }
     return {
       verb,
-      nativeTask: native,
-      runCommand: native ? renderRunCommand(native, stack, projectRoot) : null,
+      nativeTask: sel.task,
+      runCommand,
+      reason: sel.reason,
+      alternatives: sel.alternatives,
     };
   });
 
-  const tools = collectTools(ctx);
+  // tools читаем из root независимо: для PHP/Node корневой manifest часто
+  // содержит engines/require php; для meta-проектов вынос tool-версий в
+  // root mise.toml — общая практика.
+  const rootCtx: Ctx = { projectRoot, stack, cache: new Map() };
+  const tools = collectTools(rootCtx);
   const baseline = opts.baseline ?? DEFAULT_BASELINE;
-  const miseTomlContent = renderMiseToml(tools, mappings, stack, baseline);
+  const miseTomlContent = renderMiseToml(tools, mappings, stack, baseline, primarySubpackage);
 
   const agentsMdPath = path.join(projectRoot, 'AGENTS.md');
-  const existingAgents = fileExists(ctx, 'AGENTS.md') ? readText(ctx, 'AGENTS.md') : null;
+  const existingAgents = fileExists(rootCtx, 'AGENTS.md') ? readText(rootCtx, 'AGENTS.md') : null;
   const section = renderAgentsCommandsSection(mappings, baseline);
   const agentsMdContent = buildAgentsMd(existingAgents, section);
 
   let pkgManager: InitPlan['pkgManager'] = null;
-  if (stack === 'php') pkgManager = 'composer';
-  else if (stack === 'node') pkgManager = detectNodePackageManager(projectRoot);
+  const pmStack = primarySubpackage ? scanStack : stack;
+  const pmRoot = primarySubpackage ? scanRoot : projectRoot;
+  if (pmStack === 'php') pkgManager = 'composer';
+  else if (pmStack === 'node') pkgManager = detectNodePackageManager(pmRoot);
 
   return {
     projectRoot,
     stack,
+    stackOverridden,
+    primarySubpackage,
     pkgManager,
     tools,
     mappings,
@@ -255,6 +487,7 @@ export function planInit(projectRoot: string, opts: { baseline?: string } = {}):
     agentsMdPath,
     agentsMdContent,
     baseline,
+    warnings,
   };
 }
 
@@ -272,10 +505,23 @@ export function renderPlanSummary(plan: InitPlan): string {
   const lines: string[] = [];
   lines.push(`# vdx init plan`);
   lines.push('');
-  lines.push(`- **Project**: ${plan.projectRoot}`);
-  lines.push(`- **Stack**: ${plan.stack}`);
+  lines.push(
+    `- **Project**: ${plan.projectRoot}`,
+  );
+  lines.push(
+    `- **Stack**: ${plan.stack}${plan.stackOverridden ? ' (via --stack)' : ''}`,
+  );
+  if (plan.primarySubpackage) {
+    lines.push(`- **Primary subpackage**: ${plan.primarySubpackage}`);
+  }
   if (plan.pkgManager) lines.push(`- **Package manager**: ${plan.pkgManager}`);
   lines.push(`- **Baseline**: ${plan.baseline}`);
+  if (plan.warnings.length > 0) {
+    lines.push('');
+    lines.push('## ⚠ Warnings');
+    lines.push('');
+    for (const w of plan.warnings) lines.push(`- ${w}`);
+  }
   if (Object.keys(plan.tools).length > 0) {
     const toolStr = Object.entries(plan.tools)
       .map(([k, v]) => `${k}=${v}`)
@@ -285,19 +531,33 @@ export function renderPlanSummary(plan: InitPlan): string {
   lines.push('');
   lines.push('## Verb mappings');
   lines.push('');
-  lines.push('| Verb | Native task | Generated `run` |');
-  lines.push('|------|-------------|-----------------|');
+  lines.push('| Verb | Native task | Reason | Generated `run` |');
+  lines.push('|------|-------------|--------|-----------------|');
   for (const m of plan.mappings) {
     if (m.runCommand) {
-      lines.push(`| \`${m.verb}\` | \`${m.nativeTask}\` | \`${m.runCommand}\` |`);
+      lines.push(
+        `| \`${m.verb}\` | \`${m.nativeTask}\` | ${m.reason} | \`${m.runCommand}\` |`,
+      );
     } else {
-      lines.push(`| \`${m.verb}\` | _(not found)_ | _(skipped)_ |`);
+      lines.push(`| \`${m.verb}\` | _(not found)_ | not-found | _(skipped)_ |`);
     }
   }
   lines.push('');
+  const withAlts = plan.mappings.filter((m) => m.alternatives.length > 0);
+  if (withAlts.length > 0) {
+    lines.push('### Alternatives considered');
+    lines.push('');
+    for (const m of withAlts) {
+      const alts = m.alternatives.map((a) => `\`${a}\``).join(', ');
+      lines.push(
+        `- \`${m.verb}\` chose \`${m.nativeTask}\` (${m.reason}); also matched: ${alts}`,
+      );
+    }
+    lines.push('');
+  }
   const unmatched = plan.mappings.filter((m) => !m.runCommand).map((m) => m.verb);
   if (unmatched.length > 0) {
-    lines.push(`> Not mapped: ${unmatched.join(', ')}. Add тиски в \`mise.toml\` вручную.`);
+    lines.push(`> Not mapped: ${unmatched.join(', ')}. Добавь тиски в \`mise.toml\` вручную.`);
     lines.push('');
   }
   lines.push('## Generated mise.toml');

package/src/mcp-server.ts

@@ -156,7 +156,7 @@ function recordSuccessPath(input: {
 
   doc.vdx = doc.vdx ?? {
     schema_version: '0.2',
-    baseline: 'github.com/VoDmAl/vdx-rubric-vodmal@v0.2.1',
+    baseline: 'github.com/VoDmAl/vdx-rubric-vodmal@v0.3.1',
     stack: autoDetectStack(PROJECT_ROOT),
   };
   doc.vdx.verbs = input.verbs.map((v) => v.name);

package/src/publish.ts

@@ -0,0 +1,364 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { execFileSync } from 'node:child_process';
+import type { AuditResult } from './audit.ts';
+import { stackForDir, type Ctx } from './facts.ts';
+
+export type BumpKind = 'patch' | 'minor' | 'major';
+
+export interface PublishOptions {
+  projectRoot: string;
+  bump: BumpKind;
+  dryRun: boolean;
+  force: boolean;
+}
+
+export interface PreflightCheck {
+  name: string;
+  ok: boolean;
+  message: string;
+}
+
+export interface PublishPlan {
+  projectRoot: string;
+  stack: string;
+  packageName: string;
+  currentVersion: string;
+  newVersion: string;
+  bump: BumpKind;
+  packageJsonPath: string;
+  preflight: PreflightCheck[];
+  preflightPassed: boolean;
+  delegatedToMise: boolean;
+}
+
+export function bumpSemver(current: string, kind: BumpKind): string {
+  const m = current.match(/^(\d+)\.(\d+)\.(\d+)/);
+  if (!m) throw new Error(`Cannot parse semver "${current}"`);
+  let major = parseInt(m[1]!, 10);
+  let minor = parseInt(m[2]!, 10);
+  let patch = parseInt(m[3]!, 10);
+  if (kind === 'major') {
+    major += 1;
+    minor = 0;
+    patch = 0;
+  } else if (kind === 'minor') {
+    minor += 1;
+    patch = 0;
+  } else {
+    patch += 1;
+  }
+  return `${major}.${minor}.${patch}`;
+}
+
+export function compareSemver(a: string, b: string): number {
+  const norm = (s: string) =>
+    s.replace(/^v/, '').split(/[.\-+]/).map((p) => parseInt(p, 10) || 0);
+  const pa = norm(a);
+  const pb = norm(b);
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    const av = pa[i] ?? 0;
+    const bv = pb[i] ?? 0;
+    if (av !== bv) return av < bv ? -1 : 1;
+  }
+  return 0;
+}
+
+function isGitWorkingTreeClean(projectRoot: string): { ok: boolean; detail: string } {
+  try {
+    const out = execFileSync('git', ['status', '--porcelain'], {
+      cwd: projectRoot,
+      encoding: 'utf8',
+    });
+    if (out.trim() === '') return { ok: true, detail: 'OK' };
+    const lines = out.trim().split('\n');
+    const sample = lines.slice(0, 3).join(', ');
+    return { ok: false, detail: `${lines.length} uncommitted file(s) — ${sample}` };
+  } catch {
+    return { ok: false, detail: 'not a git repo (or git not available)' };
+  }
+}
+
+function fetchPublishedVersion(packageName: string): string | null {
+  try {
+    const out = execFileSync('npm', ['view', packageName, 'version'], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    return out.trim() || null;
+  } catch (e: any) {
+    const stderr = String(e?.stderr ?? e?.message ?? '');
+    if (stderr.includes('E404') || stderr.includes('404 Not Found')) return null;
+    throw new Error(`npm view failed: ${stderr.split('\n')[0] ?? stderr}`);
+  }
+}
+
+function checkMiseOverride(projectRoot: string): boolean {
+  const miseToml = path.join(projectRoot, 'mise.toml');
+  if (!fs.existsSync(miseToml)) return false;
+  try {
+    const text = fs.readFileSync(miseToml, 'utf8');
+    // Lightweight check — a [tasks.publish] section header is unambiguous
+    // enough for the delegation gate; no need for full TOML parsing here.
+    return /^\[tasks\.publish\b/m.test(text);
+  } catch {
+    return false;
+  }
+}
+
+function resolvePackageJsonPath(projectRoot: string, audit: AuditResult): string {
+  const subpkg = audit.primary_subpackage;
+  const root = subpkg ? path.join(projectRoot, subpkg) : projectRoot;
+  return path.join(root, 'package.json');
+}
+
+export function planPublish(
+  opts: PublishOptions,
+  audit: AuditResult,
+  ctx: Ctx,
+): PublishPlan {
+  if (checkMiseOverride(opts.projectRoot)) {
+    return {
+      projectRoot: opts.projectRoot,
+      stack: ctx.stack,
+      packageName: '(delegated)',
+      currentVersion: '',
+      newVersion: '',
+      bump: opts.bump,
+      packageJsonPath: '',
+      preflight: [
+        {
+          name: 'mise-override',
+          ok: true,
+          message: '[tasks.publish] present in mise.toml — delegating to mise',
+        },
+      ],
+      preflightPassed: true,
+      delegatedToMise: true,
+    };
+  }
+
+  // Resolve effective stack: prefer subpackage stack if primary_subpackage is set
+  // (meta-projects publishing a nested lib, e.g. vdx itself with primary_subpackage=cli).
+  const subpkg = audit.primary_subpackage;
+  const effectiveStack = subpkg
+    ? stackForDir(path.join(opts.projectRoot, subpkg))
+    : ctx.stack;
+
+  if (effectiveStack !== 'node') {
+    throw new Error(
+      `vdx publish: only "node" stack is supported in the MVP (Шаг X). ` +
+        `Effective stack: "${effectiveStack}" (root: "${ctx.stack}"${
+          subpkg ? `, subpackage: "${subpkg}"` : ''
+        }). PHP/Python come in Шаг X.2.`,
+    );
+  }
+
+  const pkgJsonPath = resolvePackageJsonPath(opts.projectRoot, audit);
+  if (!fs.existsSync(pkgJsonPath)) {
+    throw new Error(`vdx publish: package.json not found at ${pkgJsonPath}`);
+  }
+
+  const pkg = JSON.parse(fs.readFileSync(pkgJsonPath, 'utf8'));
+  const packageName: string = pkg.name ?? '(unnamed)';
+  const currentVersion: string = pkg.version ?? '0.0.0';
+  const newVersion = bumpSemver(currentVersion, opts.bump);
+
+  const preflight: PreflightCheck[] = [];
+
+  const tree = isGitWorkingTreeClean(opts.projectRoot);
+  preflight.push({
+    name: 'working-tree-clean',
+    ok: tree.ok,
+    message: tree.detail,
+  });
+
+  const raAxis = audit.per_axis.find((a) => a.axis_id === 'release-artifact');
+  const isExcluded = raAxis?.drift_kind === 'excluded';
+  preflight.push({
+    name: 'lib-intent (applies_when)',
+    ok: !!raAxis && !isExcluded,
+    message: !raAxis
+      ? 'release-artifact axis missing from rubric'
+      : isExcluded
+        ? 'release-artifact axis excluded — this looks like an app, not a library. ' +
+          'Use [tasks.publish] in mise.toml if you really need vdx publish here.'
+        : 'OK (axis applies → lib-intent)',
+  });
+
+  const raLevel = raAxis?.achieved ?? 'L0';
+  const raLevelInt = parseInt(raLevel.slice(1), 10) || 0;
+  preflight.push({
+    name: 'release-artifact >= L3',
+    ok: raLevelInt >= 3,
+    message:
+      raLevelInt >= 3
+        ? `OK (release-artifact ${raLevel})`
+        : `release-artifact at ${raLevel}, need >= L3. Add files[], main/exports, license in package.json.`,
+  });
+
+  let published: string | null = null;
+  let registryError: string | null = null;
+  try {
+    published = fetchPublishedVersion(packageName);
+  } catch (e: any) {
+    registryError = e?.message ?? String(e);
+  }
+  if (registryError) {
+    preflight.push({
+      name: 'registry-collision',
+      ok: false,
+      message: `could not query npm registry: ${registryError}`,
+    });
+  } else if (published === null) {
+    preflight.push({
+      name: 'registry-collision',
+      ok: true,
+      message: `first publish (no prior version on registry)`,
+    });
+  } else {
+    const cmp = compareSemver(newVersion, published);
+    preflight.push({
+      name: 'registry-collision',
+      ok: cmp > 0,
+      message:
+        cmp > 0
+          ? `OK (registry @ ${published}, new ${newVersion})`
+          : `registry @ ${published} ≥ new ${newVersion}; pick a higher bump`,
+    });
+  }
+
+  const preflightPassed = preflight.every((c) => c.ok);
+
+  return {
+    projectRoot: opts.projectRoot,
+    stack: ctx.stack,
+    packageName,
+    currentVersion,
+    newVersion,
+    bump: opts.bump,
+    packageJsonPath: pkgJsonPath,
+    preflight,
+    preflightPassed,
+    delegatedToMise: false,
+  };
+}
+
+/**
+ * Execute the publish pipeline. Order is transactional:
+ *   1. bump package.json in-place (reversible by file restore).
+ *   2. `npm publish` (irreversible — first because npm errors are easier
+ *      to recover from than a published-but-uncommitted state).
+ *   3. git add + commit + tag (reversible by reset/tag delete, but only
+ *      a problem if step 2 succeeded — uncommitted bump after success
+ *      is recoverable manually).
+ *   4. NOT pushed — that's the user's call.
+ *
+ * On npm publish failure → restore original package.json contents.
+ * Git failures after a successful npm publish leave the user in a
+ * partially-released state; they fix it manually (commit/tag what's
+ * needed) — we don't try to unpublish.
+ */
+export function executePublish(plan: PublishPlan): void {
+  if (plan.delegatedToMise) {
+    process.stderr.write('→ delegating to `mise run publish`...\n');
+    execFileSync('mise', ['run', 'publish'], {
+      cwd: plan.projectRoot,
+      stdio: 'inherit',
+    });
+    return;
+  }
+
+  // 1. Bump package.json in-place (keep original text for revert)
+  const originalText = fs.readFileSync(plan.packageJsonPath, 'utf8');
+  const pkg = JSON.parse(originalText);
+  pkg.version = plan.newVersion;
+  fs.writeFileSync(
+    plan.packageJsonPath,
+    JSON.stringify(pkg, null, 2) + '\n',
+    'utf8',
+  );
+  process.stderr.write(
+    `✓ bumped ${path.relative(plan.projectRoot, plan.packageJsonPath)}: ${plan.currentVersion} → ${plan.newVersion}\n`,
+  );
+
+  // 2. npm publish (interactive — OTP prompt may appear)
+  process.stderr.write(`→ running \`npm publish\` (OTP prompt may appear)...\n`);
+  const pkgDir = path.dirname(plan.packageJsonPath);
+  try {
+    execFileSync('npm', ['publish'], { cwd: pkgDir, stdio: 'inherit' });
+  } catch (e: any) {
+    fs.writeFileSync(plan.packageJsonPath, originalText, 'utf8');
+    process.stderr.write(
+      `✗ npm publish failed (exit ${e?.status ?? '?'}); reverted package.json\n`,
+    );
+    throw new Error('npm publish failed');
+  }
+  process.stderr.write(`✓ published ${plan.packageName}@${plan.newVersion}\n`);
+
+  // 3. git add + commit + tag (at project root)
+  execFileSync('git', ['add', plan.packageJsonPath], {
+    cwd: plan.projectRoot,
+    stdio: 'inherit',
+  });
+  execFileSync('git', ['commit', '-m', `release: v${plan.newVersion}`], {
+    cwd: plan.projectRoot,
+    stdio: 'inherit',
+  });
+  execFileSync(
+    'git',
+    ['tag', '-a', `v${plan.newVersion}`, '-m', `v${plan.newVersion}`],
+    { cwd: plan.projectRoot, stdio: 'inherit' },
+  );
+  process.stderr.write(`✓ committed + tagged v${plan.newVersion}\n`);
+  process.stderr.write(
+    `\n! NOT pushed — your call: \`git push --follow-tags\`\n`,
+  );
+}
+
+export function renderPublishPlan(plan: PublishPlan): string {
+  const lines: string[] = [];
+  lines.push('# vdx publish plan');
+  lines.push('');
+  if (plan.delegatedToMise) {
+    lines.push('- **Mode**: delegated to `[tasks.publish]` from mise.toml');
+    lines.push('');
+    lines.push('## Pre-flight checks');
+    lines.push('');
+    lines.push('| Check | Status | Message |');
+    lines.push('|-------|:------:|---------|');
+    for (const c of plan.preflight) {
+      lines.push(`| ${c.name} | ${c.ok ? 'OK' : 'FAIL'} | ${c.message} |`);
+    }
+    lines.push('');
+    lines.push('> vdx will exec `mise run publish` — no vdx-native pipeline involved.');
+    return lines.join('\n') + '\n';
+  }
+
+  lines.push(`- **Package**: ${plan.packageName}`);
+  lines.push(`- **Stack**: ${plan.stack}`);
+  lines.push(`- **Bump**: ${plan.bump}`);
+  lines.push(`- **Version**: ${plan.currentVersion} → ${plan.newVersion}`);
+  lines.push(`- **package.json**: ${plan.packageJsonPath}`);
+  lines.push('');
+  lines.push('## Pre-flight checks');
+  lines.push('');
+  lines.push('| Check | Status | Message |');
+  lines.push('|-------|:------:|---------|');
+  for (const c of plan.preflight) {
+    lines.push(`| ${c.name} | ${c.ok ? 'OK' : 'FAIL'} | ${c.message} |`);
+  }
+  lines.push('');
+  if (plan.preflightPassed) {
+    lines.push('## Pipeline (would execute on `vdx publish`)');
+    lines.push('');
+    lines.push(`1. Set \`version\` in package.json → \`${plan.newVersion}\``);
+    lines.push(`2. \`npm publish\` (cwd = directory containing package.json)`);
+    lines.push(`3. \`git add package.json && git commit -m "release: v${plan.newVersion}"\``);
+    lines.push(`4. \`git tag -a v${plan.newVersion} -m "v${plan.newVersion}"\``);
+    lines.push(`5. (NOT pushed — your call: \`git push --follow-tags\`)`);
+  } else {
+    lines.push('> Pre-flight failed. Use `--force` to bypass at your own risk.');
+  }
+  return lines.join('\n') + '\n';
+}

package/src/rubric.ts

@@ -30,6 +30,7 @@ export interface Axis {
   levels?: Partial<Record<LevelName, { requires: Predicate }>>;
   stack_implementations?: Record<string, StackImpl>;
   applies_to?: string[];
+  applies_when?: Predicate;
 }
 
 export interface Rubric {