convoke-agents 3.2.1 → 3.3.0

package/_bmad/bme/_enhance/workflows/initiatives-backlog/workflow.md

@@ -1,14 +1,14 @@
 ---
 workflow: initiatives-backlog
 type: step-file
-description: Tri-modal RICE initiatives backlog management — Triage review findings, Review existing items, or Create a new backlog from scratch
+description: Lane-aware initiative lifecycle backlog management — Triage intakes through the qualifying gate, review lane items, or bootstrap a new lifecycle backlog
 author: John PM (pm.md)
-version: 1.0.0
+version: 2.0.0
 ---
 
-# Initiatives Backlog Workflow
+# Initiative Lifecycle Backlog Workflow
 
-Manage a RICE-scored initiatives backlog through three complementary modes. This workflow transforms unstructured review findings, audit outputs, and team discussions into prioritized, scored backlog items — and keeps them calibrated over time.
+Manage the **Convoke Initiative Lifecycle & Backlog** — a three-lane (Bug / Fast / Initiative) model with a qualifying gate (Vortex, John, or Winston). Transforms unstructured findings into logged intakes, routes them through qualification, and keeps RICE scores calibrated across lanes over time.
 
 ## Workflow Structure
 
@@ -16,29 +16,32 @@ Manage a RICE-scored initiatives backlog through three complementary modes. This
 - Just-in-time loading (each step loads only when needed)
 - Sequential enforcement within each mode
 - State tracking in frontmatter (progress preserved across sessions)
-- Two-gate validation in Triage mode (extraction review, then scoring review)
+- Qualifying gate sub-flow in Triage + Create modes
 
 ## Modes Overview
 
-### [T] Triage — Ingest Review Findings
-Accepts text input (review transcripts, meeting notes, audit outputs), extracts actionable findings, proposes RICE scores with two-gate validation, and appends scored items to the existing backlog.
-- **Steps:** Ingest > Extract & Gate 1 > Score & Gate 2 > Update backlog
-- **When to use:** After a party-mode review, code review, retrospective, or any session that produces findings
+### [T] Triage — Ingest → Intake → Qualify
+Accepts text input (review transcripts, party mode outputs, audit findings, retro notes), extracts actionable findings, logs every finding as an **Intake** (§2.1), then offers the qualifying gate: for each intake, assign a **Lane** (Bug / Fast / Initiative), **Portfolio**, and **RICE** score.
+- **Steps:** Ingest > Extract & log to Intakes > Qualify into lanes > Update backlog
+- **When to use:** After any session that produces findings — code review, retrospective, party mode, user report
 
 ### [R] Review — Rescore Existing Items
-Loads the current backlog and walks through items for rescoring. Prevents score drift by prompting reassessment of Reach, Impact, Confidence, and Effort as project context evolves.
-- **Steps:** Load backlog > Walkthrough & rescore > Update backlog
-- **When to use:** Periodically (monthly or after major project milestones) to keep priorities calibrated
+Loads the current backlog, lets you pick which lane(s) to walk (Bug / Fast / Initiative / All), then walks items one at a time for RICE rescoring. Prevents score drift as project context evolves.
+- **Steps:** Load & choose lanes > Walkthrough & rescore > Update backlog
+- **When to use:** Periodically (monthly, after major milestones, or when an epic completes and changes adjacent effort)
 
-### [C] Create — Build New Backlog
-Bootstraps a new RICE-scored backlog from scratch through guided interactive gathering and scoring.
-- **Steps:** Initialize > Gather initiatives > Score > Generate prioritized view
-- **When to use:** Starting a new project or creating a fresh backlog for a new domain
+### [C] Create — Bootstrap New Lifecycle Backlog
+Generates a new lifecycle backlog file from scratch: Part 1 (canonical lifecycle process) verbatim from template + empty Part 2 lanes. Optionally gather initial intakes and run the qualifying gate on them.
+- **Steps:** Initialize & guard overwrite > Gather intakes (optional) > Qualify (optional) > Generate file
+- **When to use:** Starting a new project or creating a fresh backlog for a new domain. Existing Convoke backlog was bootstrapped on 2026-04-12.
 
 ## Output
 
