fraim 2.0.339 → 2.0.341

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

@@ -0,0 +1,161 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.COMPLETION_END = exports.COMPLETION_START = void 0;
+exports.validateProcessedSources = validateProcessedSources;
+exports.decodeCompletion = decodeCompletion;
+const node_path_1 = __importDefault(require("node:path"));
+function validateProcessedSources(sources) {
+    if (!Array.isArray(sources) || new Set(sources.map(item => item.path)).size !== sources.length || sources.some(item => !item || !node_path_1.default.isAbsolute(item.path) || !node_path_1.default.isAbsolute(item.destination) || !['raw', 'retrospective'].includes(item.kind)
+        || !/^[a-f0-9]{64}$/.test(item.sha256) || !/^[a-f0-9]{64}$/.test(item.resultHash) || !/^\d{4}-\d{2}-\d{2}$/.test(item.synthesizedAt)))
+        throw new Error('invalid-processed-sources');
+}
+exports.COMPLETION_START = '<!-- fraim-sleep-decisions:v1 -->';
+exports.COMPLETION_END = '<!-- /fraim-sleep-decisions -->';
+const text = (value) => typeof value === 'string' && !!value.trim();
+const hash = (value) => typeof value === 'string' && /^[a-f0-9]{64}$/.test(value);
+const object = (value) => !!value && typeof value === 'object' && !Array.isArray(value);
+const keys = (value, allowed) => object(value) && Object.keys(value).every(key => allowed.includes(key));
+const ownerValid = (value) => object(value) && ['Project', 'Manager', 'Org'].includes(value.level)
+    && keys(value, ['level', 'path']) && text(value.path) && node_path_1.default.isAbsolute(value.path)
+    && !/[\x00-\x1f]/.test(value.path) && value.path === (process.platform === 'win32' ? node_path_1.default.resolve(value.path).replace(/\\/g, '/').toLowerCase() : node_path_1.default.resolve(value.path));
+const sameOwner = (a, b) => a.level === b.level && a.path === b.path;
+function decodeCompletion(markdown, expected = {}) {
+    const fail = () => { throw new Error('invalid-completion-decisions'); };
+    if ((markdown.match(/<!--\s*fraim-sleep-decisions:/g) || []).length !== 1 || markdown.split(exports.COMPLETION_START).length !== 2 || markdown.split(exports.COMPLETION_END).length !== 2)
+        fail();
+    const start = markdown.indexOf(exports.COMPLETION_START) + exports.COMPLETION_START.length;
+    const end = markdown.indexOf(exports.COMPLETION_END);
+    if (end < start)
+        fail();
+    const block = markdown.slice(start, end).match(/^\s*```json\r?\n([\s\S]*?)\r?\n```\s*$/);
+    if (!block)
+        fail();
+    let state;
+    try {
+        state = JSON.parse(block[1]);
+    }
+    catch {
+        fail();
+    }
+    if (!keys(state, ['schemaVersion', 'runId', 'owner', 'finalizationState', 'decisions', 'sourceDispositions', 'cleanup', 'reconciliations', 'retrospective', 'processedSources']) || state.schemaVersion !== 1 || !text(state.runId) || !/^[a-zA-Z0-9][a-zA-Z0-9._-]*$/.test(state.runId) || !ownerValid(state.owner)
+        || !['pending', 'complete'].includes(state.finalizationState) || !Array.isArray(state.decisions) || !Array.isArray(state.sourceDispositions) || !Array.isArray(state.cleanup))
+        fail();
+    if ((expected.runId && expected.runId !== state.runId) || (expected.owner && !sameOwner(expected.owner, state.owner)))
+        fail();
+    if (state.retrospective !== undefined && (!keys(state.retrospective, ['relativePath', 'sha256'])
+        || state.retrospective.relativePath !== `retrospectives/${state.runId}-sleep-postmortem.md` || !hash(state.retrospective.sha256)))
+        fail();
+    if (state.processedSources !== undefined)
+        validateProcessedSources(state.processedSources);
+    const ids = new Set();
+    for (const item of state.decisions) {
+        if (!keys(item, ['actionId', 'revision', 'digest', 'owner', 'claimKey', 'evidenceFingerprint', 'sourceRefs', 'decision', 'publicationRef', 'target', 'dependencies']) || !text(item.actionId) || ids.has(item.actionId) || !Number.isInteger(item.revision) || item.revision < 1 || !hash(item.digest) || !ownerValid(item.owner)
+            || !text(item.claimKey) || !text(item.evidenceFingerprint) || !Array.isArray(item.sourceRefs) || !item.sourceRefs.every(text) || (item.publicationRef !== undefined && !text(item.publicationRef)))
+            fail();
+        ids.add(item.actionId);
+        const decision = item.decision;
+        // 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.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();
+        if (item.target && (!keys(item.target, ['owner', 'relativePath', 'entryId', 'learningSubject']) || !ownerValid(item.target.owner) || !text(item.target.relativePath) || /^[\\/]|^[a-zA-Z]:/.test(item.target.relativePath) || item.target.relativePath.split('/').includes('..')))
+            fail();
+        if (item.dependencies && (!Array.isArray(item.dependencies) || item.dependencies.some((dependency) => !keys(dependency, ['actionId', 'outcome']) || !text(dependency.actionId) || !['applied', 'rejected'].includes(dependency.outcome))))
+            fail();
+    }
+    for (const source of state.sourceDispositions) {
+        if (!keys(source, ['sourceRef', 'sourceHash', 'outcome', 'actionId']) || !text(source.sourceRef) || !hash(source.sourceHash) || !['applied', 'rejected'].includes(source.outcome) || !ids.has(source.actionId))
+            fail();
+    }
+    const decisions = new Map(state.decisions.map((item) => [item.actionId, item]));
+    const outcome = (item) => item.decision.action === 'approve' ? 'applied' : 'rejected';
+    const dispositions = new Set();
+    for (const source of state.sourceDispositions) {
+        const action = decisions.get(source.actionId);
+        const key = JSON.stringify([source.actionId, source.sourceRef]);
+        if (dispositions.has(key) || !action.sourceRefs.includes(source.sourceRef) || source.outcome !== outcome(action))
+            fail();
+        dispositions.add(key);
+    }
+    for (const action of decisions.values()) {
+        if (action.target && !sameOwner(action.owner, action.target.owner))
+            fail();
+        if (new Set(action.sourceRefs).size !== action.sourceRefs.length || action.sourceRefs.some(ref => !dispositions.has(JSON.stringify([action.actionId, ref]))))
+            fail();
+        const dependencies = action.dependencies || [];
+        if (new Set(dependencies.map(dependency => dependency.actionId)).size !== dependencies.length)
+            fail();
+        for (const dependency of dependencies) {
+            const target = decisions.get(dependency.actionId);
+            if (!target || target.actionId === action.actionId || dependency.outcome !== outcome(target)
+                || (action.decision.action === 'approve' && dependency.outcome !== 'applied'))
+                fail();
+        }
+    }
+    const checked = new Set();
+    const visiting = new Set();
+    const visit = (id) => {
+        if (visiting.has(id))
+            fail();
+        if (checked.has(id))
+            return;
+        visiting.add(id);
+        for (const dependency of decisions.get(id).dependencies || [])
+            visit(dependency.actionId);
+        visiting.delete(id);
+        checked.add(id);
+    };
+    for (const id of decisions.keys())
+        visit(id);
+    for (const item of state.cleanup) {
+        if (!keys(item, ['path', 'outcome', 'reason', 'sha256', 'location']) || !text(item.path) || !['pending', 'deleted', 'absent', 'retained'].includes(item.outcome) || (item.reason !== undefined && typeof item.reason !== 'string') || (item.sha256 !== undefined && !hash(item.sha256)))
+            fail();
+        if (item.location !== undefined) {
+            const location = item.location;
+            if (!keys(location, ['owner', 'relativePath']) || !ownerValid(location.owner)
+                || !text(location.relativePath) || !/^learnings\/(?:review-queue|review-archive|review-evidence|archive)\//.test(location.relativePath)
+                || /[\\:]/.test(location.relativePath) || location.relativePath.split('/').some((part) => !part || part === '.' || part === '..'))
+                fail();
+        }
+        if (state.finalizationState === 'complete' && item.outcome === 'pending')
+            fail();
+    }
+    if (state.reconciliations !== undefined) {
+        if (!Array.isArray(state.reconciliations))
+            fail();
+        const sources = new Set();
+        for (const item of state.reconciliations) {
+            if (!keys(item, ['sourceRef', 'sourceHash', 'owner', 'relativePath', 'actionIds', 'actionBindings', 'disposition', 'rationale', 'preservedDecisions', 'reviewer'])
+                || !text(item.sourceRef) || sources.has(item.sourceRef) || !hash(item.sourceHash) || !ownerValid(item.owner)
+                || !text(item.relativePath) || !/^learnings\/(?:review-queue|review-archive|review-evidence|archive)\//.test(item.relativePath)
+                || /[\\:]/.test(item.relativePath) || item.relativePath.split('/').some((part) => !part || part === '.' || part === '..')
+                || !['accounted', 'unrelated', 'raw-source'].includes(item.disposition) || !text(item.rationale) || !text(item.reviewer)
+                || !Array.isArray(item.preservedDecisions) || !item.preservedDecisions.every(text)
+                || !Array.isArray(item.actionIds) || new Set(item.actionIds).size !== item.actionIds.length
+                || !Array.isArray(item.actionBindings) || item.actionBindings.length !== item.actionIds.length)
+                fail();
+            sources.add(item.sourceRef);
+            for (const [index, id] of item.actionIds.entries()) {
+                const decision = decisions.get(id);
+                const binding = item.actionBindings[index];
+                if (!decision || !keys(binding, ['actionId', 'revision', 'digest']) || binding.actionId !== id || binding.revision !== decision.revision || binding.digest !== decision.digest
+                    || !state.sourceDispositions.some((source) => source.actionId === id && source.sourceRef.replace(/\\/g, '/') === item.sourceRef.replace(/\\/g, '/') && source.sourceHash === item.sourceHash))
+                    fail();
+            }
+        }
+    }
+    return state;
+}

