fraim 2.0.270 → 2.0.271

package/dist/src/core/config-loader.js

@@ -3,14 +3,40 @@
  * FRAIM Configuration Loader
  * Loads and validates workspace FRAIM config with fallback to defaults.
  */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.resetDetectedDefaultBranchCache = resetDetectedDefaultBranchCache;
 exports.normalizeFraimConfig = normalizeFraimConfig;
 exports.loadFraimConfig = loadFraimConfig;
 exports.getConfigValue = getConfigValue;
 exports.getRepositoryInfo = getRepositoryInfo;
 const fs_1 = require("fs");
+const path_1 = __importDefault(require("path"));
 const types_1 = require("./types");
 const project_fraim_paths_1 = require("./utils/project-fraim-paths");
+const git_utils_1 = require("./utils/git-utils");
+/**
+ * Issue #1164: detection shells out to git, and config normalization runs on every
+ * load, so answers are cached. The cache is keyed by the directory inspected, not
+ * global: a long-lived process such as the Hub server normalizes configs for
+ * several projects, and a single cached answer would apply one repository's
+ * default branch to another. `null` is a real, cacheable result meaning "no
+ * default branch could be determined for this directory".
+ */
+const detectedDefaultBranchByDir = new Map();
+function detectDefaultBranchOnce(detectionCwd) {
+    const key = detectionCwd ? path_1.default.resolve(detectionCwd) : '';
+    if (!detectedDefaultBranchByDir.has(key)) {
+        detectedDefaultBranchByDir.set(key, (0, git_utils_1.getDefaultBranch)(detectionCwd));
+    }
+    return detectedDefaultBranchByDir.get(key) ?? null;
+}
+/** Test seam: lets a test exercise both detection outcomes without a real repo. */
+function resetDetectedDefaultBranchCache() {
+    detectedDefaultBranchByDir.clear();
+}
 function normalizeCustomerCommunication(config) {
     const current = config?.['customer-communication'];
     if (!current || typeof current !== 'object')
@@ -91,7 +117,7 @@ function normalizeAutomation(config) {
         }
     };
 }