-**Artifact:** `{planning_artifacts}/initiatives-backlog.md`
-**Templates:** `templates/rice-scoring-guide.md`, `templates/backlog-format-spec.md`
+**Artifact:** `{planning_artifacts}/convoke-note-initiative-lifecycle-backlog.md`
+**Templates:**
+- `templates/backlog-format-spec.md` — canonical file structure and table formats
+- `templates/lifecycle-process-spec.md` — canonical Part 1 content (Create mode only)
+- `templates/rice-scoring-guide.md` — RICE factor definitions and calibration examples
 
 ---
 
@@ -52,11 +55,11 @@ Display the following menu to the user:
 
 ---
 
-**Initiatives Backlog — Select a Mode:**
+**Initiative Lifecycle Backlog — Select a Mode:**
 
-- **[T] Triage** — Ingest review findings into scored backlog items
-- **[R] Review** — Rescore existing backlog items to keep priorities calibrated
-- **[C] Create** — Bootstrap a new RICE-scored backlog from scratch
+- **[T] Triage** — Ingest findings → log as intakes → route through qualifying gate into lanes
+- **[R] Review** — Walk a lane and rescore items to keep RICE calibrated
+- **[C] Create** — Bootstrap a new lifecycle backlog from scratch
 - **[X] Exit** — Return to John PM agent menu
 
 ---
@@ -68,21 +71,31 @@ Display the following menu to the user:
 - **IF T:** Load, read the entire file, and execute `{project-root}/_bmad/bme/_enhance/workflows/initiatives-backlog/steps-t/step-t-01-ingest.md`
 - **IF R:** Load, read the entire file, and execute `{project-root}/_bmad/bme/_enhance/workflows/initiatives-backlog/steps-r/step-r-01-load.md`
 - **IF C:** Load, read the entire file, and execute `{project-root}/_bmad/bme/_enhance/workflows/initiatives-backlog/steps-c/step-c-01-init.md`
-- **IF X:** Display "Exiting Initiatives Backlog workflow." and end the workflow — return control to the John PM agent menu
+- **IF X:** Display "Exiting Initiative Lifecycle Backlog workflow." and end the workflow — return control to the John PM agent menu
 - **IF any other input:** Display "Unknown option. Please select **T**, **R**, **C**, or **X**." then redisplay the Mode Selection menu above
 
 ### EXECUTION RULES:
 
 - ALWAYS halt and wait for user input after presenting the menu
-- Do NOT auto-select a mode — the user must explicitly choose (ADR-3)
-- Modes run independently — do NOT switch modes mid-execution (ADR-4)
+- Do NOT auto-select a mode — the user must explicitly choose
+- Modes run independently — do NOT switch modes mid-execution
 - After X, end the workflow completely
 
 ---
 
-<!-- RETURN-TO-MENU CONVENTION (for step file authors):
-     When the final step of any mode completes (e.g., step-t-04-update.md for Triage),
-     it must instruct the LLM to re-load this entire workflow file:
-     {project-root}/_bmad/bme/_enhance/workflows/initiatives-backlog/workflow.md
-     This re-presents the INITIALIZATION section and Mode Selection menu,
-     allowing the user to run another mode or exit (FR28). -->
+## Qualifying Gate Reference
+
+The **qualifying gate** is the decision point in Triage and Create modes where intakes become lane items. Only three qualifiers can invoke it:
+
+1. **Vortex team** — through discovery (full 7-stream or partial)
+2. **John (PM)** — product framing shortcut (this agent)
+3. **Winston (Architect)** — technical framing shortcut
+
+The qualifier assigns:
+- **Lane:** Bug / Fast / Initiative (per §1.3 of lifecycle-process-spec.md)
+- **Portfolio:** convoke, vortex, gyre, forge, bmm, enhance, loom, helm — or new (John+Winston decision)
+- **RICE:** Reach × Impact × Confidence / Effort (per rice-scoring-guide.md)
+
+**Default lane when uncertain:** Fast Lane. Can be promoted later if scope grows.
+
+**Intakes stay logged even after qualification.** §2.1 is the audit trail — never deleted.

package/_bmad/bme/_gyre/config.yaml

@@ -7,6 +7,9 @@ agents:
   - model-curator
   - readiness-analyst
   - review-coach