package/dist/src/cli/commands/cleanup-artifacts.js

@@ -22,10 +22,10 @@ function runCleanupArtifactsCommand(options) {
 }
 exports.cleanupArtifactsCommand = new commander_1.Command('cleanup-artifacts')
     .alias('cleanup-artifact')
-    .description('Evaluate and optionally apply artifact retention cleanup for the current FRAIM workspace')
+    .description('Evaluate and optionally apply artifact retention cleanup for a FRAIM workspace or pack root')
     .option('--user <email>', 'Active user email used only for user-scoped cleanup categories')
     .option('--workspace-root <path>', 'Workspace root containing fraim/config.json')
-    .option('--root <path>', 'Alias for --workspace-root')
+    .option('--root <path>', 'Workspace root or explicit Manager/Org pack root; uses that root\'s retention policy')
     .option('--apply', 'Delete eligible files. Without this flag the command performs a dry run.')
     .action((options) => {
     try {

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

@@ -348,4 +348,4 @@ class AIMentor {
     }
 }
 exports.AIMentor = AIMentor;
-AIMentor.COMPACT_PHASE_AUTHORITY = '**Use only the phases defined in this workflow.**';
+AIMentor.COMPACT_PHASE_AUTHORITY = '**Use only the phases defined in this workflow.** Before phase work, read `get_fraim_file({ path: "orchestration/phase-authority.md" })` for phase closure, approval gates, and resumption.';

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

@@ -17,16 +17,19 @@
  * 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;
+exports.reviewHandoffNormalizationError = reviewHandoffNormalizationError;
 exports.validateReviewHandoff = validateReviewHandoff;
 exports.validateNextJobRecommendations = validateNextJobRecommendations;
 exports.validateDelegationLedger = validateDelegationLedger;
@@ -175,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 };
+}
+/**
+ * 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 };
+}
 /**
- * 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.
+ * 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))
@@ -190,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
@@ -205,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)
@@ -255,23 +340,49 @@ function validateReviewArtifactEntry(artifact, index) {
     return errors;
 }
 /**
- * Validates evidence.reviewHandoff. Returns null if valid, or an array of
- * human-readable error strings describing what is wrong.
- *
- * Required minimum shape:
- * {
- *   reviewRequired: boolean,
- *   artifacts: array,
- *   // when reviewRequired is true:
- *   reviewTarget: { type: "pull_request", label: string, url: string } | { type: "artifact_set", label: string },
- *   reviewActions: [{ kind: "approve", ... }, { kind: "request_changes", ... }],
- * }
- *
- * Hub normalizers (server.ts + script.js) both read reviewTarget.type, not .kind.
- * Using reviewTarget.kind produces a payload that passes validation but is silently
- * un-renderable. This validator enforces the renderable contract so malformed payloads
- * are rejected before phase advancement.
+ * Reports payloads the Hub cannot normalize, including artifact_set entries it
+ * would silently drop. This deliberately preserves the Hub's legacy defaults;
+ * it does not impose the stronger, phase-dependent submission contract.
  */
