fraim 2.0.340 → 2.0.342

package/dist/registry/scripts/learning/completion-state.js

@@ -57,9 +57,17 @@ function decodeCompletion(markdown, expected = {}) {
             fail();
         ids.add(item.actionId);
         const decision = item.decision;
-        if (!keys(decision, ['action', 'revision', 'digest', 'reviewer', 'reason', 'revisitCondition', 'at']) || !['approve', 'reject'].includes(decision.action) || decision.revision !== item.revision || decision.digest !== item.digest
+        // Issue #1857 R6 and D2: `basis`/`predecessorId` say who reached the decision,
+        // `kind` says whether a rejection refused the claim or was superseded by a
+        // rule. All three are optional so evidence written before this still decodes,
+        // and each is constrained here on the same terms `RunRecord.decide` uses.
+        if (!keys(decision, ['action', 'revision', 'digest', 'reviewer', 'reason', 'revisitCondition', 'basis', 'predecessorId', 'kind', 'at']) || !['approve', 'reject'].includes(decision.action) || decision.revision !== item.revision || decision.digest !== item.digest
             || !text(decision.reviewer) || !text(decision.reason) || !text(decision.at) || !Number.isFinite(Date.parse(decision.at))
-            || (decision.revisitCondition !== undefined && (decision.action !== 'reject' || !text(decision.revisitCondition))))
+            || (decision.revisitCondition !== undefined && (decision.action !== 'reject' || !text(decision.revisitCondition)))
+            || (decision.basis !== undefined && !['manager', 'inherited'].includes(decision.basis))
+            || (decision.basis === 'inherited' && !text(decision.predecessorId))
+            || (decision.predecessorId !== undefined && decision.basis !== 'inherited')
+            || (decision.kind !== undefined && (decision.action !== 'reject' || !['refused', 'superseded'].includes(decision.kind))))
             fail();
         if ('content' in item || 'specification' in item || 'application' in item || 'preimage' in item)
             fail();

package/dist/src/cli/setup/ide-invocation-surfaces.js

@@ -69,7 +69,7 @@ ${buildDeferredToolBootstrapSection(profile)}1. **Confirm FRAIM activation**:
    Use this process only 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.
 
 2. **If the user did not specify a FRAIM job or topic after activation**:
-   If local FRAIM job stubs are present in the workspace, inspect those first and match the request locally. Also inspect \`fraim/personalized-employee/jobs/\` for local overrides or repo-specific jobs. If local files are missing or you cannot inspect workspace files, call \`list_fraim_jobs()\` to view the full catalog, including any proxy-discoverable personalized jobs.
+   If local FRAIM job stubs are present in the workspace, read that jobs directory's \`INDEX.md\` first (it lists every job's name, one-line intent, and category) and match the request against it; open an individual stub only to confirm a shortlisted candidate, or fall back to scanning the stubs directly if no \`INDEX.md\` is present. Also check \`fraim/personalized-employee/jobs/\` (and its own \`INDEX.md\`, if present) for local overrides or repo-specific jobs. If local files are missing or you cannot inspect workspace files, call \`list_fraim_jobs()\` to view the full catalog, including any proxy-discoverable personalized jobs.
 
 3. **Find the match**:
    If the user names an exact FRAIM job, call \`get_fraim_job({ job: "<job-name>" })\` directly. Otherwise, match the user's request to a FRAIM job from the local stub catalog, \`fraim/personalized-employee/jobs/\`, or the full \`list_fraim_jobs()\` response. If no exact or high-confidence job match exists, call \`get_fraim_job({ job: "adhoc-prompt" })\` directly and execute it with the user's instructions as the task input — no confirmation question, and do not pick the nearest catalog job.

package/dist/src/cli/utils/agent-adapters.js

@@ -72,7 +72,7 @@ This repository uses FRAIM.
 - 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 names an exact FRAIM job, call \`get_fraim_job({ job: "<job-name>" })\` directly.
-- When FRAIM routing is active but the job is not exact, scan the job stubs under \`${employeeJobsPath}/\` and \`${managerJobsPath}/\` to identify the most appropriate job. Read stub filenames and their Intent/Outcome sections before using catalog tools.
+- When FRAIM routing is active but the job is not exact, read \`${employeeJobsPath}/INDEX.md\` and \`${managerJobsPath}/INDEX.md\` first (each lists every job's name, one-line intent, and category) to identify the most appropriate job; open an individual job stub only to confirm a shortlisted candidate. If an \`INDEX.md\` is missing or looks stale, fall back to scanning the job stubs under those directories directly. Also check \`${personalizedRootPath}/jobs/INDEX.md\` (or its stubs, if no index is present) for local overrides or repo-specific jobs.
 - Once you identify the relevant job, call \`get_fraim_job({ job: "<job-name>" })\` to get the full phased instructions.
 - 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.
 - For deeper capability detail, call \`get_fraim_file({ path: "skills/<category>/<skill-name>.md" })\` or \`get_fraim_file({ path: "rules/<category>/<rule-name>.md" })\`.
@@ -99,7 +99,7 @@ ${(0, ide_invocation_surfaces_1.buildFraimInvocationBody)('generic-tool-discover
 - 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 names an exact FRAIM job, fetch that full job directly with FRAIM MCP tools.
-- When FRAIM routing is active but the job is not exact, use local stubs to identify which job to invoke before fetching full content with FRAIM MCP tools.
+- When FRAIM routing is active but the job is not exact, read the local jobs directory's \`INDEX.md\` first to identify which job to invoke (falling back to the individual stub files if no index is present) before fetching full content with FRAIM MCP tools.
 - 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.
 - **Job stubs are for discovery only.** Never execute a job from stub content - always call \`get_fraim_job({ job: "<job-name>" })\` first.
 - ${ide_invocation_surfaces_1.FRAIM_MCP_UNAVAILABLE_MANAGER_GUIDANCE}
@@ -108,13 +108,13 @@ ${(0, ide_invocation_surfaces_1.buildFraimInvocationBody)('generic-tool-discover
 
 This directory is the repository-visible FRAIM surface.
 
-- \`ai-employee/jobs/\`: employee job stubs
-- \`ai-manager/jobs/\`: manager job stubs
-- \`ai-employee/skills/\`: skill stubs
+- \`ai-employee/jobs/\`: employee job stubs (+ \`INDEX.md\`)
+- \`ai-manager/jobs/\`: manager job stubs (+ \`INDEX.md\`)
+- \`ai-employee/skills/\`: skill stubs (+ \`INDEX.md\`)
 - \`ai-employee/rules/\`: rule stubs
 - \`personalized-employee/\`: repo-specific overrides and learnings
 
-When FRAIM routing is active and no exact FRAIM job is named, use the stubs here to discover which FRAIM job, skill, or rule is relevant, then load the full content through FRAIM MCP tools. If an exact FRAIM job is named, load it directly. For ordinary requests, do not scan this catalog first.
+When FRAIM routing is active and no exact FRAIM job is named, read the \`INDEX.md\` in the relevant directory first to discover which FRAIM job, skill, or rule is relevant (falling back to scanning the individual stubs if no index is present), then load the full content through FRAIM MCP tools. If an exact FRAIM job is named, load it directly. For ordinary requests, do not scan this catalog first.
 `;
     const vscodePrompt = `# FRAIM
 

package/dist/src/cli/utils/remote-sync.js

@@ -23,6 +23,7 @@ const path_1 = require("path");
 const chalk_1 = __importDefault(require("chalk"));
 const script_sync_utils_1 = require("./script-sync-utils");
 const fraim_gitignore_1 = require("./fraim-gitignore");
+const capability_index_1 = require("../../core/utils/capability-index");
 const project_fraim_paths_1 = require("../../core/utils/project-fraim-paths");
 const LOCK_SYNCED_CONTENT_ENV = 'FRAIM_LOCK_SYNCED_CONTENT';
 exports.SYNCED_CONTENT_BANNER_MARKER = '<!-- FRAIM_SYNC_MANAGED_CONTENT -->';
@@ -268,6 +269,7 @@ async function syncRoleJobsToUserDir(roleFiles, role) {
         }
         (0, fs_1.writeFileSync)(filePath, applySyncedContentBanner(file), 'utf8');
     }
+    (0, capability_index_1.writeCapabilityIndex)(targetDir, 'job');
     return roleFiles.length;
 }
 /**
@@ -353,6 +355,7 @@ async function syncFromRemote(options) {
             (0, fs_1.writeFileSync)(filePath, applySyncedContentBanner(file), 'utf8');
             console.log(chalk_1.default.gray(`  + ${(0, project_fraim_paths_1.getWorkspaceFraimDisplayPath)(`ai-employee/jobs/${relativePath}`)}`));
         }
+        (0, capability_index_1.writeCapabilityIndex)(employeeJobsDir, 'job');
         // Sync ai-manager job stubs to fraim/ai-manager/jobs/
         const managerJobsDir = (0, project_fraim_paths_1.getWorkspaceFraimPath)(options.projectRoot, 'ai-manager', 'jobs');
         cleanWorkspaceDirectory(options.projectRoot, managerJobsDir, 'manager job directory', assertWorkspacePath, 'ai-manager', 'jobs');
@@ -370,6 +373,7 @@ async function syncFromRemote(options) {
             (0, fs_1.writeFileSync)(filePath, applySyncedContentBanner(file), 'utf8');
             console.log(chalk_1.default.gray(`  + ${(0, project_fraim_paths_1.getWorkspaceFraimDisplayPath)(`ai-manager/jobs/${relativePath}`)}`));
         }
+        (0, capability_index_1.writeCapabilityIndex)(managerJobsDir, 'job');
         // Sync skill STUBS to fraim/ai-employee/skills/
         const skillFiles = files.filter(f => f.type === 'skill');
         const skillsDir = (0, project_fraim_paths_1.getWorkspaceFraimPath)(options.projectRoot, 'ai-employee', 'skills');
@@ -387,6 +391,7 @@ async function syncFromRemote(options) {
             (0, fs_1.writeFileSync)(filePath, applySyncedContentBanner(file), 'utf8');
             console.log(chalk_1.default.gray(`  + ${(0, project_fraim_paths_1.getWorkspaceFraimDisplayPath)(`ai-employee/skills/${relativePath}`)} (stub)`));
         }
+        (0, capability_index_1.writeCapabilityIndex)(skillsDir, 'skill');
         // Sync rule STUBS to fraim/ai-employee/rules/
         const ruleFiles = files.filter(f => f.type === 'rule');
         const rulesDir = (0, project_fraim_paths_1.getWorkspaceFraimPath)(options.projectRoot, 'ai-employee', 'rules');

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

@@ -17,13 +17,15 @@
  * after the existing quality enforcement block.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PHASE_START_WARN_PHASES = void 0;
 exports.isSubmitPhase = isSubmitPhase;
 exports.isRetrospectivePhase = isRetrospectivePhase;
 exports.isAddressFeedbackCompletion = isAddressFeedbackCompletion;
 exports.isDelegationGraphPhase = isDelegationGraphPhase;
 exports.validateAddressFeedbackApproval = validateAddressFeedbackApproval;
 exports.validateReviewActionCompleteness = validateReviewActionCompleteness;
+exports.recordPhaseStart = recordPhaseStart;
+exports.inspectPhaseCompletion = inspectPhaseCompletion;
+exports.commitPhaseCompletion = commitPhaseCompletion;
 exports.hasPhaseStarted = hasPhaseStarted;
 exports.upsertPhaseStarted = upsertPhaseStarted;
 exports.buildPhaseStartWarning = buildPhaseStartWarning;
@@ -176,11 +178,105 @@ function validateReviewActionCompleteness(reviewTarget, reviewActions, repo) {
     }
     return errors.length > 0 ? errors : null;
 }
+function isPhaseStartInstance(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const instance = value;
+    return typeof instance.instanceId === 'string'
+        && typeof instance.sessionId === 'string'
+        && typeof instance.jobName === 'string'
+        && typeof instance.phaseId === 'string'
+        && typeof instance.startedAt === 'string';
+}
+function phaseContextMatches(instance, context) {
+    if (instance.sessionId !== context.sessionId
+        || instance.jobName !== context.jobName
+        || instance.phaseId !== context.phaseId
+        || instance.resumeId !== context.resumeId) {
+        return false;
+    }
+    // A start without jobId is intentionally matchable to a later identified
+    // completion. When both calls identify a job, the identifiers must agree.
+    return !instance.jobId || instance.jobId === context.jobId;
+}
+function phaseInstancesFrom(marker) {
+    if (!marker || typeof marker !== 'object' || Array.isArray(marker))
+        return [];
+    const values = marker.phaseInstances;
+    return Array.isArray(values) ? values.filter(isPhaseStartInstance).map((value) => ({ ...value })) : [];
+}
+function nextPhaseInstanceId(instances, context) {
+    let ordinal = instances.length + 1;
+    const prefix = [context.sessionId, context.jobName, context.phaseId];
+    while (instances.some((instance) => instance.instanceId === JSON.stringify([...prefix, ordinal])))
+        ordinal++;
+    return JSON.stringify([...prefix, ordinal]);
+}
+/** Start a phase instance, refreshing an active start when instructions are requested again. */
+function recordPhaseStart(marker, context) {
+    const instances = phaseInstancesFrom(marker);
+    // A repeated start refreshes the current instance; it must not leave an
+    // older unconsumed start available for a later re-entry.
+    const active = instances.find((instance) => !instance.completedAt
+        && phaseContextMatches(instance, context));
+    if (active) {
+        active.startedAt = context.timestamp;
+        if (context.jobId)
+            active.jobId = context.jobId;
+        return { phaseInstances: instances };
+    }
+    const instanceId = nextPhaseInstanceId(instances, context);
+    instances.push({
+        sessionId: context.sessionId,
+        jobName: context.jobName,
+        phaseId: context.phaseId,
+        ...(context.jobId ? { jobId: context.jobId } : {}),
+        ...(context.resumeId ? { resumeId: context.resumeId } : {}),
+        instanceId,
+        startedAt: context.timestamp,
+    });
+    return { phaseInstances: instances };
+}
 /**
- * True when `marker` records a "starting" timestamp for `phaseId`. Fails
- * open (false, never throws) for a missing file (marker: undefined), a
- * missing key, or a malformed shape — this is a warn-only signal, not a
- * required artifact.
+ * Inspect a completion without mutating state. The caller must commit only
+ * after every other completion contract accepts the call, so rejected calls
+ * do not consume the valid starting instance.
+ */
+function inspectPhaseCompletion(marker, context) {
+    const instances = phaseInstancesFrom(marker);
+    const candidates = instances.filter((instance) => !instance.completedAt && phaseContextMatches(instance, context));
+    if (candidates.length === 1)
+        return { missingStart: false, instanceId: candidates[0].instanceId };
+    return { missingStart: true };
+}
+/** Commit an accepted completion, consuming its matched start or recording a flagged synthetic instance. */
+function commitPhaseCompletion(marker, inspection, context) {
+    const instances = phaseInstancesFrom(marker);
+    if (inspection.instanceId) {
+        const matched = instances.find((instance) => instance.instanceId === inspection.instanceId);
+        if (matched) {
+            matched.completedAt = context.timestamp;
+            if (context.jobId)
+                matched.jobId = context.jobId;
+            return { phaseInstances: instances };
+        }
+    }
+    instances.push({
+        sessionId: context.sessionId,
+        jobName: context.jobName,
+        phaseId: context.phaseId,
+        ...(context.jobId ? { jobId: context.jobId } : {}),
+        ...(context.resumeId ? { resumeId: context.resumeId } : {}),
+        instanceId: nextPhaseInstanceId(instances, context),
+        startedAt: context.timestamp,
+        completedAt: context.timestamp,
+        missingStart: true,
+    });
+    return { phaseInstances: instances };
+}
+/**
+ * Legacy marker helpers retained for consumers that still inspect the old
+ * address-feedback shape. New tracking uses the instance-aware helpers above.
  */
 function hasPhaseStarted(marker, phaseId) {
     if (!marker || typeof marker !== 'object' || Array.isArray(marker))
@@ -191,11 +287,6 @@ function hasPhaseStarted(marker, phaseId) {
     const value = startedPhases[phaseId];
     return typeof value === 'string' && value.length > 0;
 }
-/**
- * Returns a new marker with `phaseId` upserted to `timestamp`, preserving
- * every other phase already recorded. Tolerates a missing or malformed
- * existing marker by starting from an empty `startedPhases`.
- */
 function upsertPhaseStarted(marker, phaseId, timestamp) {
     const existing = marker && typeof marker === 'object' && !Array.isArray(marker)
         ? marker.startedPhases
@@ -206,18 +297,11 @@ function upsertPhaseStarted(marker, phaseId, timestamp) {
     startedPhases[phaseId] = timestamp;
     return { startedPhases };
 }
-/** The single phase this gate covers today (RFC: scoped, not universal — see Risk Assessment). */
-exports.PHASE_START_WARN_PHASES = ['address-feedback'];
-/**
- * Builds the warning prepended to an otherwise-valid address-feedback
- * response when this run never called seekMentoring(status: "starting") for
- * that phase. Warn-only, never a rejection: a lost marker (disk cleanup, a
- * first-ever run before this shipped) must not strand a legitimate resume.
- */
+/** Builds the warn-only notice for any phase completed without an on-arrival start. */
 function buildPhaseStartWarning(phaseId) {
-    return (`⚠️ **Phase-start notice**: this run did not call \`seekMentoring({ currentPhase: "${phaseId}", status: "starting" })\` ` +
-        `before this call. If you resumed after context compaction, re-read \`registry/delivery/address-feedback.md\` now — ` +
-        `Step 4 (write the standalone feedback file) is easy to skip when acting from remembered context.\n\n`);
+    return (`⚠️ **Phase-start notice**: phase \`${phaseId}\` completed without an on-arrival ` +
+        `\`seekMentoring({ currentPhase: "${phaseId}", status: "starting" })\` call in this session. ` +
+        `The missing call was flagged, but this completion remains accepted.\n\n`);
 }
 function isAbsoluteHttpUrl(url) {
     if (typeof url !== 'string' || !url)
@@ -586,6 +670,23 @@ evidence: {
 }
 \`\`\``;
 const FIELD_SCHEMAS = {
+    proposalSet: [
+        '{',
+        '  "runScope": "manager" | "project" | "org",',
+        '  "proposals": [{',
+        '    "proposalId": "<id the journal records against>",',
+        '    "claimKey": "<claim identity>", "family": "<learning family>", "revision": <int>,',
+        '    "changeType": "new" | "update" | "cold",',
+        '    "title": "<reader title>", "takeaway": "<reader takeaway>", "example": "<optional>",',
+        '    "suggestedLevel": "manager" | "project" | "org", "recurrences": <int>,',
+        '    "recurrencesAtLastReview": <int|null>, "domain": "<domain|null>",',
+        '    "reopening": { "rejectedAt": "<date>", "reason": "<manager words>", "countAtRejection": <int> }',
+        '  }],',
+        '  "suppressed": [{ "claimKey": "...", "family": "...", "rejectedAt": "<date>",',
+        '                   "kind": "refused" | "superseded", "reason": "...", "newSourceCount": <int> }]',
+        '}',
+        'Trace, sourceRefs and scores are audit metadata and must not be sent.',
+    ].join(String.fromCharCode(10)),
     approved: ADDRESS_FEEDBACK_APPROVAL_SCHEMA,
     reviewHandoff: REVIEW_HANDOFF_SCHEMA,
     nextJobRecommendations: NEXT_JOB_RECOMMENDATIONS_SCHEMA,

package/dist/src/core/proposal-set-contract.js

@@ -0,0 +1,214 @@
+"use strict";
+/**
+ * Proposal Set Contract Validation (Issue #1857)
+ *
+ * The Hub renders the manager's learning review batch from this payload. Before
+ * this contract it rendered from prose: `tfParsePendingProposals` scanned an
+ * employee turn for a `## Pending Review` heading and `#### [P-LEVEL]` lines that
+ * no job or skill was ever instructed to emit, so the review surface #1876
+ * shipped rendered nothing for a real run.
+ *
+ * Two findings from the design spikes shape what this file checks.
+ *
+ * First, failing loudly is the behavior under test. A wire-shaped proposal whose
+ * field names did not match what the card reads rendered a card with its body
+ * silently missing and threw nothing. A contract that rejects the payload and
+ * names the field is recoverable; one that renders a degraded card is not.
+ *
+ * Second, the size caps are measured rather than chosen. Across 4,779 recorded
+ * `seekMentoring` calls in the raw host archives, the largest evidence object this
+ * system has ever carried is 6,044 bytes (median 506, p95 1,859). A proposal costs
+ * roughly 700 bytes once its 80-word reader budget and identity fields are counted,
+ * so a proposal set is the largest payload this channel will carry and the bound
+ * has to be explicit rather than discovered in production.
+ *
+ * Lives in src/core so the local MCP proxy, the Hub and the evals import the same
+ * validator, per architecture 4.2.1 — the same pattern as `handoff-contracts.ts`,
+ * `quality-evidence.ts` and `test-evidence-contract.ts`.
+ *
+ * Primary call site: src/local-mcp-server/stdio-server.ts seekMentoring handler.
+ * The Hub keeps its own normalizer as well; the two do different jobs. This one
+ * tells the agent what to fix in one round. The normalizer protects the render
+ * from a payload that reached the Hub by some other path.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_SUPPRESSED_PER_SET = exports.MAX_PROPOSALS_PER_SET = exports.PROPOSAL_CHANGE_TYPES = exports.SUPPRESSION_KINDS = exports.PROPOSAL_RUN_SCOPES = void 0;
+exports.rankProposals = rankProposals;
+exports.validateProposalSet = validateProposalSet;
+/** Scopes a run can be asked for. Decides which corpus an approval lands in. */
+exports.PROPOSAL_RUN_SCOPES = ['manager', 'project', 'org'];
+/** How a claim came to be suppressed, so R7's report does not describe a
+ *  claim the manager promoted to a rule as one they refused. */
+exports.SUPPRESSION_KINDS = ['refused', 'superseded'];
+/** What kind of change a proposal makes to the corpus. */
+exports.PROPOSAL_CHANGE_TYPES = ['new', 'update', 'cold'];
+/**
+ * Maximum proposals in one set. Derived from the measured envelope above, not
+ * chosen: at roughly 700 bytes per proposal this keeps a full set inside twice
+ * the largest evidence payload the channel has ever carried. Raising it should
+ * follow a re-measurement, which `test-1857-proposal-set-contract.ts` pins.
+ */
+exports.MAX_PROPOSALS_PER_SET = 12;
+/** Maximum suppressed entries reported in one batch. Each is a single line. */
+exports.MAX_SUPPRESSED_PER_SET = 25;
+/** Reader-field length bound. The authoring skill already budgets 80 words across
+ *  title and the four reader values; this is the byte-level backstop. */
+const MAX_READER_FIELD = 600;
+const isObject = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+const isText = (v) => typeof v === 'string' && v.trim().length > 0;
+/**
+ * Fields that are audit metadata rather than review material. R10 is an invariant
+ * about influence, not storage: the manager's card is not a place for a score, a
+ * source path or an originating job to arrive by accident. Rejecting them at the
+ * boundary is cheaper than auditing every render site later.
+ */
+const FORBIDDEN_PROPOSAL_FIELDS = ['trace', 'sourceRefs', 'sourceHashes', 'content', 'score'];
+function validateEntry(entry, index, errors) {
+    const at = `evidence.proposalSet.proposals[${index}]`;
+    if (!isObject(entry)) {
+        errors.push(`${at} must be an object`);
+        return;
+    }
+    for (const field of ['proposalId', 'claimKey', 'family']) {
+        if (!isText(entry[field]))
+            errors.push(`${at}.${field} must be a non-empty string`);
+    }
+    if (!Number.isInteger(entry.revision) || entry.revision < 1) {
+        errors.push(`${at}.revision must be a positive integer`);
+    }
+    for (const field of ['title', 'takeaway']) {
+        if (!isText(entry[field])) {
+            errors.push(`${at}.${field} must be a non-empty string; the card renders it`);
+        }
+        else if (entry[field].length > MAX_READER_FIELD) {
+            errors.push(`${at}.${field} exceeds ${MAX_READER_FIELD} characters`);
+        }
+    }
+    if (entry.example !== undefined && typeof entry.example !== 'string') {
+        errors.push(`${at}.example must be a string when present`);
+    }
+    if (entry.suggestionReason !== undefined) {
+        if (typeof entry.suggestionReason !== 'string') {
+            errors.push(`${at}.suggestionReason must be a string when present`);
+        }
+        else if (entry.suggestionReason.length > MAX_READER_FIELD) {
+            errors.push(`${at}.suggestionReason exceeds ${MAX_READER_FIELD} characters`);
+        }
+    }
+    if (!exports.PROPOSAL_RUN_SCOPES.includes(entry.suggestedLevel)) {
+        errors.push(`${at}.suggestedLevel must be one of ${exports.PROPOSAL_RUN_SCOPES.join(', ')}`);
+    }
+    if (!exports.PROPOSAL_CHANGE_TYPES.includes(entry.changeType)) {
+        errors.push(`${at}.changeType must be one of ${exports.PROPOSAL_CHANGE_TYPES.join(', ')}`);
+    }
+    if (!Number.isInteger(entry.recurrences) || entry.recurrences < 0) {
+        errors.push(`${at}.recurrences must be a non-negative integer`);
+    }
+    for (const field of FORBIDDEN_PROPOSAL_FIELDS) {
+        if (entry[field] !== undefined) {
+            errors.push(`${at}.${field} is audit metadata and must not be sent to the review surface`);
+        }
+    }
+    if (entry.reopening !== undefined) {
+        const r = entry.reopening;
+        const ra = `${at}.reopening`;
+        if (!isObject(r)) {
+            errors.push(`${ra} must be an object`);
+        }
+        else {
+            if (!isText(r.rejectedAt))
+                errors.push(`${ra}.rejectedAt must be a non-empty string`);
+            if (!isText(r.reason)) {
+                errors.push(`${ra}.reason must be a non-empty string; a reopening quotes the original decision`);
+            }
+            if (!Number.isInteger(r.countAtRejection) || r.countAtRejection < 0) {
+                errors.push(`${ra}.countAtRejection must be a non-negative integer`);
+            }
+        }
+    }
+}
+function validateSuppressed(entry, index, errors) {
+    const at = `evidence.proposalSet.suppressed[${index}]`;
+    if (!isObject(entry)) {
+        errors.push(`${at} must be an object`);
+        return;
+    }
+    for (const field of ['claimKey', 'family', 'rejectedAt', 'reason']) {
+        if (!isText(entry[field]))
+            errors.push(`${at}.${field} must be a non-empty string`);
+    }
+    if (!exports.SUPPRESSION_KINDS.includes(entry.kind)) {
+        errors.push(`${at}.kind must be one of ${exports.SUPPRESSION_KINDS.join(', ')}`);
+    }
+    if (!Number.isInteger(entry.newSourceCount) || entry.newSourceCount < 0) {
+        errors.push(`${at}.newSourceCount must be a non-negative integer`);
+    }
+}
+/**
+ * Validates `evidence.proposalSet`. Returns null when valid or absent, or an array
+ * of messages each naming the exact field, so the agent fixes it in one round
+ * rather than guessing.
+ *
+ * Absent is valid: a review phase with nothing to review emits no set. An empty
+ * `proposals` array is also valid and means the same thing, which keeps a run that
+ * suppressed everything able to report its suppressions.
+ */
+/**
+ * Order a batch by accumulated evidence strength (Issue #1857 R3).
+ *
+ * An undecided proposal is not a chore that expires; it comes back, and it comes
+ * back stronger or it does not. A flat list makes every row look equally
+ * deserving of the manager's attention, which is how a claim with eleven
+ * occurrences ends up below one with two because it happened to be authored
+ * later. Ordering is the whole reason "leave it for now" is a position rather
+ * than a deferral: the next batch shows the manager what changed.
+ *
+ * Recurrences is the primary key because it is the accumulated evidence itself.
+ * Growth since the last review breaks ties, so between two claims at the same
+ * count the one that is still happening leads. `proposalId` breaks the remainder,
+ * so the same batch always renders in the same order and a manager re-opening a
+ * run does not find the rows rearranged.
+ *
+ * Applied on the Hub's own read rather than trusted from the agent: the order the
+ * manager sees should not depend on how a model happened to sort its output.
+ */
+function rankProposals(proposals) {
+    const growth = (p) => typeof p.recurrencesAtLastReview === 'number' ? p.recurrences - p.recurrencesAtLastReview : 0;
+    return [...proposals].sort((a, b) => b.recurrences - a.recurrences
+        || growth(b) - growth(a)
+        || a.proposalId.localeCompare(b.proposalId));
+}
+function validateProposalSet(raw) {
+    if (raw === undefined || raw === null)
+        return null;
+    const errors = [];
+    if (!isObject(raw)) {
+        return ['evidence.proposalSet must be an object'];
+    }
+    if (!exports.PROPOSAL_RUN_SCOPES.includes(raw.runScope)) {
+        errors.push(`evidence.proposalSet.runScope must be one of ${exports.PROPOSAL_RUN_SCOPES.join(', ')}`);
+    }
+    if (!Array.isArray(raw.proposals)) {
+        errors.push('evidence.proposalSet.proposals must be an array');
+    }
+    else if (raw.proposals.length > exports.MAX_PROPOSALS_PER_SET) {
+        errors.push(`evidence.proposalSet.proposals holds ${raw.proposals.length} entries, past the ` +
+            `${exports.MAX_PROPOSALS_PER_SET} a single batch may carry; present the strongest first and ` +
+            'report the remainder so the manager knows the batch was split');
+    }
+    else {
+        raw.proposals.forEach((entry, index) => validateEntry(entry, index, errors));
+    }
+    if (raw.suppressed !== undefined) {
+        if (!Array.isArray(raw.suppressed)) {
+            errors.push('evidence.proposalSet.suppressed must be an array when present');
+        }
+        else if (raw.suppressed.length > exports.MAX_SUPPRESSED_PER_SET) {
+            errors.push(`evidence.proposalSet.suppressed exceeds ${exports.MAX_SUPPRESSED_PER_SET} entries`);
+        }
+        else {
+            raw.suppressed.forEach((entry, index) => validateSuppressed(entry, index, errors));
+        }
+    }
+    return errors.length > 0 ? errors : null;
+}

package/dist/src/core/run-recovery-state.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.safeRunStateKey = safeRunStateKey;
+const crypto_1 = require("crypto");
+/** UUIDs retain their documented filenames; other IDs cannot become paths or device names. */
+function safeRunStateKey(id) {
+    return /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(id)
+        ? id : `id-${(0, crypto_1.createHash)('sha256').update(id).digest('hex')}`;
+}

package/dist/src/core/utils/capability-index.js

@@ -0,0 +1,104 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CAPABILITY_INDEX_FILENAME = void 0;
+exports.buildCapabilityIndexContent = buildCapabilityIndexContent;
+exports.writeCapabilityIndex = writeCapabilityIndex;
+exports.refreshPersonalizedJobsIndex = refreshPersonalizedJobsIndex;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const stub_generator_1 = require("./stub-generator");
+exports.CAPABILITY_INDEX_FILENAME = 'INDEX.md';
+const CAPABILITY_INDEX_MARKER = '<!-- FRAIM_DISCOVERY_INDEX -->';
+const MAX_SUMMARY_LENGTH = 140;
+function oneLine(text, maxLength = MAX_SUMMARY_LENGTH) {
+    const collapsed = text.replace(/\s+/g, ' ').trim();
+    if (collapsed.length <= maxLength)
+        return collapsed;
+    return `${collapsed.slice(0, maxLength - 1).trimEnd()}…`;
+}
+function fetchHintFor(kind, entry) {
+    return kind === 'job'
+        ? `get_fraim_job({ job: "${entry.name}" })`
+        : `get_fraim_file({ path: "skills/${entry.category}/${entry.name}.md" })`;
+}
+/**
+ * Builds the compact index markdown for one stub layer (all job stubs, or all
+ * skill stubs, under a single jobs/ or skills/ root). Pure function so the
+ * content can be unit-tested without touching the filesystem.
+ */
+function buildCapabilityIndexContent(kind, entries) {
+    const noun = kind === 'job' ? 'Job' : 'Skill';
+    const sorted = [...entries].sort((a, b) => a.category.localeCompare(b.category) || a.name.localeCompare(b.name));
+    const categorized = new Map();
+    for (const entry of sorted) {
+        const list = categorized.get(entry.category) ?? [];
+        list.push(entry);
+        categorized.set(entry.category, list);
+    }
+    const lines = [
+        CAPABILITY_INDEX_MARKER,
+        `# FRAIM ${noun} Index`,
+        '',
+        `Compact discovery index for this layer's ${kind} stubs — read this file first instead of opening every individual stub.`,
+    ];
+    for (const [category, categoryEntries] of categorized) {
+        lines.push('', `## ${category}`);
+        for (const entry of categoryEntries) {
+            lines.push(`- **${entry.name}**: ${entry.summary} (${fetchHintFor(kind, entry)})`);
+        }
+    }
+    lines.push('', '---', '', '> [!IMPORTANT]', `> This index is for discovery only. Once you have a candidate ${kind}, fetch its full content before acting on it — never execute from the one-line summary above.`);
+    return `${lines.join('\n')}\n`;
+}
+function readCategoryEntries(kind, rootDir) {
+    const entries = [];
+    const categoryDirents = fs_1.default.existsSync(rootDir)
+        ? fs_1.default.readdirSync(rootDir, { withFileTypes: true }).filter((d) => d.isDirectory())
+        : [];
+    for (const categoryDirent of categoryDirents) {
+        const categoryDir = path_1.default.join(rootDir, categoryDirent.name);
+        const fileNames = fs_1.default
+            .readdirSync(categoryDir, { withFileTypes: true })
+            .filter((d) => d.isFile() && d.name.endsWith('.md'))
+            .map((d) => d.name);
+        for (const fileName of fileNames) {
+            const filePath = path_1.default.join(categoryDir, fileName);
+            const content = fs_1.default.readFileSync(filePath, 'utf8');
+            const name = fileName.replace(/\.md$/, '');
+            const summary = kind === 'job'
+                ? oneLine((0, stub_generator_1.parseRegistryJob)(content).intent)
+                : oneLine((0, stub_generator_1.parseRegistrySkill)(content).skillInput);
+            entries.push({ category: categoryDirent.name, name, summary });
+        }
+    }
+    return entries;
+}
+/**
+ * Scans a jobs/ or skills/ root (one file per {category}/{name}.md, mirroring
+ * the layout every stub layer already uses) and (re)writes a compact INDEX.md
+ * at that root. Safe to call on a root with no category subfolders yet (writes
+ * nothing, since there is nothing to index).
+ */
+function writeCapabilityIndex(rootDir, kind) {
+    if (!fs_1.default.existsSync(rootDir))
+        return;
+    const entries = readCategoryEntries(kind, rootDir);
+    if (entries.length === 0)
+        return;
+    const indexPath = path_1.default.join(rootDir, exports.CAPABILITY_INDEX_FILENAME);
+    fs_1.default.writeFileSync(indexPath, buildCapabilityIndexContent(kind, entries), 'utf8');
+}
+/**
+ * Refreshes the job-stub index for the one layer `fraim sync` never writes:
+ * `fraim/personalized-employee/jobs/` and `.../manager-jobs/`. That layer is
+ * populated by agent writes (e.g. the evolve-employee job), not by sync, so
+ * there is no deterministic write path to hook — callers invoke this directly
+ * after writing or changing a personalized job overlay file.
+ */
+function refreshPersonalizedJobsIndex(projectRoot) {
+    writeCapabilityIndex(path_1.default.join(projectRoot, 'fraim', 'personalized-employee', 'jobs'), 'job');
+    writeCapabilityIndex(path_1.default.join(projectRoot, 'fraim', 'personalized-employee', 'manager-jobs'), 'job');
+}