wizz-method 2.0.0 → 2.1.1

package/tools/installer/modules/pin-spec.js

@@ -0,0 +1,125 @@
+// Shared `--pin CODE=TAG@SHA` value parsing, used by BOTH download paths so
+// their pin format and error messages can't diverge:
+//   - channel-plan.js (CLI gate — item 8b, auditoria 2026-09-11: a malformed
+//     pin must fail here, before any clone runs)
+//   - external-manager.js and custom-module-manager.js (post-clone trust
+//     check — item 8 fase 2 / item 8c)
+//
+// This module must stay a leaf: it is required by channel-plan.js, which is
+// itself required by external-manager.js — importing anything that pulls
+// prompts/git back in would create a require cycle.
+
+// Exactly 40 hex chars — a git full SHA. Short (abbreviated) SHAs are
+// rejected on purpose (item 8b: "prefira rejeitar: simples e seguro"): a
+// prefix compare quietly trusts whatever commit currently sits at that
+// prefix, which is exactly the ambiguity a pin exists to remove.
+const PIN_SHA_PATTERN = /^[0-9a-f]{40}$/i;
+
+/**
+ * Split a `--pin CODE=<value>` value into its tag and (optional) expected
+ * SHA, item 8 fase 2 (auditoria 2026-09-11, EXT-02 / IM-ACH-06). Accepts
+ * either:
+ *   - "TAG"      → { tag: 'TAG', expectedSha: null }
+ *   - "TAG@SHA"  → { tag: 'TAG', expectedSha: 'sha' (lowercased) }
+ *
+ * `channel-plan.js#parsePinSpec` only splits `CODE=<value>` and hands us
+ * `<value>` verbatim as an opaque string — it doesn't know about `@SHA`, so
+ * that split and this validation both live here. Same posture as
+ * `validateShellRef`/`validateCustomRef`: defensive shape check, throws
+ * loudly on a malformed value instead of silently degrading to a tag-only
+ * pin or forwarding something unchecked into `git`/the GitHub API.
+ *
+ * @param {string} rawPin - the value after `CODE=` in a --pin flag
+ * @returns {{tag: string, expectedSha: string|null}}
+ */
+function parsePinTagAndSha(rawPin) {
+  if (typeof rawPin !== 'string' || !rawPin) {
+    throw new Error(`Unsafe pin value: ${JSON.stringify(rawPin)}`);
+  }
+  const atIndex = rawPin.indexOf('@');
+  if (atIndex === -1) {
+    return { tag: rawPin, expectedSha: null };
+  }
+  const tag = rawPin.slice(0, atIndex);
+  const shaRaw = rawPin.slice(atIndex + 1);
+  if (!tag || !PIN_SHA_PATTERN.test(shaRaw)) {
+    throw new Error(
+      `Invalid --pin value ${JSON.stringify(rawPin)}. Expected TAG or TAG@40-hex-sha, where SHA is the full 40-character hex git commit SHA (e.g. --pin module=v1.7.0@0123456789abcdef0123456789abcdef01234567).`,
+    );
+  }
+  return { tag, expectedSha: shaRaw.toLowerCase() };
+}
+
+/**
+ * Inverse of parsePinTagAndSha: build the `TAG` or `TAG@SHA` string a
+ * `channelOptions.pins` entry is expected to hold, from a tag and an
+ * optional expected SHA. Used wherever a pin is rebuilt from stored state
+ * (e.g. quick-update rebuilding it from a manifest entry's `version` +
+ * `shaRequested` — item 10, review da fase 3 2026-09-11) instead of
+ * hand-concatenating `${tag}@${sha}` at each call site.
+ * @param {string} tag
+ * @param {string|null|undefined} [expectedSha]
+ * @returns {string}
+ */
+function formatPinValue(tag, expectedSha) {
+  return expectedSha ? `${tag}@${expectedSha}` : tag;
+}
+
+/**
+ * Resolve the effective raw pin ("TAG" or "TAG@SHA") for one clone call:
+ * an explicit `options.pinOverride` always wins; otherwise, when the caller
+ * passed `options.channelOptions` (parseChannelOptions' output) and a
+ * lookup `key`, look it up in `channelOptions.pins`.
+ *
+ * Bug 8 (review da fase 3, 2026-09-11): custom-module-manager.js's cloneRepo
+ * keys this by `parsed.displayName` ("owner/repo", or a local dir's
+ * basename) — a custom module's plugin code isn't known until AFTER the
+ * clone, so `--pin CODE=...` can't be keyed by plugin code at clone time.
+ * See docs/how-to/install-wizz.md.
+ *
+ * @param {{pinOverride?: string|null, channelOptions?: {pins?: Map<string,string>}}} options
+ * @param {string|null|undefined} key
+ * @returns {string|null}
+ */
+function resolvePinOverride(options, key) {
+  if (options?.pinOverride) return options.pinOverride;
+  const fromChannelOptions = key ? options?.channelOptions?.pins?.get(key) : null;
+  return fromChannelOptions || null;
+}
+
+/**
+ * Build the error for a post-clone `TAG@SHA` mismatch (item 8 fase 2 / 8c).
+ * Two flavors, picked by `fetchFailed` (bug 4, review da fase 3,
+ * 2026-09-11): when the fetch/update that preceded this compare failed
+ * (network down, repo moved, our own timeout), the mismatch was only ever
+ * checked against a stale cached checkout — the message must say the
+ * remote couldn't be reached, not claim the tag moved (that was never
+ * verified). Otherwise this ran against a fresh clone, so a real mismatch
+ * does mean the tag points somewhere else than expected.
+ *
+ * Callers remove the (now-untrusted) cache dir themselves before throwing
+ * this — building the Error here doesn't touch the filesystem.
+ *
+ * @param {Object} args
+ * @param {string} args.displayName - Human label for the module/source.
+ * @param {string} args.tag - The tag half of the pin.
+ * @param {string|null} args.resolvedSha - The actual checked-out SHA, if known.
+ * @param {string} args.expectedSha - The SHA half of the pin.
+ * @param {string} args.pinDisplay - `CODE=TAG@SHA`, echoed in the message.
+ * @param {boolean} args.fetchFailed
+ * @returns {Error}
+ */
+function buildPinMismatchError({ displayName, tag, resolvedSha, expectedSha, pinDisplay, fetchFailed }) {
+  const shaText = resolvedSha || '(desconhecido)';
+  if (fetchFailed) {
+    return new Error(
+      `Não foi possível acessar o repositório remoto para atualizar ${displayName}, e o checkout em cache não corresponde ao pin ` +
+        `solicitado (--pin ${pinDisplay}): SHA em cache ${shaText}, esperado ${expectedSha}.`,
+    );
+  }
+  return new Error(
+    `Tag '${tag}' aponta para o SHA ${shaText}, esperado ${expectedSha} (--pin ${pinDisplay}); a tag pode ter sido movida no repositório remoto.`,
+  );
+}
+
+module.exports = { parsePinTagAndSha, formatPinValue, resolvePinOverride, buildPinMismatchError, PIN_SHA_PATTERN };