+# Agents you have deliberately removed — they will NOT be restored on `convoke-update`.
+# Add an agent ID here to opt out permanently; remove to re-enable on the next update.
+excluded_agents: []
 workflows:
   - full-analysis
   - stack-detection

package/_bmad/bme/_vortex/config.yaml

@@ -10,6 +10,9 @@ agents:
   - lean-experiments-specialist
   - production-intelligence-specialist
   - learning-decision-expert
+# Agents you have deliberately removed — they will NOT be restored on `convoke-update`.
+# Add an agent ID here to opt out permanently; remove to re-enable on the next update.
+excluded_agents: []
 workflows:
   - lean-persona
   - product-vision
@@ -33,7 +36,7 @@ workflows:
   - learning-card
   - pivot-patch-persevere
   - vortex-navigation
-version: 3.2.0
+version: 3.3.0
 user_name: "{user}"
 communication_language: en
 party_mode_enabled: true

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "convoke-agents",
-  "version": "3.2.1",
+  "version": "3.3.0",
   "description": "Agent teams for complex systems, compatible with BMad Method",
   "main": "index.js",
   "files": [

package/scripts/convoke-doctor.js

@@ -5,6 +5,7 @@ const path = require('path');
 const chalk = require('chalk');
 const yaml = require('js-yaml');
 const { findProjectRoot, getPackageVersion } = require('./update/lib/utils');
+const { AGENTS, GYRE_AGENTS, EXTRA_BME_AGENTS } = require('./update/lib/agent-registry');
 // Note: parseCsvRow is loaded LAZILY inside loadSkillManifest() (ag-7-2 review patch).
 // Top-level require would crash the doctor on installs missing _team-factory/ — exactly
 // the broken-install case the doctor exists to diagnose. The lazy require is wrapped
@@ -82,7 +83,10 @@ async function main() {
     }
   }
 
-  // 4. Global checks (module-agnostic)
+  // 4. Agent skill wrapper check (I43: spans all bme modules)
+  checks.push(checkAgentSkillWrappers(projectRoot, modules));
+
+  // 5. Global checks (module-agnostic)
   checks.push(await checkOutputDir(projectRoot));
   checks.push(checkMigrationLock(projectRoot));
   checks.push(checkVersionConsistency(projectRoot, modules));