+function reviewHandoffNormalizationError(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        return 'reviewHandoff must be an object';
+    }
+    const handoff = value;
+    if (typeof handoff.reviewRequired !== 'boolean') {
+        return 'reviewHandoff.reviewRequired must be a boolean';
+    }
+    // This is renderability, not the stronger submission-phase contract below.
+    // In particular legacy handoffs need not supply actions or an artifacts array.
+    if (!handoff.reviewRequired)
+        return null;
+    const target = handoff.reviewTarget;
+    const targetType = typeof target?.type === 'string' ? target.type.trim() : '';
+    if (targetType !== 'pull_request' && targetType !== 'artifact_set') {
+        return 'reviewHandoff.reviewTarget.type must be pull_request or artifact_set';
+    }
+    if (targetType === 'pull_request' && !isAbsoluteHttpUrl(target?.url)) {
+        return 'reviewHandoff.reviewTarget.url must be an absolute http or https URL';
+    }
+    // Match the host parser's object-artifact selection and Hub's path/URL
+    // normalization. A missing label/type is filled in by the Hub, not rejected.
+    const artifacts = Array.isArray(handoff.artifacts)
+        ? handoff.artifacts.filter((artifact) => artifact && typeof artifact === 'object')
+        : [];
+    for (const [index, artifact] of artifacts.entries()) {
+        const hasPath = typeof artifact.path === 'string' && artifact.path.trim().length > 0;
+        const hasUrl = isAbsoluteHttpUrl(artifact.url);
+        if (targetType === 'pull_request') {
+            if (hasPath || hasUrl)
+                return 'reviewHandoff.artifacts must be empty for a pull_request target';
+        }
+        else if (!hasPath || hasUrl) {
+            return `reviewHandoff.artifacts[${index}] cannot be applied: an artifact_set requires a file path without an http or https URL`;
+        }
+    }
+    return null;
+}
+/** Validate the complete submission contract, including required actions. */
 function validateReviewHandoff(value) {
     if (value === undefined || value === null) {
         return ['evidence.reviewHandoff is missing'];
@@ -559,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;
+}