@vodmal/vdx-cli 0.2.0 → 0.3.0

package/README.md

@@ -1,51 +1,63 @@
-# vdx-cli — Native predicate evaluator (v0.1)
+# @vodmal/vdx-cli — vdx evaluator + MCP server
 
-Минимальный аудит-движок для рубрики `vdx-rubric-vodmal`. Шаг C плана
-реализации (см. `../docs/decisions.md` D10 — нативный оценщик, не OPA).
+Native predicate evaluator for `vdx-rubric-vodmal` + MCP stdio server for the
+Claude Code `vdx` plugin. Decision basis: [docs/decisions.md](../docs/decisions.md)
+D10 (native evaluator, not OPA).
 
-## Установка
+Published on npm as **[@vodmal/vdx-cli](https://www.npmjs.com/package/@vodmal/vdx-cli)**.
+
+## Install
 
 ```bash
-cd "$(realpath .)"
-npm install
+# global install
+npm install -g @vodmal/vdx-cli
+
+# or one-shot via npx (no install)
+npx -y -p @vodmal/vdx-cli vdx audit /path/to/project
 ```
 
-## Запуск
+## Use
 
 ```bash
-npx tsx src/index.ts audit /path/to/project
-# или
-npm run audit -- /path/to/project --json
+vdx audit <project-path> [--json] [--rubric <path>] [--stack <id>]
+vdx init  <project-path> [--baseline github.com/org/repo@vX.Y] [--dry-run] [--force]
+vdx-mcp   --project <path>   # MCP stdio server (used by the plugin)
 ```
 
-По умолчанию рубрика читается из
-`/Users/vdm/AI Projects/vdx-rubric-vodmal/vdx-rubric.yaml`. Override:
-`--rubric /alt/path.yaml`.
+By default the bundled `rubric/vdx-rubric.yaml` is used (a mirror of canonical
+[vdx-rubric-vodmal](https://github.com/VoDmAl/vdx-rubric-vodmal) at the time of
+each CLI release). Override via `--rubric <path>` or the env var `VDX_RUBRIC`.
 
-## Smoke-тест
+## Dev
 
 ```bash
-npm run smoke
+git clone https://github.com/VoDmAl/vdx
+cd vdx/cli
+npm install
+npm run audit -- /path/to/project --json
+npm run smoke      # gauge against 3 calibration references
+npm run typecheck
 ```
 
-Прогоняет аудит на трёх калибровочных референсах
-(telegram / t23b / bookmap). Ожидаемо все capped at L2 на оси `ci`.
-
-## Структура
+## Structure
 
-- `src/rubric.ts`     — типы + YAML-загрузчик
-- `src/manifest.ts`   — парсинг `[vdx]` блока в `mise.toml` + `.vdx-overrides.yml`
-- `src/facts.ts`      — fact source loaders (tasks, packages, configs)
-- `src/predicates.ts` — registry предикатов (v0.1: 11 функций)
-- `src/evaluator.ts`  — рекурсивный evaluator + сахарная нотация
-- `src/scoring.ts`    — delta-style для уровней, flags для гибкой оси
-- `src/audit.ts`      — оркестратор: применяет overrides + считает уровень (D7)
-- `src/report.ts`     — markdown / JSON формат отчёта
+- `src/rubric.ts`     — types + YAML loader
+- `src/manifest.ts`   — parser for `[vdx]` block in `mise.toml` + `.vdx-overrides.yml`
+- `src/facts.ts`      — fact source loaders (tasks, packages, configs, sub-package detection)
+- `src/predicates.ts` — predicate registry (11 functions)
+- `src/evaluator.ts`  — recursive evaluator + sugar notation
+- `src/scoring.ts`    — delta-style levels, flags for orthogonal axes
+- `src/audit.ts`      — orchestrator: overrides + applies_to filter + subpackage-ctx
+- `src/report.ts`     — markdown / JSON output
 - `src/index.ts`      — CLI entry
+- `src/mcp-server.ts` — MCP stdio server (9 tools)
+- `src/defaults.ts`   — bundled rubric resolution
+- `bin/vdx.cjs`, `bin/vdx-mcp.cjs` — Node wrappers (tsx ESM loader in-process)
 
-## Что НЕ реализовано в v0.1
+## Not implemented yet
 
-- `config_value`, `command_succeeds` предикаты — заглушки с warning.
-- Загрузка baseline из git-репо по `baseline:` ссылке — пока только local file.
-- Watermark drift (фаза 2 из drift-algorithm.md).
-- MCP-server обёртка (D6 — следующий шаг).
+- `config_value`/`command_succeeds` predicates are stubs (warning at evaluation).
+- Baseline loading from a git ref is documented but evaluator still reads file
+  paths only — `baseline:` in `mise.toml` is recorded but does not auto-fetch.
+- Watermark drift (phase 2 of `drift-algorithm.md`).
+- O25/O26/O27/O33/O34 — see [docs/decisions.md](../docs/decisions.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vodmal/vdx-cli",
-  "version": "0.2.0",
+  "version": "0.3.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",
@@ -23,8 +23,8 @@
   },
   "type": "module",
   "bin": {
-    "vdx": "./bin/vdx.cjs",
-    "vdx-mcp": "./bin/vdx-mcp.cjs"
+    "vdx": "bin/vdx.cjs",
+    "vdx-mcp": "bin/vdx-mcp.cjs"
   },
   "files": [
     "src",
@@ -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

@@ -1,7 +1,8 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import type { Rubric, LevelName } from './rubric.ts';
-import { findSubPackages, type Ctx } from './facts.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';
 
@@ -33,12 +34,14 @@ function resolveSubpackageCtx(
   manifest: VdxManifest | null,
 ): { ctx: Ctx; relPath: string | null } {
   let relPath: string | null = null;
+  let subpackageStack: string | null = null;
 
   if (manifest?.primary_subpackage) {
     const p = manifest.primary_subpackage;
     const abs = path.join(ctx.projectRoot, p);
     if (fs.existsSync(abs)) {
       relPath = p;
+      subpackageStack = stackForDir(abs);
     } else {
       process.stderr.write(
         `warning: primary_subpackage "${p}" does not exist — falling back to root\n`,
@@ -49,6 +52,12 @@ function resolveSubpackageCtx(
     const matching = subs.filter((s) => s.stack === ctx.stack);
     if (matching.length === 1) {
       relPath = matching[0]!.relPath;
+      subpackageStack = matching[0]!.stack;
+    } else if (matching.length === 0 && subs.length === 1) {
+      // O33: single sub-package with a stack different from ctx.stack —
+      // adopt it so applies_to-axes for that stack can evaluate.
+      relPath = subs[0]!.relPath;
+      subpackageStack = subs[0]!.stack;
     }
   }
 
@@ -56,7 +65,7 @@ function resolveSubpackageCtx(
   return {
     ctx: {
       projectRoot: path.join(ctx.projectRoot, relPath),
-      stack: ctx.stack,
+      stack: subpackageStack ?? ctx.stack,
       cache: new Map(),
     },
     relPath,
@@ -96,7 +105,18 @@ export function audit(
       });
       continue;
     }
-    if (axis.applies_to && !axis.applies_to.includes(ctx.stack)) {
+    const evalCtx = axis.applies_to ? subpackageCtx : ctx;
+    if (axis.applies_to && !axis.applies_to.includes(evalCtx.stack)) {
+      perAxis.push({
+        axis_id: axis.id,
+        class: axis.class,
+        achieved: 'L0',
+        target: axis.default_target,
+        drift_kind: 'excluded',
+      });
+      continue;
+    }
+    if (axis.applies_when && !evalPredicate(axis.applies_when, evalCtx)) {
       perAxis.push({
         axis_id: axis.id,
         class: axis.class,
@@ -106,7 +126,6 @@ export function audit(
       });
       continue;
     }
-    const evalCtx = axis.applies_to ? subpackageCtx : ctx;
     const achieved = evalAxis(axis, evalCtx);
     const ov = overrideByAxis.get(axis.id);
     const target = (ov?.target as LevelName) ?? axis.default_target;

package/src/facts.ts

@@ -216,7 +216,7 @@ const MANIFEST_TO_STACK: Array<[string, string]> = [
   ['requirements.txt', 'python'],
 ];
 
-function stackForDir(dir: string): string | null {
+export function stackForDir(dir: string): string | null {
   for (const [manifest, stack] of MANIFEST_TO_STACK) {
     if (fs.existsSync(path.join(dir, manifest))) return stack;
   }

package/src/index.ts

@@ -14,7 +14,7 @@ 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 init  <project_path> [--stack <id>] [--baseline <ref>] [--dry-run] [--force]
 `,
   );
   process.exit(1);
@@ -86,10 +86,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;

package/src/init.ts

@@ -7,12 +7,14 @@ 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'],
@@ -41,6 +43,10 @@ export interface VerbMapping {
 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 +55,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 +75,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.
@@ -135,12 +152,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)) {
@@ -161,6 +189,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 +248,93 @@ 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);
-    return {
-      verb,
-      nativeTask: native,
-      runCommand: native ? renderRunCommand(native, stack, projectRoot) : null,
-    };
+    let runCommand: string | null = null;
+    if (native) {
+      runCommand =
+        primarySubpackage !== null
+          ? renderRunCommandInSubpackage(native, scanStack, scanRoot, primarySubpackage)
+          : renderRunCommand(native, stack, projectRoot);
+    }
+    return { verb, nativeTask: native, runCommand };
   });
 
-  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 +343,7 @@ export function planInit(projectRoot: string, opts: { baseline?: string } = {}):
     agentsMdPath,
     agentsMdContent,
     baseline,
+    warnings,
   };
 }
 
@@ -272,10 +361,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}`)

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 {