fraim 2.0.338 → 2.0.340

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

@@ -0,0 +1,153 @@
+"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;
+        if (!keys(decision, ['action', 'revision', 'digest', 'reviewer', 'reason', 'revisitCondition', '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))))
+            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

@@ -27,6 +27,7 @@ exports.validateReviewActionCompleteness = validateReviewActionCompleteness;
 exports.hasPhaseStarted = hasPhaseStarted;
 exports.upsertPhaseStarted = upsertPhaseStarted;
 exports.buildPhaseStartWarning = buildPhaseStartWarning;
+exports.reviewHandoffNormalizationError = reviewHandoffNormalizationError;
 exports.validateReviewHandoff = validateReviewHandoff;
 exports.validateNextJobRecommendations = validateNextJobRecommendations;
 exports.validateDelegationLedger = validateDelegationLedger;
@@ -255,23 +256,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'];

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

@@ -28,9 +28,14 @@ exports.ARTIFACT_RETENTION_CATEGORIES = [
     'learning_usage',
     'hub_event_logs',
 ];
+function contentRoot(workspaceRoot) {
+    const packContent = node_path_1.default.join(workspaceRoot, 'personalized-employee');
+    return node_fs_1.default.existsSync(packContent) ? packContent : node_path_1.default.join(workspaceRoot, 'fraim', 'personalized-employee');
+}
 function readWorkspaceConfig(workspaceRoot) {
     try {
-        const configPath = (0, project_fraim_paths_1.getWorkspaceConfigPath)(workspaceRoot);
+        const configPath = contentRoot(workspaceRoot) === node_path_1.default.join(workspaceRoot, 'personalized-employee')
+            ? node_path_1.default.join(workspaceRoot, 'config.json') : (0, project_fraim_paths_1.getWorkspaceConfigPath)(workspaceRoot);
         if (!node_fs_1.default.existsSync(configPath))
             return {};
         return JSON.parse(node_fs_1.default.readFileSync(configPath, 'utf8'));
@@ -143,7 +148,7 @@ function loadGitLastChangeDates(workspaceRoot, relativeDir) {
     return dates;
 }
 function readFrontmatter(content) {
-    const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+    const match = content.match(/^(?:\uFEFF)?---\r?\n([\s\S]*?)\r?\n---/);
     if (!match)
         return {};
     const values = {};
@@ -167,8 +172,20 @@ function synthesizedDate(absolutePath) {
         return undefined;
     }
 }
-function userScoped(fileName, activeUserEmail) {
-    return fileName.startsWith(`${activeUserEmail}-`);
+function userScoped(filePath, activeUserEmail) {
+    try {
+        const body = node_fs_1.default.readFileSync(filePath, 'utf8');
+        const author = readFrontmatter(body).author;
+        if (author !== undefined) {
+            const value = author.replace(/^(?:"([^"]*)"|'([^']*)')$/, (_match, double, single) => double ?? single);
+            return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value) && value === activeUserEmail;
+        }
+        // Older artifacts used the author in their filename.
+        return node_path_1.default.basename(filePath).startsWith(`${activeUserEmail}-`);
+    }
+    catch {
+        return false;
+    }
 }
 function evidenceEligibilityDate(workspaceRoot, absolutePath, gitDates) {
     const relativePath = normalizeRelative(workspaceRoot, absolutePath);
@@ -187,17 +204,22 @@ function collectCandidates(workspaceRoot, options) {
             eligibilityDate,
         });
     };
-    const archiveDir = node_path_1.default.join(workspaceRoot, 'fraim', 'personalized-employee', 'learnings', 'archive');
+    const content = contentRoot(workspaceRoot);
+    const archiveDir = node_path_1.default.join(content, 'learnings', 'archive');
     for (const filePath of listFiles(archiveDir)) {
         const fileName = node_path_1.default.basename(filePath);
-        if (!fileName.endsWith('.md') || !userScoped(fileName, activeUserEmail))
+        if (!fileName.endsWith('.md') || !userScoped(filePath, activeUserEmail))
             continue;
         add('learning_archive', filePath, true, 'Archived learning source for active user.', fileMtime(filePath));
     }
-    const retrospectivesDir = node_path_1.default.join(workspaceRoot, 'docs', 'retrospectives');
-    for (const filePath of listFiles(retrospectivesDir)) {
+    const retrospectives = new Set([
+        node_path_1.default.join(workspaceRoot, 'docs', 'retrospectives'),
+        node_path_1.default.join(workspaceRoot, 'retrospectives'),
+        node_path_1.default.join(content, 'retrospectives'),
+    ].flatMap(listFiles));
+    for (const filePath of retrospectives) {
         const fileName = node_path_1.default.basename(filePath);
-        if (!fileName.endsWith('.md') || !userScoped(fileName, activeUserEmail))
+        if (!fileName.endsWith('.md') || !userScoped(filePath, activeUserEmail))
             continue;
         const date = synthesizedDate(filePath);
         if (date)
@@ -209,6 +231,11 @@ function collectCandidates(workspaceRoot, options) {
     const evidenceGitDates = loadGitLastChangeDates(workspaceRoot, 'docs/evidence');
     for (const filePath of listFiles(evidenceDir)) {
         const fileName = node_path_1.default.basename(filePath);
+        // A surviving run journal is unfinished recovery; completion removes it.
+        if (fileName.endsWith('.queue.jsonl')) {
+            add('evidence', filePath, false, 'Unfinished Sleep run journal; removed by run completion.');
+            continue;
+        }
         const isMarkdown = fileName.endsWith('.md');
         const isJson = fileName.endsWith('.json');
         const eligibilityDate = evidenceEligibilityDate(workspaceRoot, filePath, evidenceGitDates);