package/tools/installer/modules/plugin-resolver.js

@@ -87,6 +87,7 @@ class PluginResolver {
         name: moduleData.name || plugin.name,
         version: plugin.version || moduleData.module_version || null,
         description: moduleData.description || plugin.description || '',
+        interfaceVersion: moduleData.interface_version,
         strategy: 1,
         pluginName: plugin.name,
         moduleYamlPath,
@@ -124,6 +125,7 @@ class PluginResolver {
           name: moduleData.name || plugin.name,
           version: plugin.version || moduleData.module_version || null,
           description: moduleData.description || plugin.description || '',
+          interfaceVersion: moduleData.interface_version,
           strategy: 2,
           pluginName: plugin.name,
           moduleYamlPath,
@@ -163,6 +165,7 @@ class PluginResolver {
         name: moduleData.name || plugin.name,
         version: plugin.version || moduleData.module_version || null,
         description: moduleData.description || plugin.description || '',
+        interfaceVersion: moduleData.interface_version,
         strategy: 3,
         pluginName: plugin.name,
         moduleYamlPath,
@@ -201,6 +204,7 @@ class PluginResolver {
         name: moduleData.name || path.basename(skillPath),
         version: plugin.version || moduleData.module_version || null,
         description: moduleData.description || '',
+        interfaceVersion: moduleData.interface_version,
         strategy: 4,
         pluginName: plugin.name,
         moduleYamlPath,

package/tools/installer/modules/skills-lib.js

@@ -24,6 +24,7 @@ const path = require('node:path');
 const fs = require('../fs-native');
 const yaml = require('yaml');
 const { getProjectRoot, getSourcePath } = require('../project-root');
+const { loadYamlCached } = require('../core/yaml-cache');
 const { resolveAreaEntries } = require('./registry-resolve');
 
 /**
@@ -158,12 +159,8 @@ async function installSkillsLib({ wizzDir, selectedAreas, trackFile = () => {} }
     return { copied: 0, skipped: [], registry: false };
   }
 
-  let registry;
-  try {
-    registry = yaml.parse(await fs.readFile(srcRegistry, 'utf8'));
-  } catch (error) {
-    throw new Error(`Failed to parse skills-registry.yaml: ${error.message}`);
-  }
+  // Memoized: ui.js already parsed this same file during selection (ACH-07).
+  const registry = await loadYamlCached(srcRegistry);
 
   const ids = resolveSkillIds(registry, selectedAreas);
   const destLib = path.join(wizzDir, 'skills-lib');

package/tools/installer/prompts.js

@@ -771,9 +771,7 @@ async function prompt(questions) {
 }
 
 module.exports = {
-  getClack,
   getColor,
-  handleCancel,
   intro,
   outro,
   cancel,
@@ -783,7 +781,6 @@ module.exports = {
   select,
   multiselect,
   autocompleteMultiselect,
-  autocomplete,
   directory,
   confirm,
   text,

package/tools/installer/ui.js

@@ -1,7 +1,6 @@
 const path = require('node:path');
 const os = require('node:os');
 const semver = require('semver');
-const yaml = require('yaml');
 const fs = require('./fs-native');
 const { getProjectRoot } = require('./project-root');
 const installerPackageJson = require('../../package.json');
@@ -9,6 +8,8 @@ const { CLIUtils } = require('./banner');
 const { ExternalModuleManager } = require('./modules/external-manager');
 const { resolveModuleVersion } = require('./modules/version-resolver');
 const { Manifest } = require('./core/manifest');
+const { findWizzDir } = require('./core/installer');
+const { loadYamlCached } = require('./core/yaml-cache');
 const {
   parseChannelOptions,
   buildPlan,
@@ -17,6 +18,11 @@ const {
   bundledTargetWarnings,
 } = require('./modules/channel-plan');
 const channelResolver = require('./modules/channel-resolver');
+// Bug 5 (review da fase 3, 2026-09-11): the interactive "pin to a version"
+// prompt validators below used to reject '@' outright, so a user could never
+// type TAG@SHA at the prompt (only --pin from the CLI could). Validate with
+// the same parser the CLI gate uses instead of a bare tag-chars regex.
+const { parsePinTagAndSha } = require('./modules/pin-spec');
 const { resolveMcps, partitionGloballyConfigured } = require('./modules/mcp-config');
 const { resolveClis, detectClis } = require('./modules/cli-config');
 const prompts = require('./prompts');
@@ -42,6 +48,35 @@ function formatDisplayVersion(version) {
   return trimmed;
 }
 
+// Bare tag chars: letters, digits, dots, hyphens, plus, slash. Same shape
+// the interactive picker always accepted; TAG@SHA additionally requires
+// parsePinTagAndSha's 40-hex-SHA half to validate (item 8c/bug 5).
+const PIN_TAG_CHARS_RE = /^[\w.\-+/]+$/;
+
+/**
+ * Validate a value typed at the interactive "pin to a version" prompt.
+ * Accepts a bare tag ("v1.6.0") or TAG@SHA ("v1.6.0@<40-hex-sha>") — the
+ * same two forms `--pin CODE=...` accepts on the CLI (pin-spec.js).
+ * @param {string} value
+ * @returns {string|undefined} Error message, or undefined when valid.
+ */
+function validatePinTagInput(value) {
+  const trimmed = String(value || '').trim();
+  if (!trimmed) return 'Must be a non-empty tag name (letters, digits, dots, hyphens), optionally TAG@40-hex-sha.';
+  if (!trimmed.includes('@')) {
+    if (!PIN_TAG_CHARS_RE.test(trimmed)) return 'Must be a non-empty tag name (letters, digits, dots, hyphens).';
+    return;
+  }
+  try {
+    const { tag } = parsePinTagAndSha(trimmed);
+    if (!PIN_TAG_CHARS_RE.test(tag)) {
+      return 'Must be a non-empty tag name (letters, digits, dots, hyphens), optionally TAG@40-hex-sha.';
+    }
+  } catch (error) {
+    return error.message;
+  }
+}
+
 /**
  * Build the display label for a module, showing an upgrade arrow when an
  * installed semver differs from the latest resolvable semver.
@@ -204,15 +239,15 @@ class UI {
     const messageLoader = new MessageLoader();
     await messageLoader.displayStartMessage();
 
-    // Probe the local Python before any other prompts: several WIZZ features
-    // (memlog session memory, TOML config resolution) need Python 3.11+ at
-    // runtime. Warn-don't-block, but require an explicit ack so the warning
-    // can't scroll past unseen. The installer runs in the destination
-    // environment, so probing PATH here tests the right machine.
-    // Skip the ack when stdin isn't a TTY (CI/Docker/piped): clack's select
-    // on closed stdin resolves to cancel, which would silently exit 0.
+    // Probe the local Python before any other prompts. Since audit item 29
+    // (2026-09-12) this is INFORMATIONAL only: Node is the sole prerequisite
+    // of the core, and Python buys the user the handful of BMAD skills that
+    // ship their own Python scripts. It logs one line, never blocks, and no
+    // longer asks for an acknowledgement — there is nothing to acknowledge.
+    // The installer runs in the destination environment, so probing PATH
+    // here tests the right machine.
     const { checkPythonEnvironment } = require('./core/python-check');
-    await checkPythonEnvironment({ nonInteractive: !!options.yes || !process.stdin.isTTY });
+    await checkPythonEnvironment();
 
     // Parse channel flags (--channel/--all-*/--next=/--pin) once. Warnings
     // are surfaced immediately so the user sees them before any git ops run.
@@ -254,9 +289,7 @@ class UI {
       confirmedDirectory = await this.getConfirmedDirectory();
     }
 
-    const { Installer } = require('./core/installer');
-    const installer = new Installer();
-    const { wizzDir } = await installer.findWizzDir(confirmedDirectory);
+    const { wizzDir } = findWizzDir(confirmedDirectory);
 
     // Check if there's an existing WIZZ installation
     const hasExistingInstall = await fs.pathExists(wizzDir);
@@ -358,7 +391,7 @@ class UI {
 
         // Resolve custom sources from --custom-source flag
         if (options.customSource) {
-          const customCodes = await this._resolveCustomSourcesCli(options.customSource);
+          const customCodes = await this._resolveCustomSourcesCli(options.customSource, channelOptions);
           for (const code of customCodes) {
             if (!selectedModules.includes(code)) selectedModules.push(code);
           }
@@ -460,7 +493,7 @@ class UI {
 
     // Resolve custom sources from --custom-source flag
     if (options.customSource) {
-      const customCodes = await this._resolveCustomSourcesCli(options.customSource);
+      const customCodes = await this._resolveCustomSourcesCli(options.customSource, channelOptions);
       for (const code of customCodes) {
         if (!selectedModules.includes(code)) selectedModules.push(code);
       }
@@ -534,18 +567,19 @@ class UI {
   }
 
   /**
-   * Load and parse skills-registry.yaml from the package root.
+   * Load and parse skills-registry.yaml from the package root, memoized per
+   * absolute path (audit 2026-09-11 ACH-07: this used to be a plain
+   * readFileSync + yaml.parse called 3x per install with no cache).
    * A corrupted/unparsable registry still degrades to null (areas/MCPs/CLIs
    * come back empty rather than crashing the install), but that degradation
    * is never silent: it is logged so the failure is diagnosable instead of
    * looking like "nothing to choose from" (audit finding M11).
-   * @returns {Object|null} Parsed registry, or null when absent/unreadable
+   * @returns {Promise<Object|null>} Parsed registry, or null when absent/unreadable
    */
-  _loadSkillsRegistry() {
+  async _loadSkillsRegistry() {
     const registryPath = path.join(getProjectRoot(), 'skills-registry.yaml');
-    if (!fs.existsSync(registryPath)) return null;
     try {
-      return yaml.parse(fs.readFileSync(registryPath, 'utf8'));
+      return await loadYamlCached(registryPath);
     } catch (error) {
       console.warn(`⚠ skills-registry.yaml failed to parse (${error.message}). Areas/MCPs/CLIs will be empty until this is fixed.`);
       return null;
@@ -564,7 +598,7 @@ class UI {
   async selectSkillAreas(selectedModules, options = {}) {
     if (!selectedModules.includes('bmm')) return [];
 
-    const registry = this._loadSkillsRegistry();
+    const registry = await this._loadSkillsRegistry();
     if (!registry || !registry.areas) return [];
     const areaKeys = Object.keys(registry.areas);
     if (areaKeys.length === 0) return [];
@@ -620,7 +654,7 @@ class UI {
   async selectMcps(selectedModules, selectedAreas, options = {}) {
     if (!selectedModules.includes('bmm')) return { toWrite: [], toRecommend: [] };
 
-    const registry = this._loadSkillsRegistry();
+    const registry = await this._loadSkillsRegistry();
     let resolved = resolveMcps(registry, selectedAreas);
     if (resolved.length === 0) return { toWrite: [], toRecommend: [] };
 
@@ -702,7 +736,7 @@ class UI {
     const empty = { toInstall: [], toRecommend: [], alreadyInstalled: [] };
     if (!selectedModules.includes('bmm')) return empty;
 
-    const registry = this._loadSkillsRegistry();
+    const registry = await this._loadSkillsRegistry();
     const resolved = resolveClis(registry, selectedAreas);
     if (resolved.length === 0) return empty;
 
@@ -849,9 +883,7 @@ class UI {
 
   async promptToolSelection(projectDir, options = {}) {
     const { ExistingInstall } = require('./core/existing-install');
-    const { Installer } = require('./core/installer');
-    const installer = new Installer();
-    const { wizzDir } = await installer.findWizzDir(projectDir || process.cwd());
+    const { wizzDir } = findWizzDir(projectDir || process.cwd());
     const existingInstall = await ExistingInstall.detect(wizzDir);
     const configuredIdes = existingInstall.ides;
 
@@ -1084,9 +1116,7 @@ class UI {
    */
   async getExistingInstallation(directory) {
     const { ExistingInstall } = require('./core/existing-install');
-    const { Installer } = require('./core/installer');
-    const installer = new Installer();
-    const { wizzDir } = await installer.findWizzDir(directory);
+    const { wizzDir } = findWizzDir(directory);
     const existingInstall = await ExistingInstall.detect(wizzDir);
     const installedModuleIds = new Set(existingInstall.moduleIds);
     const installedModuleVersions = new Map();
@@ -1236,7 +1266,7 @@ class UI {
     const installedNonOfficial = [...installedModuleIds].filter((id) => !officialRegistryCodes.has(id));
 
     // Phase 2: Custom URL modules
-    const customSelected = await this._addCustomUrlModules(installedModuleIds);
+    const customSelected = await this._addCustomUrlModules(installedModuleIds, channelOptions);
 
     const allSelected = new Set([...officialSelected, ...customSelected, ...installedNonOfficial]);
 
@@ -1361,7 +1391,7 @@ class UI {
    * @param {Set} installedModuleIds - Currently installed module IDs
    * @returns {Array} Selected custom module code strings
    */
-  async _addCustomUrlModules(installedModuleIds = new Set()) {
+  async _addCustomUrlModules(installedModuleIds = new Set(), channelOptions = null) {
     const addCustom = await prompts.confirm({
       message: 'Do you want to install custom or community modules (Git URL or local path)?',
       default: false,
@@ -1379,8 +1409,16 @@ class UI {
         placeholder: 'https://github.com/owner/repo or /path/to/module',
         validate: (input) => {
           if (!input || input.trim() === '') return 'Source is required';
-          const result = customMgr.parseSource(input.trim());
-          return result.isValid ? undefined : result.error;
+          try {
+            const result = customMgr.parseSource(input.trim());
+            return result.isValid ? undefined : result.error;
+          } catch (error) {
+            // parseSource() throws for SSH URLs whose host/owner/repo contain
+            // characters that could not be safely handed to git — surface
+            // that as an inline validation message instead of crashing the
+            // prompt.
+            return error.message;
+          }
         },
       });
 
@@ -1389,7 +1427,13 @@ class UI {
 
       let sourceResult;
       try {
-        sourceResult = await customMgr.resolveSource(sourceInput.trim(), { skipInstall: true, silent: true });
+        // Bug 8 (review da fase 3, 2026-09-11): thread channelOptions through
+        // so a `--pin CODE=TAG@SHA` targeting this source's displayName
+        // (owner/repo, or the local dir basename) is honored and SHA-checked
+        // by cloneRepo — see the pin-lookup block near custom-module-manager.js's
+        // cloneRepo, keyed by parsed.displayName since the plugin code isn't
+        // known until after this clone.
+        sourceResult = await customMgr.resolveSource(sourceInput.trim(), { skipInstall: true, silent: true, channelOptions });
         s.stop(sourceResult.parsed.type === 'local' ? 'Local source resolved' : 'Repository cloned');
       } catch (error) {
         s.error('Failed to resolve source');
@@ -1541,9 +1585,10 @@ class UI {
    * Resolve custom sources from --custom-source CLI flag (non-interactive).
    * Auto-selects all discovered modules from each source.
    * @param {string} sourcesArg - Comma-separated Git URLs or local paths
+   * @param {Object|null} channelOptions - Parsed installer channel options (for --pin CODE=TAG@SHA)
    * @returns {Array} Module codes from all resolved sources
    */
-  async _resolveCustomSourcesCli(sourcesArg) {
+  async _resolveCustomSourcesCli(sourcesArg, channelOptions = null) {
     const { CustomModuleManager } = require('./modules/custom-module-manager');
     const customMgr = new CustomModuleManager();
     const allCodes = [];
@@ -1559,7 +1604,9 @@ class UI {
 
       let sourceResult;
       try {
-        sourceResult = await customMgr.resolveSource(source, { skipInstall: true, silent: true });
+        // Bug 8 (review da fase 3, 2026-09-11): see the matching comment in
+        // _addCustomUrlModules — same pin-by-displayName wiring, CLI path.
+        sourceResult = await customMgr.resolveSource(source, { skipInstall: true, silent: true, channelOptions });
         s.stop(sourceResult.parsed.type === 'local' ? 'Local source resolved' : 'Repository cloned');
       } catch (error) {
         s.error(`Failed to resolve ${source}`);
@@ -1711,9 +1758,7 @@ class UI {
         const files = await fs.readdir(directory);
         if (files.length > 0) {
           // Check for any wizz installation (any folder with _config/manifest.yaml)
-          const { Installer } = require('./core/installer');
-          const installer = new Installer();
-          const wizzResult = await installer.findWizzDir(directory);
+          const wizzResult = findWizzDir(directory);
           const hasWizzInstall =
             (await fs.pathExists(wizzResult.wizzDir)) && (await fs.pathExists(path.join(wizzResult.wizzDir, '_config', 'manifest.yaml')));
 
@@ -1954,9 +1999,7 @@ class UI {
    */
   async getConfiguredIdes(directory) {
     const { ExistingInstall } = require('./core/existing-install');
-    const { Installer } = require('./core/installer');
-    const installer = new Installer();
-    const { wizzDir } = await installer.findWizzDir(directory);
+    const { wizzDir } = findWizzDir(directory);
     const existingInstall = await ExistingInstall.detect(wizzDir);
     return existingInstall.ides;
   }
@@ -2180,12 +2223,8 @@ class UI {
         channelOptions.nextSet.add(code);
       } else if (choice === 'pin') {
         const pinValue = await prompts.text({
-          message: `Enter a version tag for '${code}' (e.g. v1.6.0):`,
-          validate: (value) => {
-            if (!value || !/^[\w.\-+/]+$/.test(String(value).trim())) {
-              return 'Must be a non-empty tag name (letters, digits, dots, hyphens).';
-            }
-          },
+          message: `Enter a version tag for '${code}' (e.g. v1.6.0, or TAG@40-hex-sha to also pin the commit):`,
+          validate: validatePinTagInput,
         });
         channelOptions.pins.set(code, String(pinValue).trim());
       }
@@ -2312,12 +2351,8 @@ class UI {
         }
         if (choice === 'pin') {
           const pinValue = await prompts.text({
-            message: `Enter a version tag for '${code}' (e.g. v1.6.0):`,
-            validate: (value) => {
-              if (!value || !/^[\w.\-+/]+$/.test(String(value).trim())) {
-                return 'Must be a non-empty tag name (letters, digits, dots, hyphens).';
-              }
-            },
+            message: `Enter a version tag for '${code}' (e.g. v1.6.0, or TAG@40-hex-sha to also pin the commit):`,
+            validate: validatePinTagInput,
           });
           channelOptions.pins.set(code, String(pinValue).trim());
           continue;
@@ -2429,4 +2464,4 @@ class UI {
   }
 }
 
-module.exports = { UI };
+module.exports = { UI, validatePinTagInput };

package/tools/installer/wizz-cli.js

@@ -81,7 +81,7 @@ for (const file of commandFiles) {
 }
 
 // Set up main program
-program.version(packageJson.version).description('Wizz Method CLI - Universal AI agent framework (built on BMAD Core)');
+program.version(packageJson.version).description('Wizz Method CLI: método de agência orientado por IA');
 
 // Register all commands
 for (const [name, cmd] of Object.entries(commands)) {

package/tools/lib/frontmatter.js

@@ -0,0 +1,139 @@
+// Parsers de frontmatter compartilhados pelos validadores do repo.
+//
+// M15 (auditoria 2026-07-07): `parseFrontmatter` estava reimplementado em
+// validate-method-refs.js (via `yaml.parse`, estrito) e 2x em
+// validate-skills.js (parser manual linha-a-linha, tolerante). As três
+// variantes têm comportamento DIFERENTE de propósito — cada validador
+// depende de nuances distintas — então esta lib não as funde numa só; ela
+// só para de duplicar a implementação, centralizando as 3 num único lugar
+// com nome próprio para cada uma:
+//   - parseFrontmatterYaml: `yaml.parse` real (estrito: só reconhece o
+//     fechamento `\n---\n`; um `---` final sem newline devolve null).
+//   - parseFrontmatterSimple: parser manual linha-a-linha; ignora linhas
+//     indentadas (valores aninhados) e NÃO junta continuações multi-linha.
+//   - parseFrontmatterMultiline: parser manual que junta continuações de
+//     valor (descriptions que ocupam várias linhas) na mesma chave.
+// parseFrontmatterSimple e parseFrontmatterMultiline aceitam o fechamento
+// tolerante (`---` final sem newline) que parseFrontmatterYaml não aceita —
+// preservando o comportamento exato que validate-skills.js já tinha.
+
+const yaml = require('yaml');
+
+/**
+ * Remove aspas simples/duplas envolvendo o valor, se houver.
+ * @param {string} value
+ * @returns {string}
+ */
+function stripQuotes(value) {
+  if ((value.startsWith("'") && value.endsWith("'")) || (value.startsWith('"') && value.endsWith('"'))) {
+    return value.slice(1, -1);
+  }
+  return value;
+}
+
+/**
+ * Extrai o bloco de frontmatter (texto entre os `---`), sem parsear.
+ * @param {string} content - Conteúdo completo do arquivo
+ * @param {{lenient?: boolean}} [opts] - `lenient`: aceita também um `---`
+ *   final sem newline de fechamento (ex.: arquivo termina em `\n---`)
+ * @returns {string|null} Bloco de frontmatter, ou null se não houver
+ */
+function frontmatterBlock(content, { lenient = false } = {}) {
+  const trimmed = content.trimStart();
+  if (!trimmed.startsWith('---')) return null;
+
+  let end = trimmed.indexOf('\n---\n', 3);
+  if (end === -1) {
+    if (lenient && trimmed.endsWith('\n---')) {
+      end = trimmed.length - 4;
+    } else {
+      return null;
+    }
+  }
+  return trimmed.slice(3, end);
+}
+
+/**
+ * Parse de frontmatter via YAML real. Fechamento estrito (`\n---\n`); um
+ * `---` final sem newline devolve null, igual ao comportamento original de
+ * validate-method-refs.js.
+ * @param {string} content
+ * @returns {Object|null} Objeto parseado, ou null se não houver frontmatter
+ *   válido (ausente, sem fechamento, ou YAML inválido)
+ */
+function parseFrontmatterYaml(content) {
+  const block = frontmatterBlock(content, { lenient: false });
+  if (block === null) return null;
+  try {
+    return yaml.parse(block);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Parse manual linha-a-linha: só reconhece pares `chave: valor` na coluna 0;
+ * linhas indentadas (valores aninhados) são ignoradas; nenhuma continuação
+ * multi-linha é aplicada. Fechamento tolerante (aceita `---` final sem
+ * newline).
+ * @param {string} content
+ * @returns {Object|null} Objeto com pares chave/valor, ou null se não houver
+ *   frontmatter
+ */
+function parseFrontmatterSimple(content) {
+  const block = frontmatterBlock(content, { lenient: true });
+  if (block === null) return null;
+
+  const fmBlock = block.trim();
+  if (fmBlock === '') return {};
+
+  const result = {};
+  for (const line of fmBlock.split('\n')) {
+    const colonIndex = line.indexOf(':');
+    if (colonIndex === -1) continue;
+    if (line[0] === ' ' || line[0] === '\t') continue;
+    const key = line.slice(0, colonIndex).trim();
+    const value = line.slice(colonIndex + 1).trim();
+    result[key] = stripQuotes(value);
+  }
+  return result;
+}
+
+/**
+ * Parse manual que junta continuações de valor multi-linha (ex.:
+ * `description:` que ocupa várias linhas) na mesma chave. Fechamento
+ * tolerante (aceita `---` final sem newline). Linhas de comentário YAML
+ * (`#`) dentro de uma continuação são ignoradas.
+ * @param {string} content
+ * @returns {Object|null} Objeto com pares chave/valor, ou null se não houver
+ *   frontmatter
+ */
+function parseFrontmatterMultiline(content) {
+  const block = frontmatterBlock(content, { lenient: true });
+  if (block === null) return null;
+
+  const fmBlock = block.trim();
+  if (fmBlock === '') return {};
+
+  const result = {};
+  let currentKey = null;
+  let currentValue = '';
+
+  for (const line of fmBlock.split('\n')) {
+    const colonIndex = line.indexOf(':');
+    // Nova chave: precisa começar na coluna 0 (sem indentação) e ter ':'.
+    if (colonIndex > 0 && line[0] !== ' ' && line[0] !== '\t') {
+      if (currentKey !== null) result[currentKey] = stripQuotes(currentValue.trim());
+      currentKey = line.slice(0, colonIndex).trim();
+      currentValue = line.slice(colonIndex + 1);
+    } else if (currentKey !== null) {
+      if (line.trimStart().startsWith('#')) continue;
+      currentValue += '\n' + line;
+    }
+  }
+  if (currentKey !== null) result[currentKey] = stripQuotes(currentValue.trim());
+
+  return result;
+}
+
+module.exports = { parseFrontmatterYaml, parseFrontmatterSimple, parseFrontmatterMultiline, stripQuotes, frontmatterBlock };