@@ -196,6 +200,12 @@ function checkModuleAgents(mod) {
   const label = `${mod.name} agents`;
   const agentsDir = path.join(mod.dir, 'agents');
   const agentIds = mod.config.agents;
+  // U8: `agents` in config.yaml already has exclusions filtered out (mergeConfig does this
+  // at upgrade time). We read `excluded_agents` purely to surface the opt-out list in the
+  // info line — so operators can see what's excluded without cross-referencing files.
+  const excluded = Array.isArray(mod.config.excluded_agents)
+    ? mod.config.excluded_agents.filter(a => typeof a === 'string')
+    : [];
 
   if (!fs.existsSync(agentsDir)) {
     return {
@@ -232,7 +242,11 @@ function checkModuleAgents(mod) {
     };
   }
 
-  return { name: label, passed: true, info: `${agentIds.length} agents present` };
+  let info = `${agentIds.length} agents present`;
+  if (excluded.length > 0) {
+    info += ` (${excluded.length} excluded: ${excluded.join(', ')})`;
+  }
+  return { name: label, passed: true, info };
 }
 
 function checkModuleWorkflows(mod) {
@@ -421,6 +435,46 @@ function checkModuleSkillWrappers(mod, projectRoot, manifestMap) {
   };
 }
 
+function checkAgentSkillWrappers(projectRoot, modules = []) {
+  const label = 'BME agent skill wrappers';
+  // U8: gather excluded agent IDs across all discovered modules so their wrappers
+  // don't get flagged as missing (they are intentionally absent).
+  const excludedIds = new Set();
+  for (const mod of modules) {
+    if (mod.config && Array.isArray(mod.config.excluded_agents)) {
+      for (const id of mod.config.excluded_agents) {
+        if (typeof id === 'string') excludedIds.add(id);
+      }
+    }
+  }
+
+  const allAgents = [...AGENTS, ...GYRE_AGENTS, ...EXTRA_BME_AGENTS].filter(
+    a => !excludedIds.has(a.id)
+  );
+  const failures = [];
+
+  for (const agent of allAgents) {
+    const wrapperPath = path.join(projectRoot, '.claude', 'skills', `bmad-agent-bme-${agent.id}`, 'SKILL.md');
+    if (!fs.existsSync(wrapperPath)) {
+      failures.push(`Missing: .claude/skills/bmad-agent-bme-${agent.id}/SKILL.md`);
+    }
+  }
+
+  if (failures.length > 0) {
+    return {
+      name: label,
+      passed: false,
+      error: failures.join('; '),
+      fix: 'Run convoke-update to regenerate agent skill wrappers'
+    };
+  }
+
+  const info = excludedIds.size > 0
+    ? `${allAgents.length} agent skill wrappers verified (${excludedIds.size} excluded)`
+    : `${allAgents.length} agent skill wrappers verified`;
+  return { name: label, passed: true, info };
+}
+
 async function checkOutputDir(projectRoot) {
   const outputDir = path.join(projectRoot, '_bmad-output');
 

package/scripts/lib/artifact-utils.js

@@ -1996,10 +1996,23 @@ function generateRenameMap(renamedEntries) {
  *
  * @param {string} date - ISO date string (YYYY-MM-DD)
  * @param {{renamedCount: number, injectedCount: number, linksUpdated: number, scopeDirs: string[]}} migrationStats
+ * @param {import('./types').TaxonomyConfig} taxonomy - Loaded taxonomy (source of truth for platform/type lists and counts)
  * @returns {string} Markdown content for the ADR file
  */
-function generateGovernanceADR(date, migrationStats = {}) {
+function generateGovernanceADR(date, migrationStats = {}, taxonomy) {
+  if (
+    !taxonomy ||
+    !taxonomy.initiatives ||
+    !Array.isArray(taxonomy.initiatives.platform) ||
+    !Array.isArray(taxonomy.artifact_types)
+  ) {
+    throw new TypeError(
+      'generateGovernanceADR: taxonomy arg is required and must expose initiatives.platform and artifact_types as arrays (pass the object returned by readTaxonomy)'
+    );
+  }
   const { renamedCount = 0, injectedCount = 0, linksUpdated = 0, scopeDirs = [] } = migrationStats;
+  const platformIds = taxonomy.initiatives.platform;
+  const artifactTypes = taxonomy.artifact_types;
   return `# Architecture Decision Record: Artifact Governance Convention
 
 **Status:** ACCEPTED
@@ -2028,9 +2041,9 @@ All artifacts within \`_bmad-output/\` follow the governance naming convention:
 
 ## Taxonomy
 
-**Platform initiatives (8):** vortex, gyre, bmm, forge, helm, enhance, loom, convoke
+**Platform initiatives (${platformIds.length}):** ${platformIds.join(', ')}
 
-**Artifact types (21):** prd, epic, arch, adr, persona, lean-persona, empathy-map, problem-def, hypothesis, experiment, signal, decision, scope, pre-reg, sprint, brief, vision, report, research, story, spec
+**Artifact types (${artifactTypes.length}):** ${artifactTypes.join(', ')}
 
 **Aliases (migration-specific):** Historical name variants mapped to canonical initiative IDs during migration (e.g., strategy-perimeter -> helm, team-factory -> loom).
 

package/scripts/migrate-artifacts.js

@@ -135,7 +135,8 @@ const PLATFORM_INITIATIVES = ['vortex', 'gyre', 'bmm', 'forge', 'helm', 'enhance
 const DEFAULT_ARTIFACT_TYPES = [
   'prd', 'epic', 'arch', 'adr', 'persona', 'lean-persona', 'empathy-map',
   'problem-def', 'hypothesis', 'experiment', 'signal', 'decision', 'scope',
-  'pre-reg', 'sprint', 'brief', 'vision', 'report', 'research', 'story', 'spec'
+  'pre-reg', 'sprint', 'brief', 'vision', 'report', 'research', 'story', 'spec',
+  'covenant'
 ];
 
 /**
@@ -385,7 +386,7 @@ async function main() {
         injectedCount: injResult.injectedCount,
         linksUpdated: injResult.linkUpdates.updatedLinks,
         scopeDirs: filteredIncludeDirs
-      });
+      }, taxonomy);
 
       const adrDir = path.join(projectRoot, '_bmad-output', 'planning-artifacts');
       fs.ensureDirSync(adrDir);

package/scripts/portability/convoke-export.js

@@ -67,9 +67,14 @@ function parseArgs(argv) {
       opts.dryRun = true;
     } else if (a === '--all') {
       opts.all = true;
+    } else if (a === '--quiet' || a === '-q') {
+      opts.quiet = true;
     } else if (a === '--output') {
       const next = argv[i + 1];
-      if (!next || next.startsWith('--')) {
+      // Reject any `-`-prefixed token as a value — covers both long (`--flag`)
+      // and short (`-q`, `-h`) neighbors. Previously accepted `-q` as a literal
+      // output path; I50's short-alias introduction made that exploitable.
+      if (!next || next.startsWith('-')) {
         opts.unknown = '--output (missing value)';
         return opts;
       }
@@ -80,7 +85,8 @@ function parseArgs(argv) {
       opts.output = val;
     } else if (a === '--tier') {
       const next = argv[i + 1];
-      if (!next || next.startsWith('--')) {
+      // See note on `--output` above: reject any `-`-prefixed token as a value.
+      if (!next || next.startsWith('-')) {
         opts.unknown = '--tier (missing value)';
         return opts;
       }
@@ -126,6 +132,9 @@ function printHelp() {
     '  --all                 Export all exportable tiers (standalone + light-deps).',
     '  --dry-run             Run the engine in-memory; print would-be paths; write',
     '                        nothing. Combinable with all other flags.',
+    '  --quiet, -q           Suppress per-skill success and skip lines. Failures',
+    '                        (stderr) and the final summary line are still emitted.',
+    '                        Useful in CI / scripted pipelines.',
     '  --help, -h            Print this message and exit 0.',
     '',
     '  Conflicts:',
@@ -161,25 +170,30 @@ function printHelp() {
 // REPORTER
 // =============================================================================
 
-function makeReporter() {
+function makeReporter(opts = {}) {
+  const { quiet = false } = opts;
   const results = { success: 0, failed: 0, skipped: 0, warnings: 0 };
   return {
     success(skill, relPath, warnings) {
       results.success++;
       results.warnings += warnings;
+      if (quiet) return;
       const suffix = warnings > 0 ? ` (${warnings} warnings)` : '';
       process.stdout.write(`✅ ${skill} → ${relPath}${suffix}\n`);
     },
     failure(skill, error) {
+      // Failures always emit — `--quiet` suppresses success noise, not errors.
       results.failed++;
       const msg = (error && error.message ? error.message : String(error)).split('\n')[0];
       process.stderr.write(`❌ ${skill} — ${msg}\n`);
     },
     skip(skill, reason) {
       results.skipped++;
+      if (quiet) return;
       process.stdout.write(`⏭️  ${skill} — ${reason}\n`);
     },
     summary(dryRun) {
+      // Summary always emits — it's a single line that tells CI the batch outcome.
       const prefix = dryRun ? '[DRY RUN] ' : '';
       const total = results.success + results.failed + results.skipped;
       process.stdout.write(
@@ -189,6 +203,9 @@ function makeReporter() {
     counts() {
       return results;
     },
+    isQuiet() {
+      return quiet;
+    },
   };
 }
 
@@ -410,7 +427,11 @@ function runBatch(tierValue, outputBase, dryRun, projectRoot, reporter) {
   ].sort();
 
   if (matchingSkills.length === 0) {
-    process.stdout.write('Nothing to export — manifest matches found 0 skills\n');
+    // Suppress the friendly message in --quiet mode so the caller only sees
+    // the single-line summary ("Exported 0 skills (0/0/0) — 0 warnings total").
+    if (!reporter.isQuiet()) {
+      process.stdout.write('Nothing to export — manifest matches found 0 skills\n');
+    }
     return EXIT_SUCCESS;
   }
 
@@ -484,7 +505,7 @@ function main() {
     outputBase = path.join(projectRoot, 'exported-skills');
   }
 
-  const reporter = makeReporter();
+  const reporter = makeReporter({ quiet: !!opts.quiet });
 
   let exitCode;
   if (hasPositional) {

package/scripts/portability/export-engine.js

@@ -269,7 +269,7 @@ function loadPersona(skillName, skillContent, workflowContent, projectRoot) {
 
   // Convert agent row to persona object
   return {
-    name: agent.displayName,
+    name: agent.displayName || agent.name,
     icon: agent.icon || '',
     title: agent.title || '',
     role: agent.role || '',
@@ -1008,13 +1008,8 @@ function buildDependencyNotes(skillRefs, sidecars, manifestSkillNames) {
 function exportSkill(skillName, projectRoot, options = {}) {
   const warnings = [];
 
-  // 1. Load skill row + tier check (standalone + light-deps allowed; pipeline rejected)
+  // 1. Load skill row (all tiers exportable; pipeline skills get a framework-only notice)
   const skillRow = loadSkillRow(skillName, projectRoot);
-  if (skillRow.tier === 'pipeline') {
-    throw new Error(
-      `${skillName} is tier "pipeline" — pipeline skills are not exported per the portability schema.`
-    );
-  }
 
   // 2. Load source files
   const { skillContent, workflowContent, stepContents, skillDir } = loadSkillSource(skillRow, projectRoot, warnings);
@@ -1079,6 +1074,13 @@ function exportSkill(skillName, projectRoot, options = {}) {
   const parts = [
     transformedSections.title,
     '',
+  ];
+  // Framework-only notice for pipeline skills (not fully portable)
+  if (skillRow.tier === 'pipeline') {
+    parts.push('> **⚠️ Framework-only skill.** This skill depends on the full Convoke installation and cannot run standalone. It\'s included in the catalog for discoverability. Install Convoke from [convoke-agents](https://github.com/amalik/convoke-agents) to use it.');
+    parts.push('');
+  }
+  parts.push(
     transformedSections.persona,
     '',
     transformedSections.whenToUse,
@@ -1088,7 +1090,7 @@ function exportSkill(skillName, projectRoot, options = {}) {
     transformedSections.howToProceed,
     '',
     transformedSections.whatYouProduce,
-  ];
+  );
   if (transformedSections.qualityChecks) {
     parts.push('');
     parts.push(transformedSections.qualityChecks);

package/scripts/portability/seed-catalog-repo.js

@@ -86,22 +86,22 @@ function generate(outputDir, projectRoot) {
   const manifestPath = path.join(projectRoot, '_bmad', '_config', 'skill-manifest.csv');
   const { header, rows } = readManifest(manifestPath);
   const nameIdx = header.indexOf('name');
-  const tierIdx = header.indexOf('tier');
 
-  // Get unique exportable skill names (standalone + light-deps)
+  // Get unique exportable skill names (all tiers — pipeline gets a framework-only notice)
+  // Exclude meta-platform skills (framework internals, not user-facing)
+  const intentIdx = header.indexOf('intent');
   const seen = new Set();
   const exportableNames = [];
   for (const row of rows) {
     const name = row[nameIdx];
     if (seen.has(name)) continue;
     seen.add(name);
-    if (row[tierIdx] === 'standalone' || row[tierIdx] === 'light-deps') {
-      exportableNames.push(name);
-    }
+    if (row[intentIdx] === 'meta-platform') continue;
+    exportableNames.push(name);
   }
   exportableNames.sort();
 
-  console.log(`Exporting ${exportableNames.length} skills (standalone + light-deps)...`);
+  console.log(`Exporting ${exportableNames.length} skills (all tiers)...`);
 
   // Create output directory
   fs.mkdirSync(outputDir, { recursive: true });

package/scripts/portability/validate-exports.js

@@ -84,25 +84,36 @@ function validateInstructions(filePath, skillName) {
     issues.push({ skill: skillName, file: 'instructions.md', issue: 'contains frontmatter block' });
   }
 
-  // Balanced code fences
-  const fenceCount = (content.match(/^```/gm) || []).length;
-  if (fenceCount % 2 !== 0) {
-    issues.push({ skill: skillName, file: 'instructions.md', issue: `unbalanced code fences (${fenceCount} found)` });
+  // Framework-only (pipeline) skills skip strict structural checks since they
+  // intentionally reference framework-internal paths and may have unbalanced
+  // fences after transformations strip framework scaffolding
+  const isFrameworkOnly = content.includes('⚠️ Framework-only skill.');
+
+  // Balanced code fences (skipped for framework-only)
+  if (!isFrameworkOnly) {
+    const fenceCount = (content.match(/^```/gm) || []).length;
+    if (fenceCount % 2 !== 0) {
+      issues.push({ skill: skillName, file: 'instructions.md', issue: `unbalanced code fences (${fenceCount} found)` });
+    }
   }
 
-  // Broken markdown links (links to local files that aren't URLs or anchors)
-  const localLinks = [...content.matchAll(/\[([^\]]*)\]\((?!https?:\/\/|#|mailto:)([^)]+)\)/g)];
-  for (const match of localLinks) {
-    const linkTarget = match[2];
-    // Skip links containing template placeholders or non-path content
-    if (linkTarget.includes('[') || linkTarget.includes('{')) continue;
-    if (linkTarget.includes(' ')) continue; // URLs/paths don't have spaces; this is prose like "(none found)"
-    const resolved = path.resolve(path.dirname(filePath), linkTarget);
-    if (!fs.existsSync(resolved)) {
-      issues.push({ skill: skillName, file: 'instructions.md', issue: `broken link: [${match[1]}](${linkTarget})` });
+  // Broken markdown links (skipped for framework-only)
+  if (!isFrameworkOnly) {
+    // Broken markdown links (links to local files that aren't URLs or anchors)
+    const localLinks = [...content.matchAll(/\[([^\]]*)\]\((?!https?:\/\/|#|mailto:)([^)]+)\)/g)];
+    for (const match of localLinks) {
+      const linkTarget = match[2];
+      // Skip links containing template placeholders or non-path content
+      if (linkTarget.includes('[') || linkTarget.includes('{')) continue;
+      if (linkTarget.includes(' ')) continue; // URLs/paths don't have spaces; this is prose like "(none found)"
+      const resolved = path.resolve(path.dirname(filePath), linkTarget);
+      if (!fs.existsSync(resolved)) {
+        issues.push({ skill: skillName, file: 'instructions.md', issue: `broken link: [${match[1]}](${linkTarget})` });
+      }
     }
   }
 
+
   return issues;
 }
 

package/scripts/update/convoke-update.js

@@ -6,6 +6,7 @@ const versionDetector = require('./lib/version-detector');
 const migrationRunner = require('./lib/migration-runner');
 const registry = require('./migrations/registry');
 const { findProjectRoot } = require('./lib/utils');
+const { readChangelogEntries } = require('./lib/changelog-reader');
 
 /**
  * Convoke Update CLI
@@ -158,6 +159,8 @@ async function main() {
     console.log(chalk.cyan('No migration deltas needed — refreshing installation files.'));
     console.log('');
 
+    printChangelog(assessment.currentVersion, assessment.targetVersion);
+
     if (dryRun) {
       console.log(chalk.yellow.bold('DRY RUN — no changes will be made'));
       console.log('');
@@ -220,6 +223,8 @@ async function main() {
     console.log('');
   }
 
+  printChangelog(assessment.currentVersion, assessment.targetVersion);
+
   // Dry run - preview only
   if (dryRun) {
     console.log(chalk.yellow.bold('DRY RUN - Previewing changes'));
@@ -279,6 +284,26 @@ async function main() {
   }
 }
 
+/**
+ * Render CHANGELOG sections for versions in (fromVersion, toVersion] to stdout.
+ * Silently skips if there are no matching entries — this is a decorative surface.
+ */
+function printChangelog(fromVersion, toVersion) {
+  const entries = readChangelogEntries(fromVersion, toVersion);
+  if (entries.length === 0) return;
+
+  console.log(chalk.cyan.bold("What's New:"));
+  console.log('');
+  for (const entry of entries) {
+    const header = entry.date
+      ? `${entry.version} — ${entry.date}`
+      : entry.version;
+    console.log(chalk.bold.green(header));
+    console.log(entry.body);
+    console.log('');
+  }
+}
+
 /**
  * Confirm action with user
  * @param {string} message - Confirmation message
@@ -298,8 +323,8 @@ async function confirm(message) {
   });
 }
 
-// Export assessUpdate for testing
-module.exports = { assessUpdate };
+// Export for testing
+module.exports = { assessUpdate, printChangelog };
 
 // Run main when executed directly
 if (require.main === module) {