-function normalizeFraimConfig(config) {
+function normalizeFraimConfig(config, options = {}) {
     // Handle backward compatibility and migration
     const mergedConfig = {
         project: {
@@ -106,7 +132,9 @@ function normalizeFraimConfig(config) {
                 provider: config.git.provider || 'github',
                 owner: config.git.repoOwner,
                 name: config.git.repoName,
-                defaultBranch: config.git.defaultBranch || 'main'
+                // Issue #1164: no `|| 'main'`. An undeclared default branch is
+                // resolved from git below, or left absent.
+                ...(config.git.defaultBranch ? { defaultBranch: config.git.defaultBranch } : {})
             } : {})
         },
         customizations: {
@@ -114,6 +142,19 @@ function normalizeFraimConfig(config) {
             ...(config.customizations || {})
         }
     };
+    // Issue #1164: an undeclared default branch is resolved from the repository
+    // itself rather than guessed. When detection fails the field stays absent, so
+    // a consumer renders a visible placeholder instead of silently targeting a
+    // branch that may not exist.
+    if (mergedConfig.repository && !mergedConfig.repository.defaultBranch) {
+        const detected = detectDefaultBranchOnce(options.detectionCwd);
+        if (detected) {
+            mergedConfig.repository.defaultBranch = detected;
+        }
+        else {
+            delete mergedConfig.repository.defaultBranch;
+        }
+    }
     if (config.customizations?.postCleanupHook || config.customizations?.cleanupCommand) {
         if (!mergedConfig.customizations)
             mergedConfig.customizations = {};
@@ -158,7 +199,11 @@ function loadFraimConfig(configPath = (0, project_fraim_paths_1.getWorkspaceConf
     try {
         const configContent = (0, fs_1.readFileSync)(configPath, 'utf-8');
         const config = JSON.parse(configContent);
-        const mergedConfig = normalizeFraimConfig(config);
+        // Issue #1164: detection must inspect the workspace this config belongs to,
+        // not whatever directory the process happens to be running in. The config
+        // lives at <workspaceRoot>/fraim/config.json.
+        const workspaceRoot = path_1.default.dirname(path_1.default.dirname(path_1.default.resolve(configPath)));
+        const mergedConfig = normalizeFraimConfig(config, { detectionCwd: workspaceRoot });
         console.log(`Loaded FRAIM config from ${displayPath}`);
         if (config.git && !config.repository) {
             console.warn('Deprecated: "git" config detected. Consider migrating to "repository" config.');

package/dist/src/core/fraim-config-schema.generated.js

@@ -213,6 +213,20 @@ exports.FRAIM_CONFIG_SCHEMA = {
                 },
                 "globalPath": {
                     "kind": "string"
+                },
+                "usage": {
+                    "kind": "object",
+                    "properties": {
+                        "firingLogLimit": {
+                            "kind": "number"
+                        },
+                        "offerLogLimit": {
+                            "kind": "number"
+                        },
+                        "retirementOfferThreshold": {
+                            "kind": "number"
+                        }
+                    }
                 }
             }
         },
@@ -646,6 +660,10 @@ exports.SUPPORTED_FRAIM_CONFIG_PATHS = [
     "learning.lastSynthesisDate",
     "learning.scoreThreshold",
     "learning.globalPath",
+    "learning.usage",
+    "learning.usage.firingLogLimit",
+    "learning.usage.offerLogLimit",
+    "learning.usage.retirementOfferThreshold",
     "customer-communication",
     "customer-communication.productName",
     "customer-communication.productUrl",

package/dist/src/core/handoff-contracts.js

@@ -18,7 +18,9 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.isSubmitPhase = isSubmitPhase;
 exports.isRetrospectivePhase = isRetrospectivePhase;
+exports.isAddressFeedbackCompletion = isAddressFeedbackCompletion;
 exports.isDelegationGraphPhase = isDelegationGraphPhase;
+exports.validateAddressFeedbackApproval = validateAddressFeedbackApproval;
 exports.validateReviewHandoff = validateReviewHandoff;
 exports.validateNextJobRecommendations = validateNextJobRecommendations;
 exports.validateDelegationLedger = validateDelegationLedger;
@@ -43,6 +45,13 @@ function isSubmitPhase(currentPhase, status) {
 function isRetrospectivePhase(currentPhase, status) {
     return currentPhase === 'retrospective' && status === 'complete';
 }
+/**
+ * Returns true when a seekMentoring call is address-feedback completing.
+ * Completing address-feedback requires manager approval (evidence.approved: true).
+ */
+function isAddressFeedbackCompletion(currentPhase, status) {
+    return currentPhase === 'address-feedback' && status === 'complete';
+}
 /**
  * Returns true when a seekMentoring call is the delegation graph phase.
  * This matches the existing Hub test fixture for the delegation board.
@@ -53,6 +62,20 @@ function isDelegationGraphPhase(currentPhase) {
 // ---------------------------------------------------------------------------
 // Individual validators
 // ---------------------------------------------------------------------------
+/**
+ * Validates that evidence.approved is true for address-feedback completion.
+ * Returns null if valid, or an array of error strings.
+ */
+function validateAddressFeedbackApproval(evidence) {
+    if (evidence.approved !== true) {
+        return [
+            `evidence.approved must be true when completing address-feedback. ` +
+                `Set evidence.approved: true only after the manager has explicitly approved the work. ` +
+                `If the manager has not yet approved, set status: "failure" to re-enter the review loop.`,
+        ];
+    }
+    return null;
+}
 /**
  * Validates evidence.reviewHandoff. Returns null if valid, or an array of
  * human-readable error strings describing what is wrong.
@@ -213,11 +236,21 @@ function validateHandoffContracts(args) {
         if (errors)
             return errors;
     }
+    if (isAddressFeedbackCompletion(phase, status)) {
+        const errors = validateAddressFeedbackApproval(evidence);
+        if (errors)
+            return errors;
+    }
     return [];
 }
 // ---------------------------------------------------------------------------
 // Rejection message builder
 // ---------------------------------------------------------------------------
+const ADDRESS_FEEDBACK_APPROVAL_SCHEMA = `\`\`\`javascript
+evidence: {
+  approved: true  // Set only after the manager explicitly approves via the Hub review action
+}
+\`\`\``;
 const REVIEW_HANDOFF_SCHEMA = `\`\`\`javascript
 evidence: {
   reviewHandoff: {
@@ -257,6 +290,7 @@ evidence: {
 }
 \`\`\``;
 const FIELD_SCHEMAS = {
+    approved: ADDRESS_FEEDBACK_APPROVAL_SCHEMA,
     reviewHandoff: REVIEW_HANDOFF_SCHEMA,
     nextJobRecommendations: NEXT_JOB_RECOMMENDATIONS_SCHEMA,
     delegationLedger: DELEGATION_LEDGER_SCHEMA,
@@ -280,6 +314,8 @@ function buildHandoffRejectionMessage(currentPhase, field, errors) {
         '',
         schemaHint,
         '',
-        `The job is **not** marked complete. Add the \`evidence.${field}\` object and resubmit this phase.`,
+        field === 'approved'
+            ? 'The job is **not** marked complete. Set `evidence.approved: true` (only after explicit manager approval) and resubmit.'
+            : `The job is **not** marked complete. Add the \`evidence.${field}\` object and resubmit this phase.`,
     ].join('\n');
 }

package/dist/src/core/job-phases.js

@@ -9,6 +9,7 @@ exports.labelForPhaseId = labelForPhaseId;
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const project_fraim_paths_1 = require("./utils/project-fraim-paths");
+const resolve_phase_edge_1 = require("./resolve-phase-edge");
 const EMPLOYEE_JOB_LAYERS = [
     { segments: ['ai-employee', 'jobs'] },
     { segments: ['personalized-employee', 'jobs'] },
@@ -99,19 +100,6 @@ function findJobStubPath(projectPath, jobId) {
     }
     return null;
 }
-function nextPhase(edge, discriminant) {
-    if (edge == null)
-        return null;
-    if (typeof edge === 'string')
-        return edge;
-    if (typeof edge === 'object') {
-        if (typeof edge[discriminant] === 'string')
-            return edge[discriminant];
-        if (typeof edge.default === 'string')
-            return edge.default;
-    }
-    return null;
-}
 function loadJobPhasesFromSteps(filePath) {
     const raw = fs_1.default.readFileSync(filePath, 'utf8');
     const stepsMatch = raw.match(/## Steps\r?\n([\s\S]*?)(?:\r?\n## |\r?\n---|$)/);
@@ -141,7 +129,7 @@ function loadJobPhases(jobId, projectPath, discriminant = 'feature') {
         const phaseDef = fm.phases[cursor];
         if (!phaseDef)
             break;
-        cursor = nextPhase(phaseDef.onSuccess, discriminant);
+        cursor = (0, resolve_phase_edge_1.resolvePhaseEdge)(phaseDef.onSuccess, discriminant);
     }
     const labels = fm.phaseLabels || {};
     return ordered.map((id) => ({ id, label: friendlyPhaseLabel(id, labels[id]) }));

package/dist/src/core/resolve-phase-edge.js

@@ -0,0 +1,75 @@
+"use strict";
+/**
+ * Single authority for resolving a job phase transition (issue #1123).
+ *
+ * A phase edge (`onSuccess` or `onFailure`) is either a phase id, a discriminant
+ * map, or terminal. Before this module the identical resolver existed twice, in
+ * `src/core/job-phases.ts` and `src/ai-hub/catalog.ts`, and the discriminant
+ * precedence lived a third time inline in `src/core/ai-mentor.ts`. Three copies of
+ * one rule is how the success and failure paths drift apart, which is exactly the
+ * class of defect this issue is about.
+ *
+ * Both edges accept a map. A map must declare `default`; an unset or unrecognised
+ * discriminant resolves to it, so a job can never route somewhere unexpected. A
+ * string edge never consults a discriminant at all, which is what makes this
+ * change inert for every job that authors no map.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolvePhaseEdge = resolvePhaseEdge;
+exports.resolveDiscriminant = resolveDiscriminant;
+exports.discriminantKeys = discriminantKeys;
+/** The default discriminant, and the mandatory key on every authored map. */
+const DEFAULT_DISCRIMINANT = 'default';
+/**
+ * Resolve an edge to the next phase id.
+ *
+ * Returns `null` when the edge is terminal, when a map resolves to nothing, or
+ * when the edge is malformed. Callers decide what a `null` means for them:
+ * `loadJobPhases` stops walking, `ai-mentor` falls back to self-retry.
+ */
+function resolvePhaseEdge(edge, discriminant) {
+    if (edge == null)
+        return null;
+    if (typeof edge === 'string')
+        return edge;
+    if (typeof edge === 'object') {
+        if (typeof edge[discriminant] === 'string')
+            return edge[discriminant];
+        if (typeof edge[DEFAULT_DISCRIMINANT] === 'string')
+            return edge[DEFAULT_DISCRIMINANT];
+    }
+    return null;
+}
+/**
+ * The discriminant an agent supplied on a `seekMentoring` call.
+ *
+ * `phaseOutcome` is the general form and `issueType` the original narrower one;
+ * both are accepted from either `findings` or `evidence` so an agent following
+ * older phase text still routes correctly. This precedence is deliberately shared
+ * by the success and failure paths: if they read the discriminant differently,
+ * the same call would route two ways depending on its status.
+ */
+function resolveDiscriminant(findings, evidence) {
+    const read = (source, key) => {
+        if (!source || typeof source !== 'object')
+            return null;
+        const value = source[key];
+        return typeof value === 'string' && value.length > 0 ? value : null;
+    };
+    return (read(findings, 'phaseOutcome')
+        ?? read(findings, 'issueType')
+        ?? read(evidence, 'issueType')
+        ?? read(evidence, 'phaseOutcome')
+        ?? DEFAULT_DISCRIMINANT);
+}
+/**
+ * The discriminant keys a map edge offers, excluding `default`.
+ *
+ * Used to tell the agent which outcomes a phase accepts. A routing map nobody
+ * knows how to trigger is decorative, which is the failure recorded as #1135.
+ */
+function discriminantKeys(edge) {
+    if (!edge || typeof edge !== 'object')
+        return [];
+    return Object.keys(edge).filter((key) => key !== DEFAULT_DISCRIMINANT);
+}

package/dist/src/core/types.js

@@ -17,7 +17,13 @@ exports.DEFAULT_FRAIM_CONFIG = {
         provider: 'github',
         owner: '',
         name: '',
-        defaultBranch: 'main'
+        // Issue #1164: deliberately no defaultBranch. `owner` and `name` default to
+        // the empty string, which is obviously missing and fails loudly downstream.
+        // A default branch name does not have that property: `'main'` is
+        // indistinguishable from a real answer, so it silently targeted pull
+        // requests at a branch this repository does not have. An absent value is
+        // resolved from git in `normalizeFraimConfig`, and left absent when it
+        // cannot be determined.
     },
     customizations: {}
 };

package/dist/src/core/utils/git-utils.js

@@ -77,6 +77,9 @@ function getPort() {
  * Determines the database name based on the git branch
  */
 function determineDatabaseName() {
+    if (process.env.MONGODB_DB_NAME) {
+        return process.env.MONGODB_DB_NAME;
+    }
     try {
         const branchName = process.env.FRAIM_BRANCH || process.env.FRAIM_BRANCH_NAME || (0, child_process_1.execSync)('git rev-parse --abbrev-ref HEAD').toString().trim();
         const issueMatch = branchName.match(/issue-(\d+)/i) || branchName.match(/(\d+)-/);
@@ -87,7 +90,7 @@ function determineDatabaseName() {
     catch (e) {
         // Silently fail
     }
-    return process.env.MONGODB_DB_NAME || (process.env.NODE_ENV === 'production' ? 'fraim_prod' : 'fraim_dev');
+    return process.env.NODE_ENV === 'production' ? 'fraim_prod' : 'fraim_dev';
 }
 /**
  * Gets the current git branch name
@@ -114,14 +117,28 @@ function determineSchema(branchName) {
     return 'prod';
 }
 /**
- * Gets the default branch name from git remote
+ * Gets the default branch name from the git remote, or `null` when it cannot be
+ * determined.
+ *
+ * Issue #1164: this deliberately reports failure instead of guessing. A branch
+ * name is used to target pull requests, so a wrong-but-plausible answer is worse
+ * than no answer: it opens a PR against a branch that may not exist. Two earlier
+ * fallbacks are removed for that reason:
+ *
+ *   - falling back to the *current* branch, which reports whatever feature branch
+ *     happens to be checked out as though it were the repository default;
+ *   - falling back to the literal `'main'`, which is indistinguishable from a real
+ *     detection result.
+ *
+ * @param cwd Directory to inspect. Defaults to the current working directory.
+ *            Explicit so callers and tests can scope detection to a known repo.
  */
-function getDefaultBranch() {
+function getDefaultBranch(cwd) {
     try {
-        // Try to get the default branch from remote HEAD
         const remoteHead = (0, child_process_1.execSync)('git symbolic-ref refs/remotes/origin/HEAD', {
             timeout: 2000, // 2 second timeout
-            stdio: 'pipe'
+            stdio: 'pipe',
+            ...(cwd ? { cwd } : {})
         }).toString().trim();
         const match = remoteHead.match(/refs\/remotes\/origin\/(.+)$/);
         if (match) {
@@ -129,16 +146,9 @@ function getDefaultBranch() {
         }
     }
     catch (e) {
-        // If that fails, try to get it from the current branch
-        try {
-            return getCurrentGitBranch();
-        }
-        catch (e2) {
-            // Fall back to common defaults
-        }
+        // No remote HEAD to read: a bare local repo, no origin, or not a repo at all.
     }
-    // Default fallback
-    return 'main';
+    return null;
 }
 /**
  * Sanitizes a repository identifier by stripping local paths and normalizing to standard HTTPS URLs.

package/dist/src/core/utils/project-fraim-paths.js

@@ -144,9 +144,24 @@ function getUserFraimDisplayPath(relativePath = '') {
 /**
  * Get the user-level FRAIM directory (~/.fraim/).
  * Can be overridden with FRAIM_USER_DIR env var for testing.
+ *
+ * Issue #1159: inside a sandboxed test run the silent fallback to the real home
+ * is a data-loss bug, not a convenience. A test suite that reached `~/.fraim`
+ * booted `AiHubServer` instances against the developer's live conversation
+ * store and parked four in-flight runs as "Waiting on you". When the runner has
+ * marked the run sandboxed, an unset `FRAIM_USER_DIR` means isolation was
+ * broken, so fail here rather than corrupt real state.
  */
 function getUserFraimDirPath() {
-    return process.env.FRAIM_USER_DIR || (0, path_1.join)(os_1.default.homedir(), '.fraim');
+    const override = process.env.FRAIM_USER_DIR;
+    if (override)
+        return override;
+    if (process.env.FRAIM_TEST_SANDBOX === '1') {
+        throw new Error('FRAIM_USER_DIR is unset inside a sandboxed test run (FRAIM_TEST_SANDBOX=1). '
+            + 'Refusing to fall back to the real ~/.fraim. Restore FRAIM_USER_DIR to the run sandbox '
+            + 'before touching the machine-level FRAIM home.');
+    }
+    return (0, path_1.join)(os_1.default.homedir(), '.fraim');
 }
 function getUserFraimLearningsDir() {
     return (0, path_1.join)(getUserFraimDirPath(), 'personalized-employee', 'learnings');

package/dist/src/local-mcp-server/artifact-retention-cleanup.js

@@ -17,6 +17,14 @@ exports.ARTIFACT_RETENTION_CATEGORIES = [
     'evidence',
     'feedback',
     'cleanup_manifests',
+    // Issue #1103 R18: the usage record is personal-bearing behavioural metadata, so
+    // it needs a storage-limitation category like every other retained artifact.
+    // Unlike the others it is one JSON file rather than a directory of files, so the
+    // value bounds how long an individual offer or firing record keeps its detail
+    // (applied by learning-usage-store.pruneUsageStore) rather than when a file is
+    // deleted. Aggregate counters are never pruned; deleting them would misreport
+    // history rather than minimise it.
+    'learning_usage',
 ];
 function readWorkspaceConfig(workspaceRoot) {
     try {