fraim 2.0.342 → 2.0.344

package/dist/src/local-mcp-server/learning-usage-attestation.js

@@ -2,7 +2,9 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.extractLegacyTitle = exports.parseFiringSection = void 0;
 exports.recordAttestationsFromRetrospective = recordAttestationsFromRetrospective;
+exports.readRetrospectiveForAttestation = readRetrospectiveForAttestation;
 exports.runBackfill = runBackfill;
+const artifact_paths_1 = require("../../registry/scripts/artifact-paths");
 /**
  * Issue #1103 — turning an attestation into a usage record.
  *
@@ -18,6 +20,7 @@ exports.runBackfill = runBackfill;
  */
 const fs_1 = require("fs");
 const path_1 = require("path");
+const learning_source_record_1 = require("./learning-source-record");
 const learning_usage_store_1 = require("./learning-usage-store");
 const learning_firing_parser_1 = require("./learning-firing-parser");
 const learning_context_builder_1 = require("./learning-context-builder");
@@ -160,69 +163,76 @@ function recordAttestationsFromRetrospective(workspaceRoot, userId, options) {
         rejected: parsed.rejected,
     };
 }
-function jobFromFrontmatter(content) {
-    const match = content.match(/^job:\s*(.+)$/m);
-    return match ? match[1].trim() : 'unknown';
+// ── R15: backfill ────────────────────────────────────────────────────────────
+/** Resolve live attestation against its recorded home and immutable accounting identity. */
+function readRetrospectiveForAttestation(workspaceRoot, userId, filePath) {
+    let reason = 'Retrospective is outside configured learning homes';
+    for (const home of (0, learning_context_builder_1.getLearningInputHomes)(workspaceRoot)) {
+        const result = (0, learning_context_builder_1.readLearningSourceFile)((0, path_1.resolve)(filePath), home.root, home.contentRoot);
+        if (result.status !== 'valid') {
+            reason = result.reason;
+            continue;
+        }
+        if (result.record.kind !== 'retrospective' || result.record.author !== userId) {
+            throw new Error('Retrospective kind or author does not match this attestation');
+        }
+        return { content: result.content, record: result.record };
+    }
+    throw new Error(`Invalid learning retrospective: ${reason}`);
 }
-/**
- * Read every retrospective and apply the firings it attests.
- *
- * Best effort by design (R15): only an id or an exact title resolves, and the
- * unmatched count is reported rather than resolved by fuzzy matching. A low match
- * rate is an expected outcome to state, not a failure to hide — only a small
- * fraction of the existing attestations name a machine-matchable identifier.
- *
- * A retrospective already stamped `synthesized` is still read: being synthesized
- * for learning content is not the same as having contributed usage data.
- */
+/** Read only typed future reflections, including archives, with stable accounting identity. */
 function runBackfill(workspaceRoot, userId, options) {
     const limits = options.limits ?? (0, learning_usage_store_1.resolveUsageLimits)(workspaceRoot);
-    const dir = options.retrospectivesDir ?? (0, path_1.join)(workspaceRoot, 'docs', 'retrospectives');
     const report = {
         filesScanned: 0, filesWithSection: 0, itemsRead: 0, applied: 0,
-        alreadyRecorded: 0, unmatched: [], rejected: [], synthesizedFilesRead: 0,
+        alreadyRecorded: 0, unmatched: [], rejected: [], synthesizedFilesRead: 0, invalidRecords: [],
     };
-    if (!(0, fs_1.existsSync)(dir))
-        return report;
-    let files;
-    try {
-        files = (0, fs_1.readdirSync)(dir).filter((f) => f.endsWith('.md'));
-    }
-    catch {
-        return report;
-    }
-    for (const file of files) {
-        let content;
-        try {
-            content = (0, fs_1.readFileSync)((0, path_1.join)(dir, file), 'utf8');
-        }
-        catch {
-            continue;
+    const seen = new Set();
+    for (const home of (0, learning_context_builder_1.getLearningInputHomes)(workspaceRoot)) {
+        const paths = (0, artifact_paths_1.resolveLearningPaths)(home.root, home.contentRoot);
+        for (const dir of [paths.retrospectives, paths.archiveRetrospectives]) {
+            if (options.retrospectivesDir && (0, learning_source_record_1.normalizeLearningSourcePath)(dir) !== (0, learning_source_record_1.normalizeLearningSourcePath)(options.retrospectivesDir))
+                continue;
+            let files;
+            try {
+                if ((0, fs_1.lstatSync)(dir).isSymbolicLink())
+                    continue;
+                files = (0, fs_1.readdirSync)(dir).filter(f => f.endsWith('.md'));
+            }
+            catch {
+                continue;
+            }
+            for (const file of files) {
+                const filePath = (0, path_1.join)(dir, file);
+                const parsed = (0, learning_context_builder_1.readLearningSourceFile)(filePath, home.root, home.contentRoot);
+                if (parsed.status !== 'valid') {
+                    if (parsed.status === 'invalid')
+                        report.invalidRecords.push({ path: filePath, reason: parsed.reason });
+                    continue;
+                }
+                const { record } = parsed;
+                if (record.kind !== 'retrospective' || record.author !== userId)
+                    continue;
+                if (seen.has(record.usageSourceRef))
+                    continue;
+                seen.add(record.usageSourceRef);
+                report.filesScanned++;
+                if (record.synthesized)
+                    report.synthesizedFilesRead++;
+                const result = recordAttestationsFromRetrospective(workspaceRoot, userId, {
+                    content: parsed.content, source: record.usageSourceRef, job: record.job, date: record.date,
+                    agent: options.agent, model: options.model, legacy: false,
+                    limits, now: options.now, storePath: options.storePath, integrityMode: 'flag',
+                });
+                if (result.sectionState !== 'absent')
+                    report.filesWithSection++;
+                report.itemsRead += result.itemsRead;
+                report.applied += result.applied;
+                report.alreadyRecorded += result.alreadyRecorded;
+                report.unmatched.push(...result.unmatched);
+                report.rejected.push(...result.rejected);
+            }
         }
-        report.filesScanned += 1;
-        if (/^synthesized:\s*\S/m.test(content))
-            report.synthesizedFilesRead += 1;
-        const result = recordAttestationsFromRetrospective(workspaceRoot, userId, {
-            content,
-            source: `docs/retrospectives/${file}`,
-            job: jobFromFrontmatter(content),
-            agent: options.agent,
-            model: options.model,
-            legacy: true,
-            limits,
-            now: options.now,
-            storePath: options.storePath,
-            // A backfill reconciles hundreds of retrospectives at once, so a single
-            // stranded-offer entry must not refuse the whole run.
-            integrityMode: 'flag',
-        });
-        if (result.sectionState !== 'absent')
-            report.filesWithSection += 1;
-        report.itemsRead += result.itemsRead;
-        report.applied += result.applied;
-        report.alreadyRecorded += result.alreadyRecorded;
-        report.unmatched.push(...result.unmatched);
-        report.rejected.push(...result.rejected);
     }
     return report;
 }

package/dist/src/local-mcp-server/learning-usage-command.js

@@ -134,12 +134,13 @@ const recordFiringsCommand = addCommonOptions(new commander_1.Command('record-fi
     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 { content, record } = (0, learning_usage_attestation_1.readRetrospectiveForAttestation)(workspaceRoot, user, filePath);
+    const source = record.usageSourceRef;
     const result = (0, learning_usage_attestation_1.recordAttestationsFromRetrospective)(workspaceRoot, user, {
         content,
         source,
-        job: options.job ?? 'unknown',
+        job: record.job,
+        date: record.date,
         agent: options.agent ?? null,
         model: options.model ?? null,
         legacy: Boolean(options.legacy),
@@ -387,7 +388,7 @@ function defaultStampDirs(workspaceRoot) {
     const dirs = [node_path_1.default.join(workspaceRoot, 'fraim', 'personalized-employee', 'learnings')];
     for (const level of ['org', 'manager']) {
         try {
-            dirs.push(node_path_1.default.join((0, pack_home_1.resolvePackHome)(level).contentRoot, 'learnings'));
+            dirs.push(node_path_1.default.join((0, pack_home_1.resolvePackHome)(level, { migrateLegacy: false }).contentRoot, 'learnings'));
         }
         catch {
             // A pack home that does not resolve is simply not stamped. Reported by the

package/dist/src/local-mcp-server/stdio-server.js

@@ -59,6 +59,7 @@ const path_1 = require("path");
 const os_1 = require("os");
 const child_process_1 = require("child_process");
 const crypto_1 = require("crypto");
+const local_runtime_1 = require("../../registry/scripts/learning-usage/local-runtime");
 const axios_1 = __importDefault(require("axios"));
 const provider_utils_1 = require("../core/utils/provider-utils");
 const object_utils_1 = require("../core/utils/object-utils");
@@ -79,6 +80,7 @@ const learning_context_builder_js_1 = require("./learning-context-builder.js");
 const learning_usage_store_js_1 = require("./learning-usage-store.js");
 const learning_domains_js_1 = require("../config/learning-domains.js");
 const skill_include_dedup_js_1 = require("./skill-include-dedup.js");
+const git_utils_1 = require("../core/utils/git-utils");
 /**
  * Handle template substitution logic separately for better testability
  */
@@ -171,7 +173,7 @@ class FraimTemplateEngine {
         try {
             const configPath = (0, path_1.join)(this.projectRoot, 'fraim', 'config.json');
             if ((0, fs_1.existsSync)(configPath)) {
-                this.config = JSON.parse((0, fs_1.readFileSync)(configPath, 'utf8'));
+                this.config = (0, local_runtime_1.readJsonIfObject)(configPath, { strict: true });
                 this.configLoadAttempted = true;
                 return this.config;
             }
@@ -742,8 +744,7 @@ class FraimLocalMCPServer {
             const configPath = (0, project_fraim_paths_1.getWorkspaceConfigPath)(projectDir);
             this.log(`🔍 Looking for config at: ${configPath}`);
             if ((0, fs_1.existsSync)(configPath)) {
-                const configContent = (0, fs_1.readFileSync)(configPath, 'utf8');
-                this.config = JSON.parse(configContent);
+                this.config = (0, local_runtime_1.readJsonIfObject)(configPath, { strict: true });
                 this.log(`Loaded local ${(0, project_fraim_paths_1.getWorkspaceFraimDisplayPath)('config.json')}`);
             }
             else {
@@ -1119,7 +1120,7 @@ class FraimLocalMCPServer {
             catch {
                 branch = '';
             }
-            const defaultBranch = this.config?.repository?.defaultBranch || '';
+            const defaultBranch = this.config?.repository?.defaultBranch || (0, git_utils_1.getDefaultBranch)(projectDir) || '';
             const repoInfo = {
                 url: repoUrl,
                 name: name || 'unknown',
@@ -1301,7 +1302,9 @@ class FraimLocalMCPServer {
             }
             const timestamp = new Date().toISOString();
             const accepted = acceptedNext !== undefined;
-            const currentPhase = accepted
+            const recoveringTerminalReview = previous?.status === 'waiting_review' && previous.currentPhase === null
+                && (args.status === 'starting' || args.status === 'incomplete');
+            const currentPhase = recoveringTerminalReview ? null : accepted
                 ? (args.status === 'complete' ? acceptedNext.nextPhase : acceptedNext.nextPhase || args.currentPhase)
                 : previous ? previous.currentPhase : args.currentPhase;
             const completedPhases = previous?.completedPhases || [];
@@ -1371,7 +1374,7 @@ class FraimLocalMCPServer {
             updated.phaseInstances = updated.phaseInstances?.filter((instance) => instance.jobId && instance.jobId !== args.jobId);
         }
         this.writeRunStateMarker(sessionId, args.jobName, updated);
-        return (inspection.missingStart ? (0, handoff_contracts_1.buildPhaseStartWarning)(args.currentPhase) : '')
+        return (inspection.missingStart ? (0, handoff_contracts_1.buildPhaseStartWarning)(args.currentPhase, nextPhase ?? undefined) : '')
             + (!args.jobId ? `Run-tracking notice: phase ${args.currentPhase} has no jobId; matching used the session, job name and phase.\n\n` : '');
     }
     readCachedTemplateFile(filename) {
@@ -3109,7 +3112,7 @@ class FraimLocalMCPServer {
                 const requestId = request.id;
                 const cached = this.jobStartCache.get(requestId);
                 if (cached) {
-                    args = { ...args, jobId: cached.jobId, action: 'start' };
+                    args = { ...args, jobId: cached.jobId, action: 'start', isReload: false };
                     this.jobStartCache.delete(requestId);
                     this.log(`📊 Enriched get_fraim_job args with jobId=${cached.jobId}, action=start`);
                 }

package/dist/src/local-mcp-server/usage-collector.js

@@ -147,6 +147,8 @@ class UsageCollector {
                     analyticsArgs.job = args.job;
                 if (args.action)
                     analyticsArgs.action = args.action;
+                if (typeof args.isReload === 'boolean')
+                    analyticsArgs.isReload = args.isReload;
                 break;
             case 'fraim_connect':
                 if (args.agent?.name)

package/dist/src/mcp/tool-schemas.js

@@ -343,13 +343,17 @@ Do not use this tool for other repositories or external project issue trackers.`
                     },
                     currentPhase: {
                         type: 'string',
-                        description: 'The phase you are currently in or have just finished (e.g., "implement-scoping"). For initial workflow start, use "starting".'
+                        description: 'The phase you are currently in or have just finished (e.g., "implement-scoping"). For initial workflow start, pass "starting" as a one-time bootstrap — this is distinct from the per-phase status:"starting" on-arrival call you make at the beginning of every phase.'
                     },
                     status: {
                         type: 'string',
                         description: 'Status of your work in the current phase.',
                         enum: ['starting', 'complete', 'incomplete', 'failure']
                     },
+                    requestInstructions: {
+                        type: 'boolean',
+                        description: 'On a starting call, pass true to restore full phase and skill instructions after context loss. Ordinary arrivals acknowledge the phase without repeating instructions already delivered by the previous response. Initial and recurring entry still deliver instructions.'
+                    },
                     findings: {
                         type: 'object',
                         description: 'Your findings, summaries, or results from the current phase (required for status="complete")',

package/dist/src/services/mcp-service.js

@@ -548,9 +548,9 @@ class McpService {
             '- Use FRAIM when the user explicitly invokes FRAIM, names a FRAIM job, asks what FRAIM job to run, or the active surface has already selected a FRAIM job.',
             '- For ordinary requests, answer or work normally. Do not scan FRAIM stubs first.',
             '- If the user already named a job, call `get_fraim_job({ job: "<job-name>" })` directly.',
-            '- If routing is active and local FRAIM job stubs are present under `fraim/ai-employee/jobs/` or `fraim/ai-manager/jobs/`, read that directory\'s `INDEX.md` first (name, one-line intent, and category per job) to choose the best job; open an individual stub only to confirm a shortlisted candidate, or fall back to scanning the stubs directly if no `INDEX.md` is present.',
+            '- If routing is active and no exact job is named, read `~/.fraim/ai-employee/jobs/INDEX.md` and `~/.fraim/ai-manager/jobs/INDEX.md` first (name, one-line intent, and category per job) to choose the best job; open an individual stub only to confirm a shortlisted candidate, or fall back to scanning stubs in those machine directories if an index is missing or stale. Project baseline catalog directories are not required.',
             '- Also check `fraim/personalized-employee/jobs/` (and its own `INDEX.md`, if present) for local job overrides or repo-specific jobs when routing is active.',
-            '- If local stubs are missing, you cannot inspect workspace files, or the user asks for available jobs, call `list_fraim_jobs()` to view the full catalog.',
+            '- If machine stubs are missing, you cannot inspect local files, or the user asks for available jobs, call `list_fraim_jobs()` to view the full catalog.',
             '- If no exact or high-confidence job match exists, say that no FRAIM job matches and continue with normal tools or ask one concise clarification.',
             '- Use `get_fraim_file(...)` only for the specific skills or rules needed for the current task.',
             '- Once a phased job starts, use `seekMentoring` for phase-specific instructions and transitions.'
@@ -712,7 +712,8 @@ class McpService {
             currentPhase: args.currentPhase,
             status: args.status,
             evidence: args.evidence,
-            findings: args.findings
+            findings: args.findings,
+            requestInstructions: args.requestInstructions
         });
         // Handoff contract enforcement (Issue #916/#1157/#1276) fall-through
         // safety net, matching the quality-enforcement note just below.
@@ -824,7 +825,7 @@ class McpService {
             else if (isPhaseCompletion) {
                 const inspection = (0, handoff_contracts_1.inspectPhaseCompletion)(marker, context);
                 if (inspection.missingStart)
-                    phaseStartWarning = (0, handoff_contracts_1.buildPhaseStartWarning)(args.currentPhase);
+                    phaseStartWarning = (0, handoff_contracts_1.buildPhaseStartWarning)(args.currentPhase, result.nextPhase ?? undefined);
                 const completed = (0, handoff_contracts_1.commitPhaseCompletion)(marker, inspection, { ...context, timestamp });
                 this.phaseStartMarkers.set(markerKey, completed);
                 if (args.status === 'complete' && result.nextPhase === null) {
@@ -924,6 +925,7 @@ class McpService {
                     status: args.status,
                     evidence: args.evidence,
                     findings: args.findings,
+                    requestInstructions: args.requestInstructions,
                     skipIncludes: true // ← the key difference: raw, no include resolution
                 });
                 return { content: [{ type: 'text', text: result.message }] };

package/dist/src/services/usage-analytics-service.js

@@ -254,6 +254,7 @@ class UsageAnalyticsService {
     async logJobStart(jobId, jobName, userId, sessionId, issueNumber) {
         const jobStartEvent = UsageAnalyticsService.createUsageEvent('job', jobName, userId, sessionId, true, {
             action: 'start',
+            isReload: false,
             issueNumber,
             jobId
         }, await this.resolveCategory(jobName), jobId);

package/package.json

@@ -1,12 +1,14 @@
 {
   "name": "fraim",
-  "version": "2.0.342",
+  "version": "2.0.344",
   "description": "FRAIM core CLI and MCP package.",
   "main": "index.js",
   "bin": {
     "fraim": "bin/fraim.js"
   },
   "files": [
+    "dist/registry/scripts/artifact-paths.js",
+    "dist/registry/scripts/learning-usage/local-runtime.js",
     "dist/registry/scripts/learning/learning-domains.json",
     "dist/registry/scripts/learning/entry-format.js",
     "dist/registry/scripts/learning/completion-state.js",