fraim 2.0.270 → 2.0.271

package/dist/src/cli/commands/add-ide.js

@@ -42,6 +42,7 @@ const chalk_1 = __importDefault(require("chalk"));
 const prompts_1 = __importDefault(require("prompts"));
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
+const os_1 = __importDefault(require("os"));
 const ide_detector_1 = require("../setup/ide-detector");
 const mcp_config_generator_1 = require("../setup/mcp-config-generator");
 const claude_code_telemetry_1 = require("../setup/claude-code-telemetry");
@@ -51,13 +52,38 @@ const get_provider_client_1 = require("../api/get-provider-client");
 const provider_prompts_1 = require("../setup/provider-prompts");
 const provider_registry_1 = require("../providers/provider-registry");
 const user_config_1 = require("../utils/user-config");
+const resolveGlobalConfigPath = () => {
+    const primary = path_1.default.join((0, script_sync_utils_1.getUserFraimDir)(), 'config.json');
+    if (fs_1.default.existsSync(primary)) {
+        try {
+            const config = JSON.parse(fs_1.default.readFileSync(primary, 'utf8'));
+            if (config && config.apiKey)
+                return primary;
+        }
+        catch {
+            return primary;
+        }
+    }
+    // The aggregate test runner sets FRAIM_USER_DIR for process isolation, while
+    // older command tests isolate by monkey-patching os.homedir(). In test mode,
+    // honor that fixture home if it already contains the config under test.
+    if (process.env.NODE_ENV === 'test') {
+        const homedirConfig = path_1.default.join(os_1.default.homedir(), '.fraim', 'config.json');
+        if (homedirConfig !== primary && fs_1.default.existsSync(homedirConfig)) {
+            return homedirConfig;
+        }
+    }
+    return primary;
+};
 const loadGlobalConfig = async () => {
-    const globalConfigPath = path_1.default.join((0, script_sync_utils_1.getUserFraimDir)(), 'config.json');
+    const globalConfigPath = resolveGlobalConfigPath();
     if (!fs_1.default.existsSync(globalConfigPath)) {
         return null;
     }
     try {
         const config = JSON.parse(fs_1.default.readFileSync(globalConfigPath, 'utf8'));
+        if (!config.apiKey)
+            return null;
         // Support both old and new token format
         const tokens = config.tokens || {};
         // Backward compatibility: map old format to new
@@ -136,7 +162,7 @@ const promptForProviderTokenIfNeeded = async (providerId, isOptional = false) =>
     }
 };
 const saveProviderTokenToConfig = async (providerId, token) => {
-    const globalConfigPath = path_1.default.join((0, script_sync_utils_1.getUserFraimDir)(), 'config.json');
+    const globalConfigPath = resolveGlobalConfigPath();
     if (fs_1.default.existsSync(globalConfigPath)) {
         try {
             const config = JSON.parse(fs_1.default.readFileSync(globalConfigPath, 'utf8'));

package/dist/src/cli/commands/learning-usage.js

@@ -0,0 +1,412 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.learningUsageCommand = void 0;
+/**
+ * Issue #1103 — `fraim learning-usage <subcommand>`.
+ *
+ * The read and analysis side of the usage record. The write side of an offer is the
+ * proxy (no agent involvement, R2); the write side of a firing is an attestation in
+ * a retrospective, which `record-firings` reads back.
+ *
+ * This is a CLI rather than a new MCP tool deliberately: the store schema then has
+ * exactly one implementation, and nothing is added to the MCP tool surface that
+ * issues #801, #860 and #861 are working to shrink.
+ */
+const commander_1 = require("commander");
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const learning_context_builder_1 = require("../../local-mcp-server/learning-context-builder");
+const learning_usage_analysis_1 = require("../../local-mcp-server/learning-usage-analysis");
+const learning_usage_store_1 = require("../../local-mcp-server/learning-usage-store");
+const learning_usage_attestation_1 = require("../../local-mcp-server/learning-usage-attestation");
+function resolveWorkspaceRoot(options) {
+    return node_path_1.default.resolve(options.workspaceRoot || options.root || process.cwd());
+}
+function resolveUser(options) {
+    const email = options.user || process.env.FRAIM_ACTIVE_USER_EMAIL || '';
+    if (!email.trim()) {
+        throw new Error('Missing active user email. Pass --user <email> or set FRAIM_ACTIVE_USER_EMAIL.');
+    }
+    return email.trim();
+}
+function emit(payload, json, text) {
+    process.stdout.write(json ? `${JSON.stringify(payload, null, 2)}\n` : `${text()}\n`);
+}
+function addCommonOptions(command) {
+    return command
+        .option('--workspace-root <path>', 'Workspace root containing fraim/config.json')
+        .option('--root <path>', 'Alias for --workspace-root')
+        .option('--user <email>', 'Active user email')
+        .option('--json', 'Print JSON');
+}
+// ── offers ───────────────────────────────────────────────────────────────────
+const offersCommand = addCommonOptions(new commander_1.Command('offers'))
+    .description('List the learning entries and rule files the runtime delivered, so an attestation is written against the record rather than memory')
+    .option('--job <name>', 'The job whose context was loaded', 'unknown')
+    .option('--domain <domain>', 'Learning domain the job resolved to')
+    .option('--session', 'Use the session frame rather than the job frame')
+    .action((options) => {
+    const workspaceRoot = resolveWorkspaceRoot(options);
+    const user = resolveUser(options);
+    const forJob = !options.session;
+    // Prefer what the runtime recorded for this job, because that is what was
+    // actually delivered. Re-deriving from the files on disk answers a subtly
+    // different question — what would be delivered now — and the two diverge if a
+    // learning file changed during the job.
+    const store = (0, learning_usage_store_1.readUsageStore)();
+    const recorded = Object.values(store.entries)
+        .filter((entry) => entry.offered.log.some((offer) => offer.job === options.job))
+        .map((entry) => {
+        const last = [...entry.offered.log].reverse().find((offer) => offer.job === options.job);
+        return {
+            key: entry.key,
+            family: entry.family,
+            id: entry.key.startsWith('L-') ? entry.key : null,
+            title: entry.titles[entry.titles.length - 1] ?? entry.key,
+            fileType: entry.fileType ?? 'unknown',
+            level: entry.level ?? 'unknown',
+            displayPath: '',
+            severity: null,
+            aboveThreshold: last.aboveThreshold,
+        };
+    });
+    const source = recorded.length > 0 ? 'offer-record' : 'derived';
+    const offered = recorded.length > 0
+        ? recorded
+        : [
+            ...(0, learning_context_builder_1.collectOfferedLearningEntries)(workspaceRoot, user, forJob, options.domain ?? null),
+            ...(0, learning_context_builder_1.collectOfferedRuleFiles)(workspaceRoot, forJob),
+        ];
+    const payload = { job: options.job, forJob, source, offered };
+    emit(payload, options.json, () => {
+        if (payload.offered.length === 0) {
+            return `No offer record and nothing resolves for job ${options.job}. Do not attest any firing for this job.`;
+        }
+        const rows = payload.offered.map((o) => `| ${o.id ?? '(no id)'} | ${o.title} | ${o.fileType} | ${o.aboveThreshold ? 'yes' : 'no'} |`);
+        const header = source === 'offer-record'
+            ? `Entries offered for job ${options.job}, from the offer record:`
+            : `No offer record exists for job ${options.job} yet, so this is what would be delivered now. Say so when you attest against it.`;
+        return [
+            header,
+            '',
+            '| Id | Title | Family | Above threshold |',
+            '|---|---|---|---|',
+            ...rows,
+        ].join('\n');
+    });
+});
+// ── record-firings ───────────────────────────────────────────────────────────
+const recordFiringsCommand = addCommonOptions(new commander_1.Command('record-firings'))
+    .description('Read the firing section of a retrospective and write the attested firings into the usage record')
+    .requiredOption('--retrospective <path>', 'Retrospective file to read')
+    .option('--job <name>', 'The job that produced the retrospective')
+    .option('--agent <name>', 'Agent that attested')
+    .option('--model <model>', 'Model that attested')
+    .option('--legacy', 'Also accept the pre-#1103 prose form')
+    .action((options) => {
+    const workspaceRoot = resolveWorkspaceRoot(options);
+    const user = resolveUser(options);
+    const filePath = node_path_1.default.resolve(options.retrospective);
+    if (!node_fs_1.default.existsSync(filePath)) {
+        throw new Error(`Retrospective not found: ${filePath}`);
+    }
+    const content = node_fs_1.default.readFileSync(filePath, 'utf8');
+    const source = node_path_1.default.relative(workspaceRoot, filePath).replace(/\\/g, '/');
+    const result = (0, learning_usage_attestation_1.recordAttestationsFromRetrospective)(workspaceRoot, user, {
+        content,
+        source,
+        job: options.job ?? 'unknown',
+        agent: options.agent ?? null,
+        model: options.model ?? null,
+        legacy: Boolean(options.legacy),
+    });
+    emit(result, options.json, () => {
+        const lines = [
+            `Section state: ${result.sectionState}`,
+            `Items read: ${result.itemsRead}`,
+            `Recorded: ${result.applied}`,
+            `Already recorded: ${result.alreadyRecorded}`,
+            `Unmatched: ${result.unmatched.length}`,
+            `Rejected: ${result.rejected.length}`,
+        ];
+        for (const item of result.unmatched)
+            lines.push(`  unmatched: ${item.title} — ${item.reason}`);
+        for (const item of result.rejected)
+            lines.push(`  rejected: ${item.reason}`);
+        return lines.join('\n');
+    });
+});
+// ── classify ─────────────────────────────────────────────────────────────────
+const classifyCommand = addCommonOptions(new commander_1.Command('classify'))
+    .description('Say whether a recurrence was ignored (the entry was in context) or not-offered (it never reached the agent), because the two need different fixes')
+    .option('--entry <id>', 'The entry id, for an entry that carries one')
+    .option('--title <title>', 'The exact entry title, for an entry with no id yet. Use with --family')
+    .option('--family <family>', 'The entry family: mistake-patterns, preferences, validated-patterns, or manager-coaching')
+    .requiredOption('--job <name>', 'The job the recurrence happened in')
+    .requiredOption('--date <YYYY-MM-DD>', 'The date the mistake recurred')
+    .option('--window <days>', 'How far back an offer still counts as in-context', '30')
+    .action((options) => {
+    const workspaceRoot = resolveWorkspaceRoot(options);
+    // `--title` plus `--family` exists so a caller never has to build the composite
+    // title key by hand. An entry title is corpus content and can contain any
+    // character, so an agent assembling `T:<family>:<title>` into a shell command
+    // would be interpolating untrusted text into a command line. Passing the title
+    // as its own argument keeps it a single argv entry.
+    let key;
+    if (options.entry) {
+        key = String(options.entry);
+    }
+    else if (options.title && options.family) {
+        key = (0, learning_usage_store_1.titleUsageKey)(String(options.family), String(options.title));
+    }
+    else {
+        throw new Error('Pass --entry <id>, or --title <title> together with --family <family>.');
+    }
+    const store = (0, learning_usage_store_1.readUsageStore)();
+    const diagnosis = (0, learning_usage_analysis_1.classifyRecurrence)(store, {
+        key,
+        job: options.job,
+        date: options.date,
+        windowDays: Number.parseInt(options.window, 10) || 30,
+    });
+    void workspaceRoot;
+    emit(diagnosis, options.json, () => [
+        `Classification: ${diagnosis.classification}`,
+        `Diagnosis: ${diagnosis.diagnosis}`,
+        `Recommendation: ${diagnosis.recommendation}`,
+        `Raise the recurrence count: ${diagnosis.recurrenceBump ? 'yes' : 'no'}`,
+    ].join('\n'));
+});
+// ── candidates ───────────────────────────────────────────────────────────────
+const candidatesCommand = addCommonOptions(new commander_1.Command('candidates'))
+    .description('List retirement candidates: offered often under the current model with no firing under it, paired with a structural signal')
+    .option('--model <model>', 'Override the current model (defaults to the most recently offered-to model)')
+    .option('--detector <path>', 'Path to the corpus hygiene detector that provides the structural signal')
+    .action((options) => {
+    const workspaceRoot = resolveWorkspaceRoot(options);
+    const limits = (0, learning_usage_store_1.resolveUsageLimits)(workspaceRoot);
+    const result = (0, learning_usage_analysis_1.findRetirementCandidates)((0, learning_usage_store_1.readUsageStore)(), {
+        workspaceRoot,
+        limits,
+        currentModel: options.model ?? undefined,
+        structuralSignalPath: options.detector,
+    });
+    emit(result, options.json, () => {
+        if (result.candidates.length === 0) {
+            return `No retirement candidates. Current model: ${result.currentModel ?? 'unknown'}; threshold ${result.offerThreshold} offers.`;
+        }
+        const lines = [`Current model: ${result.currentModel ?? 'unknown'}. Threshold: ${result.offerThreshold} offers.`, ''];
+        for (const c of result.candidates) {
+            const earlier = c.firedUnderEarlierModels.map((m) => `${m.count} under ${m.model}`).join(', ') || 'none under any earlier model';
+            lines.push(`- ${c.title}`, `  Offered ${c.offeredUnderCurrentModel} times under the current model, fired ${c.firedUnderCurrentModel}. Earlier: ${earlier}.`, `  Structural signal: ${c.structural}. ${c.structuralDetail}`, `  Recommendation: ${c.recommendation}`);
+        }
+        return lines.join('\n');
+    });
+});
+// ── standing ─────────────────────────────────────────────────────────────────
+const standingCommand = addCommonOptions(new commander_1.Command('standing'))
+    .description('Assess each entry as promoted, standard or demoted from its usage record, and list the ones whose standing should change')
+    .option('--changes-only', 'Print only the entries whose standing should change')
+    .action((options) => {
+    const workspaceRoot = resolveWorkspaceRoot(options);
+    const limits = (0, learning_usage_store_1.resolveUsageLimits)(workspaceRoot);
+    const report = (0, learning_usage_analysis_1.assessStanding)((0, learning_usage_store_1.readUsageStore)(), { limits });
+    const payload = options.changesOnly ? { ...report, assessments: report.changes } : report;
+    emit(payload, options.json, () => {
+        const rows = (options.changesOnly ? report.changes : report.assessments);
+        if (rows.length === 0) {
+            return options.changesOnly
+                ? 'No standing changes. Every measured entry is already where the record says it belongs.'
+                : 'No entry has a usage record yet, so there is nothing to assess.';
+        }
+        const lines = [];
+        if (report.changes.length > 0) {
+            lines.push(`${report.changes.length} entr${report.changes.length === 1 ? 'y' : 'ies'} should change standing.`, '');
+        }
+        for (const a of rows) {
+            lines.push(`- ${a.title}`);
+            lines.push(`  ${a.standing}${a.recommendation ? ` (recommend: ${a.recommendation})` : ''}. ${a.reason}`);
+        }
+        lines.push('', 'Nothing is applied here. Run sleep-on-learnings to decide.');
+        return lines.join('\n');
+    });
+});
+// ── report ───────────────────────────────────────────────────────────────────
+const reportCommand = addCommonOptions(new commander_1.Command('report'))
+    .description('Answer which learnings are still earning their place, from the record rather than from memory')
+    .option('--window <days>', 'Reporting window', '90')
+    .action((options) => {
+    const workspaceRoot = resolveWorkspaceRoot(options);
+    const limits = (0, learning_usage_store_1.resolveUsageLimits)(workspaceRoot);
+    const report = (0, learning_usage_analysis_1.buildUsageReport)((0, learning_usage_store_1.readUsageStore)(), {
+        workspaceRoot,
+        limits,
+        windowDays: Number.parseInt(options.window, 10) || 90,
+    });
+    emit(report, options.json, () => {
+        const lines = [
+            `${report.totals.entriesOffered} entries were offered. ${report.totals.entriesWithFirings} fired. ${report.totals.entriesNeverFired} have never fired.`,
+        ];
+        if (report.workingHardest.length) {
+            lines.push('', 'Working hardest');
+            report.workingHardest.forEach((e, i) => lines.push(`${i + 1}. ${e.title}. Offered ${e.offered} times, fired ${e.fired}. Last fired ${e.lastFired ?? 'never'}.`));
+        }
+        if (report.neverFired.length) {
+            lines.push('', 'Never fired');
+            report.neverFired.forEach((e, i) => lines.push(`${i + 1}. ${e.title}. Offered ${e.offered} times, never fired.`));
+        }
+        if (report.ignoredWhileInContext.length) {
+            lines.push('', 'Ignored while in context');
+            report.ignoredWhileInContext.forEach((e, i) => lines.push(`${i + 1}. ${e.title}. In context and the work went against it, so the entry needs work rather than another recurrence.`));
+        }
+        lines.push('', 'Nothing is retired from this view. Run sleep-on-learnings to decide.');
+        return lines.join('\n');
+    });
+});
+// ── backfill ─────────────────────────────────────────────────────────────────
+const backfillCommand = addCommonOptions(new commander_1.Command('backfill'))
+    .description('Read the firings already attested in existing retrospectives, matching only on an id or an exact title, and report what could not be matched')
+    .option('--agent <name>', 'Agent to attribute the backfilled records to', 'backfill')
+    .option('--model <model>', 'Model to attribute the backfilled records to')
+    .action((options) => {
+    const workspaceRoot = resolveWorkspaceRoot(options);
+    const user = resolveUser(options);
+    const report = (0, learning_usage_attestation_1.runBackfill)(workspaceRoot, user, {
+        agent: options.agent ?? 'backfill',
+        model: options.model ?? null,
+    });
+    emit(report, options.json, () => [
+        `Files scanned: ${report.filesScanned} (${report.filesWithSection} carry the section, ${report.synthesizedFilesRead} already synthesized)`,
+        `Items read: ${report.itemsRead}`,
+        `Applied: ${report.applied}`,
+        `Already recorded: ${report.alreadyRecorded}`,
+        `Unmatched: ${report.unmatched.length}`,
+        `Rejected: ${report.rejected.length}`,
+        '',
+        'Only an id or an exact title resolves. A low match rate is expected on retrospectives written before entries carried ids, and is reported rather than resolved by similarity matching.',
+    ].join('\n'));
+});
+/**
+ * Add the `**Id**` line to entries that do not have one.
+ *
+ * This is a format migration, not a change to any lesson: it inserts one
+ * identifier line per entry and touches nothing else. R19 forbids a new write path
+ * into the corpus for usage data, and this is not one — it writes no usage data,
+ * and it is run explicitly by the manager rather than by any automatic path.
+ */
+function stampFile(filePath, fileType, apply) {
+    const content = node_fs_1.default.readFileSync(filePath, 'utf8');
+    const eol = content.includes('\r\n') ? '\r\n' : '\n';
+    const lines = content.split(/\r?\n/);
+    const headingRe = (0, learning_context_builder_1.learningEntryHeadingRegex)();
+    const idRe = (0, learning_context_builder_1.learningEntryIdLineRegex)();
+    const out = [];
+    let stamped = 0;
+    let alreadyStamped = 0;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        out.push(line);
+        const header = line.match(headingRe);
+        if (!header)
+            continue;
+        // Look ahead to the next entry heading for an existing id line.
+        let hasId = false;
+        for (let j = i + 1; j < lines.length; j++) {
+            if (headingRe.test(lines[j]))
+                break;
+            if (idRe.test(lines[j].trim())) {
+                hasId = true;
+                break;
+            }
+        }
+        if (hasId) {
+            alreadyStamped++;
+            continue;
+        }
+        const title = header[2].trim();
+        if (!title)
+            continue;
+        // Insert immediately after the heading, keeping the blank line that usually
+        // follows it so the file's shape is unchanged.
+        if (lines[i + 1] !== undefined && lines[i + 1].trim() === '') {
+            out.push('');
+            out.push(`**Id**: ${(0, learning_context_builder_1.generateLearningEntryId)(fileType, title)}`);
+            i++;
+        }
+        else {
+            out.push(`**Id**: ${(0, learning_context_builder_1.generateLearningEntryId)(fileType, title)}`);
+        }
+        stamped++;
+    }
+    if (apply && stamped > 0) {
+        node_fs_1.default.writeFileSync(filePath, out.join(eol), 'utf8');
+    }
+    return { file: filePath, entriesStamped: stamped, entriesAlreadyStamped: alreadyStamped };
+}
+const FILE_TYPES = ['mistake-patterns', 'preferences', 'validated-patterns', 'manager-coaching'];
+function fileTypeFromName(fileName) {
+    for (const type of FILE_TYPES) {
+        if (fileName.includes(type))
+            return type;
+    }
+    return null;
+}
+const stampIdsCommand = addCommonOptions(new commander_1.Command('stamp-ids'))
+    .description('Add the stable Id line to learning entries that do not have one. A format migration: it inserts one identifier line per entry and changes no lesson text')
+    .option('--dir <path>', 'Learning directory to stamp (repeatable)', (value, previous) => [...previous, value], [])
+    .option('--apply', 'Write the changes. Without this flag the command reports what it would do')
+    .action((options) => {
+    const workspaceRoot = resolveWorkspaceRoot(options);
+    const dirs = options.dir.length
+        ? options.dir.map((d) => node_path_1.default.resolve(d))
+        : [node_path_1.default.join(workspaceRoot, 'fraim', 'personalized-employee', 'learnings')];
+    const results = [];
+    for (const dir of dirs) {
+        if (!node_fs_1.default.existsSync(dir))
+            continue;
+        for (const fileName of node_fs_1.default.readdirSync(dir)) {
+            if (!fileName.endsWith('.md'))
+                continue;
+            const fileType = fileTypeFromName(fileName);
+            if (!fileType)
+                continue;
+            results.push(stampFile(node_path_1.default.join(dir, fileName), fileType, Boolean(options.apply)));
+        }
+    }
+    const payload = {
+        apply: Boolean(options.apply),
+        filesScanned: results.length,
+        entriesStamped: results.reduce((sum, r) => sum + r.entriesStamped, 0),
+        entriesAlreadyStamped: results.reduce((sum, r) => sum + r.entriesAlreadyStamped, 0),
+        files: results,
+    };
+    emit(payload, options.json, () => [
+        `${payload.apply ? 'Stamped' : 'Would stamp'} ${payload.entriesStamped} entries across ${payload.filesScanned} files.`,
+        `${payload.entriesAlreadyStamped} entries already carry an id.`,
+        payload.apply ? '' : 'Re-run with --apply to write the changes.',
+    ].filter(Boolean).join('\n'));
+});
+// ── prune ────────────────────────────────────────────────────────────────────
+const pruneCommand = addCommonOptions(new commander_1.Command('prune'))
+    .description('Apply the configured retention window and log bounds to the usage record. Aggregate counters are never pruned')
+    .action((options) => {
+    const workspaceRoot = resolveWorkspaceRoot(options);
+    const limits = (0, learning_usage_store_1.resolveUsageLimits)(workspaceRoot);
+    const result = (0, learning_usage_store_1.pruneUsageStore)(limits);
+    emit({ ...result, storePath: (0, learning_usage_store_1.resolveUsageStorePath)(), limits }, options.json, () => `Pruned ${result.prunedOfferRecords} offer records and ${result.prunedFiringRecords} firing records across ${result.entries} entries. Aggregates unchanged.`);
+});
+// ── root ─────────────────────────────────────────────────────────────────────
+exports.learningUsageCommand = new commander_1.Command('learning-usage')
+    .description('Read and analyse the learning and rule usage record (issue #1103)')
+    .addCommand(offersCommand)
+    .addCommand(recordFiringsCommand)
+    .addCommand(classifyCommand)
+    .addCommand(candidatesCommand)
+    .addCommand(standingCommand)
+    .addCommand(reportCommand)
+    .addCommand(backfillCommand)
+    .addCommand(stampIdsCommand)
+    .addCommand(pruneCommand);

package/dist/src/cli/fraim.js

@@ -56,6 +56,7 @@ const workspace_config_1 = require("./commands/workspace-config");
 const org_1 = require("./commands/org");
 const manager_1 = require("./commands/manager");
 const cleanup_artifacts_1 = require("./commands/cleanup-artifacts");
+const learning_usage_1 = require("./commands/learning-usage");
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const program = new commander_1.Command();
@@ -101,6 +102,7 @@ program.addCommand(workspace_config_1.workspaceConfigCommand);
 program.addCommand(org_1.orgCommand);
 program.addCommand(manager_1.managerCommand);
 program.addCommand(cleanup_artifacts_1.cleanupArtifactsCommand);
+program.addCommand(learning_usage_1.learningUsageCommand);
 // Wait for async command initialization before parsing
 (async () => {
     // Import the initialization promise from setup command

package/dist/src/core/ai-mentor.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AIMentor = void 0;
 const include_resolver_1 = require("./utils/include-resolver");
+const resolve_phase_edge_1 = require("./resolve-phase-edge");
 class AIMentor {
     constructor(resolver, skillDedup) {
         this.jobCache = new Map();
@@ -36,7 +37,10 @@ class AIMentor {
             return await this.generateCompletionMessage(workflow, args.currentPhase, args.findings, args.evidence, args.skipIncludes);
         }
         else {
-            return await this.generateHelpMessage(workflow, args.currentPhase, args.status, args.skipIncludes);
+            // Issue #1123: findings/evidence must reach the failure path too. The
+            // MCP layer has always forwarded them for every status; only this hop
+            // dropped them, which is why a failure edge could not be discriminated.
+            return await this.generateHelpMessage(workflow, args.currentPhase, args.status, args.skipIncludes, args.findings, args.evidence);
         }
     }
     async getOrLoadJob(jobType) {
@@ -65,15 +69,21 @@ class AIMentor {
             return '';
         const onSuccess = phaseFlow.onSuccess;
         const completionCall = `seekMentoring({ jobName: "${jobName}", issueNumber: "<issue_number>", currentPhase: "${phaseId}", status: "complete" })`;
+        // Issue #1123: a routing map nobody knows how to trigger is decorative,
+        // which is the defect recorded as #1135. Whichever edge carries a map, the
+        // footer has to name its outcomes so the agent can actually supply one.
+        const failureOutcomes = (0, resolve_phase_edge_1.discriminantKeys)(phaseFlow.onFailure);
+        const failureNote = failureOutcomes.length > 0
+            ? `\nIf this phase needs to loop back, call the same tool with \`status: "failure"\`, and set \`findings.phaseOutcome\` to one of: ${failureOutcomes.map((key) => `"${key}"`).join(' | ')} when one applies. Omit it otherwise.`
+            : '';
         if (!onSuccess || typeof onSuccess === 'string') {
             const finalPhaseNote = onSuccess ? '' : ' This is the final phase.';
-            return `\n\n---\n\n## Report Back\nWhen this phase is done, call \`${completionCall}\`.${finalPhaseNote}`;
+            return `\n\n---\n\n## Report Back\nWhen this phase is done, call \`${completionCall}\`.${finalPhaseNote}${failureNote}`;
         }
-        const validOutcomes = Object.keys(onSuccess)
-            .filter((key) => key !== 'default')
+        const validOutcomes = (0, resolve_phase_edge_1.discriminantKeys)(onSuccess)
             .map((key) => `"${key}"`)
             .join(' | ');
-        return `\n\n---\n\n## Report Back\nWhen this phase is done, call \`seekMentoring({ jobName: "${jobName}", issueNumber: "<issue_number>", currentPhase: "${phaseId}", status: "complete", findings: { issueType: "<outcome>" } })\` with one of: ${validOutcomes}.`;
+        return `\n\n---\n\n## Report Back\nWhen this phase is done, call \`seekMentoring({ jobName: "${jobName}", issueNumber: "<issue_number>", currentPhase: "${phaseId}", status: "complete", findings: { issueType: "<outcome>" } })\` with one of: ${validOutcomes}.${failureNote}`;
     }
     /** Phase-authority content injected for all phased workflows. Loaded from orchestration/phase-authority.md. */
     async getPhaseAuthorityContent() {
@@ -158,13 +168,9 @@ class AIMentor {
         const phaseFlow = workflow.metadata.phases?.[phaseId];
         let nextPhaseId = null;
         if (phaseFlow && phaseFlow.onSuccess) {
-            if (typeof phaseFlow.onSuccess === 'string') {
-                nextPhaseId = phaseFlow.onSuccess;
-            }
-            else {
-                const outcome = findings?.phaseOutcome ?? findings?.issueType ?? evidence?.issueType ?? evidence?.phaseOutcome ?? 'default';
-                nextPhaseId = phaseFlow.onSuccess[outcome] ?? phaseFlow.onSuccess.default ?? null;
-            }
+            // Issue #1123: resolved through the shared authority so the success and
+            // failure paths cannot read the discriminant differently.
+            nextPhaseId = (0, resolve_phase_edge_1.resolvePhaseEdge)(phaseFlow.onSuccess, (0, resolve_phase_edge_1.resolveDiscriminant)(findings, evidence));
         }
         let message = '';
         if (nextPhaseId) {
@@ -189,7 +195,7 @@ class AIMentor {
             status: 'complete'
         };
     }
-    async generateHelpMessage(workflow, phaseId, status, skipIncludes) {
+    async generateHelpMessage(workflow, phaseId, status, skipIncludes, findings, evidence) {
         const entityType = 'Job';
         if (workflow.isSimple) {
             const message = `${entityType}: ${workflow.metadata.name}\n\n${workflow.overview}`;
@@ -201,7 +207,14 @@ class AIMentor {
             };
         }
         const phaseMeta = workflow.metadata.phases?.[phaseId];
-        const targetPhaseId = status === 'failure' ? (phaseMeta?.onFailure || phaseId) : phaseId;
+        // Issue #1123: the failure edge may be a discriminant map. Resolving to
+        // null (terminal, malformed, or a map with no `default` and no match)
+        // falls back to self-retry, which is what the previous `|| phaseId` did
+        // for an absent edge. The old expression could not do this: an object is
+        // truthy, so it was returned as the target and `phases.get()` then missed.
+        const targetPhaseId = status === 'failure'
+            ? ((0, resolve_phase_edge_1.resolvePhaseEdge)(phaseMeta?.onFailure, (0, resolve_phase_edge_1.resolveDiscriminant)(findings, evidence)) || phaseId)
+            : phaseId;
         let message = `### Current Phase: ${targetPhaseId}\n\n`;
         let instructions = workflow.phases.get(targetPhaseId);
         if (instructions) {