fraim 2.0.280 → 2.0.283

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

@@ -14,9 +14,9 @@ exports.buildAntigravityCommandContent = buildAntigravityCommandContent;
 exports.buildGeminiCommandContent = buildGeminiCommandContent;
 exports.describeInvocationSurface = describeInvocationSurface;
 exports.FRAIM_LAUNCH_PHRASE = 'Use FRAIM for <job or task>';
-exports.CURSOR_MDC_FRONTMATTER = `---
-description: FRAIM discovery and execution contract
-alwaysApply: true
+exports.CURSOR_MDC_FRONTMATTER = `---
+description: FRAIM discovery and execution contract
+alwaysApply: true
 ---`;
 exports.FRAIM_DEFERRED_TOOL_PRELOAD = [
     'fraim_connect',
@@ -38,112 +38,112 @@ function buildDeferredToolBootstrapSection(profile) {
     const preloadList = exports.FRAIM_DEFERRED_TOOL_PRELOAD.map((toolName) => `\`${toolName}\``).join(', ');
     switch (profile) {
         case 'claude-toolsearch':
-            return `0. **Preload deferred FRAIM tools when needed**:
-   - If FRAIM MCP tools are unavailable because this host lazily loads deferred tool schemas, call \`ToolSearch\` once to load ${preloadList}.
-   - Do the preload as one batched discovery step, not one search per tool.
-
+            return `0. **Preload deferred FRAIM tools when needed**:
+   - If FRAIM MCP tools are unavailable because this host lazily loads deferred tool schemas, call \`ToolSearch\` once to load ${preloadList}.
+   - Do the preload as one batched discovery step, not one search per tool.
+
 `;
         case 'codex-tool-search':
-            return `0. **Preload deferred FRAIM tools when needed**:
-   - If FRAIM MCP tools are unavailable because this host lazily loads deferred tool schemas, call \`tool_search\` once to load ${preloadList}.
-   - Do the preload as one batched discovery step, not one search per tool.
-
+            return `0. **Preload deferred FRAIM tools when needed**:
+   - If FRAIM MCP tools are unavailable because this host lazily loads deferred tool schemas, call \`tool_search\` once to load ${preloadList}.
+   - Do the preload as one batched discovery step, not one search per tool.
+
 `;
         case 'generic-tool-discovery':
-            return `0. **Preload deferred FRAIM tools when needed**:
-   - If FRAIM MCP tools are unavailable because this host lazily loads deferred tool schemas, use the host's tool discovery surface once to load ${preloadList}.
-   - Do the preload as one batched discovery step, not one search per tool.
-
+            return `0. **Preload deferred FRAIM tools when needed**:
+   - If FRAIM MCP tools are unavailable because this host lazily loads deferred tool schemas, use the host's tool discovery surface once to load ${preloadList}.
+   - Do the preload as one batched discovery step, not one search per tool.
+
 `;
         default:
             return '';
     }
 }
 function buildFraimInvocationBody(profile = 'none') {
-    return `Follow this process:
-
-${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.
-
-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, say that no FRAIM job matches and continue with normal tools or ask one concise clarification. Do not pick the nearest catalog job.
-
-4. **Load the full content**:
-   - For jobs, call \`get_fraim_job({ job: "<matched-job-name>" })\`.
-   - For skills, use the content returned by \`get_fraim_file(...)\`.
-
-5. **Execute**:
-   - For jobs, follow the phased instructions and use \`seekMentoring\` when the job requires phase transitions.
-   - For skills, apply the skill steps directly to the user's current context.
-   - ${exports.FRAIM_MCP_UNAVAILABLE_MANAGER_GUIDANCE}
+    return `Follow this process:
+
+${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.
+
+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, say that no FRAIM job matches and continue with normal tools or ask one concise clarification. Do not pick the nearest catalog job.
+
+4. **Load the full content**:
+   - For jobs, call \`get_fraim_job({ job: "<matched-job-name>" })\`.
+   - For skills, use the content returned by \`get_fraim_file(...)\`.
+
+5. **Execute**:
+   - For jobs, follow the phased instructions and use \`seekMentoring\` when the job requires phase transitions.
+   - For skills, apply the skill steps directly to the user's current context.
+   - ${exports.FRAIM_MCP_UNAVAILABLE_MANAGER_GUIDANCE}
 `;
 }
 exports.FRAIM_INVOCATION_BODY = buildFraimInvocationBody();
 function buildClaudeSkillContent() {
-    return `# FRAIM
-
+    return `# FRAIM
+
 ${buildFraimInvocationBody('claude-toolsearch')}`;
 }
 function buildClaudeCommandShimContent() {
-    return `# FRAIM Compatibility Command
-
-Use the FRAIM skill when Claude exposes skills directly. This compatibility command keeps \`/fraim\` working on surfaces that still discover legacy command files.
-
+    return `# FRAIM Compatibility Command
+
+Use the FRAIM skill when Claude exposes skills directly. This compatibility command keeps \`/fraim\` working on surfaces that still discover legacy command files.
+
 ${buildFraimInvocationBody('claude-toolsearch')}`;
 }
 function buildClaudeSlashCommandContent() {
     return buildClaudeCommandShimContent();
 }
 function buildCursorMentionRuleContent() {
-    return `${exports.CURSOR_MDC_FRONTMATTER}
-
-# FRAIM
-
-${buildFraimInvocationBody('generic-tool-discovery')}
+    return `${exports.CURSOR_MDC_FRONTMATTER}
+
+# FRAIM
+
+${buildFraimInvocationBody('generic-tool-discovery')}
 `;
 }
-exports.CODEX_SKILL_FRONTMATTER = `---
-name: fraim
-description: Discover and execute FRAIM jobs and skills from Codex.
+exports.CODEX_SKILL_FRONTMATTER = `---
+name: fraim
+description: Discover and execute FRAIM jobs and skills from Codex.
 ---`;
 function buildCodexSkillContent() {
-    return `${exports.CODEX_SKILL_FRONTMATTER}
-# FRAIM
-
+    return `${exports.CODEX_SKILL_FRONTMATTER}
+# FRAIM
+
 ${buildFraimInvocationBody('codex-tool-search')}`;
 }
 function buildGrokSkillContent() {
-    return `# FRAIM
-
+    return `# FRAIM
+
 ${buildFraimInvocationBody('generic-tool-discovery')}`;
 }
 function buildWindsurfCommandContent() {
-    return `# FRAIM
-
+    return `# FRAIM
+
 ${buildFraimInvocationBody('generic-tool-discovery')}`;
 }
 function buildKiroCommandContent() {
-    return `# FRAIM
-
+    return `# FRAIM
+
 ${buildFraimInvocationBody('generic-tool-discovery')}`;
 }
 function escapeTomlMultiline(value) {
     return value.replace(/"""/g, '\\"""');
 }
 function buildAntigravityCommandContent() {
-    return `# FRAIM
-
+    return `# FRAIM
+
 ${buildFraimInvocationBody('generic-tool-discovery')}`;
 }
 function buildGeminiCommandContent() {
-    return `description = "Discover and execute FRAIM jobs and skills"
-prompt = """
-# FRAIM
-
-${escapeTomlMultiline(buildFraimInvocationBody('generic-tool-discovery'))}
+    return `description = "Discover and execute FRAIM jobs and skills"
+prompt = """
+# FRAIM
+
+${escapeTomlMultiline(buildFraimInvocationBody('generic-tool-discovery'))}
 """`;
 }
 function describeInvocationSurface(ideName, invocationProfile) {

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

@@ -25,9 +25,9 @@ function adapterConfigTypes(file) {
     return Array.isArray(file.configType) ? file.configType : [file.configType];
 }
 function buildManagedSection(body) {
-    return `${START_MARKER}
-${body.trim()}
-${END_MARKER}
+    return `${START_MARKER}
+${body.trim()}
+${END_MARKER}
 `;
 }
 function mergeManagedSection(existingContent, managedSection) {
@@ -59,69 +59,69 @@ function getAdapterFiles(allowedConfigTypes = null) {
     const employeeRulesPath = (0, project_fraim_paths_1.getWorkspaceFraimDisplayPath)('ai-employee/rules');
     const personalizedRootPath = (0, project_fraim_paths_1.getWorkspaceFraimDisplayPath)('personalized-employee');
     const projectRulesPath = (0, project_fraim_paths_1.getWorkspaceFraimDisplayPath)('personalized-employee/rules/project_rules.md');
-    const markdownBody = buildManagedSection(`
-## FRAIM
-
-This repository uses FRAIM.
-
-- The FRAIM discovery catalog lives under \`${fraimRoot}/\`.
-- Jobs under \`${employeeJobsPath}/\` and \`${managerJobsPath}/\` are FRAIM's primary execution units. Treat them like first-class workflows when deciding how to execute work.
-- Skills under \`${employeeSkillsPath}/\` are reusable capabilities that jobs compose.
-- Rules under \`${employeeRulesPath}/\` are always-on constraints and conventions.
-- Repo-specific overrides and learning artifacts live under \`${personalizedRootPath}/\` and take precedence over synced baseline content.
-- 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.
-- 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" })\`.
-- Read \`${projectRulesPath}\` if it exists before doing work.
-- When users ask for next step recommendations, use recommend-next-job skill under \`${employeeSkillsPath}/\` to gather context before suggesting jobs.
-- ${ide_invocation_surfaces_1.FRAIM_MCP_UNAVAILABLE_MANAGER_GUIDANCE}
-
-> [!IMPORTANT]
-> **Job stubs are for discovery only.** When a user mentions or references any file under \`${employeeJobsPath}/\` or \`${managerJobsPath}/\`, do NOT attempt to execute the job from the stub content. The stub only shows intent and phase names. Always call \`get_fraim_job({ job: "<job-name>" })\` first to get the full phased instructions before doing any work.
+    const markdownBody = buildManagedSection(`
+## FRAIM
+
+This repository uses FRAIM.
+
+- The FRAIM discovery catalog lives under \`${fraimRoot}/\`.
+- Jobs under \`${employeeJobsPath}/\` and \`${managerJobsPath}/\` are FRAIM's primary execution units. Treat them like first-class workflows when deciding how to execute work.
+- Skills under \`${employeeSkillsPath}/\` are reusable capabilities that jobs compose.
+- Rules under \`${employeeRulesPath}/\` are always-on constraints and conventions.
+- Repo-specific overrides and learning artifacts live under \`${personalizedRootPath}/\` and take precedence over synced baseline content.
+- 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.
+- 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" })\`.
+- Read \`${projectRulesPath}\` if it exists before doing work.
+- When users ask for next step recommendations, use recommend-next-job skill under \`${employeeSkillsPath}/\` to gather context before suggesting jobs.
+- ${ide_invocation_surfaces_1.FRAIM_MCP_UNAVAILABLE_MANAGER_GUIDANCE}
+
+> [!IMPORTANT]
+> **Job stubs are for discovery only.** When a user mentions or references any file under \`${employeeJobsPath}/\` or \`${managerJobsPath}/\`, do NOT attempt to execute the job from the stub content. The stub only shows intent and phase names. Always call \`get_fraim_job({ job: "<job-name>" })\` first to get the full phased instructions before doing any work.
 `);
-    const cursorManagedBody = buildManagedSection(`
-# FRAIM
-
-${(0, ide_invocation_surfaces_1.buildFraimInvocationBody)('generic-tool-discovery')}
+    const cursorManagedBody = buildManagedSection(`
+# FRAIM
+
+${(0, ide_invocation_surfaces_1.buildFraimInvocationBody)('generic-tool-discovery')}
 `);
-    const copilotBody = buildManagedSection(`
-## FRAIM
-
-- Use \`${fraimRoot}/\` as the repository's FRAIM catalog.
-- FRAIM jobs are the primary execution units and should be treated like first-class workflows.
-- FRAIM skills are reusable capabilities jobs compose.
-- FRAIM rules are always-on constraints and conventions.
-- Repo-specific overrides and learnings live under \`${personalizedRootPath}/\`.
-- 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.
-- 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}
+    const copilotBody = buildManagedSection(`
+## FRAIM
+
+- Use \`${fraimRoot}/\` as the repository's FRAIM catalog.
+- FRAIM jobs are the primary execution units and should be treated like first-class workflows.
+- FRAIM skills are reusable capabilities jobs compose.
+- FRAIM rules are always-on constraints and conventions.
+- Repo-specific overrides and learnings live under \`${personalizedRootPath}/\`.
+- 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.
+- 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}
 `);
-    const fraimReadme = `# FRAIM Catalog
-
-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/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.
+    const fraimReadme = `# FRAIM Catalog
+
+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/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.
 `;
-    const vscodePrompt = `# FRAIM
-
+    const vscodePrompt = `# FRAIM
+
 ${(0, ide_invocation_surfaces_1.buildFraimInvocationBody)('generic-tool-discovery')}`;
-    const geminiProjectInstructions = `# Gemini Project Instructions
-
-@../AGENTS.md
+    const geminiProjectInstructions = `# Gemini Project Instructions
+
+@../AGENTS.md
 `;
     const all = [
         { path: 'AGENTS.md', content: markdownBody, configType: 'standard' },

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

@@ -230,6 +230,41 @@ class AIMentor {
             status
         };
     }
+    /**
+     * The job's declared phase graph (onSuccess/onFailure edges), or undefined
+     * for a simple/bootstrap-style job with no phases. Lets a caller derive
+     * graph facts (e.g. "which phase is this job's submission phase", issue
+     * #1276) without hardcoding phase names or duplicating job loading.
+     */
+    async getJobPhaseMap(jobName) {
+        const job = await this.getOrLoadJob(jobName);
+        return job?.metadata.phases;
+    }
+    /**
+     * True when a job's phase, with its includes resolved, itself instructs
+     * the agent to emit `evidence.reviewHandoff` (issue #1318 follow-up).
+     *
+     * The #1276 reviewHandoff gate fires for any job's graph-derived
+     * submission phase, but not every job family promises reviewHandoff at
+     * that phase — jobs built on `rich-review-artifact-contract.md`,
+     * `author-docx.md`, or `reporting-standards.md` (analysis reports, DOCX
+     * deliverables, operational setup jobs) use a different, legitimate
+     * completion contract and never mention the field, even resolved. Gating
+     * those unconditionally would reject a call the job's own instructions
+     * never told the agent to satisfy. This check reads the phase's actual
+     * resolved instructions rather than a hardcoded skill/job allowlist, so
+     * a new reviewHandoff-emitting skill (or a new non-reviewHandoff one)
+     * needs no update here — same "derive, don't hardcode" reasoning as
+     * `derivePredecessorPhase`.
+     */
+    async phasePromisesReviewHandoff(jobName, phaseId) {
+        const job = await this.getOrLoadJob(jobName);
+        const raw = job?.phases.get(phaseId);
+        if (!raw)
+            return false;
+        const resolved = await this.resolveIncludes(raw, job.path);
+        return resolved.includes('evidence.reviewHandoff');
+    }
     async getJobOverview(jobName) {
         const job = await this.getOrLoadJob(jobName);
         if (!job)

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

@@ -5,7 +5,8 @@
  * Pure helpers for validating the three evidence fields that FRAIM jobs must
  * emit on key seekMentoring calls so the Hub can render its review surfaces:
  *
- *   - evidence.reviewHandoff   (submit phase, status === "awaiting_mentor")
+ *   - evidence.reviewHandoff   (job's submission phase, status === "complete";
+ *                               see isSubmitPhase for how that phase is found)
  *   - evidence.nextJobRecommendations  (retrospective phase completion)
  *   - evidence.delegationLedger  (create-delegation-graph phase)
  *
@@ -26,17 +27,36 @@ exports.validateNextJobRecommendations = validateNextJobRecommendations;
 exports.validateDelegationLedger = validateDelegationLedger;
 exports.validateHandoffContracts = validateHandoffContracts;
 exports.buildHandoffRejectionMessage = buildHandoffRejectionMessage;
+const resolve_phase_edge_1 = require("./resolve-phase-edge");
 // ---------------------------------------------------------------------------
 // Phase detection
 // ---------------------------------------------------------------------------
 /**
  * Returns true when a seekMentoring call is a submit-phase handoff requiring
- * a reviewHandoff evidence field. The canonical signal is status === "awaiting_mentor"
- * — set only by submit-phase jobs requesting a review gate — rather than a
- * hardcoded phase name list, which is fragile for personalized jobs.
+ * a reviewHandoff evidence field.
+ *
+ * Two triggers, either is sufficient:
+ *  - `status === "awaiting_mentor"`: the original #916 signal. No published
+ *    `seekMentoring` status permits this value today (confirmed by
+ *    `spike/1157-approval-gate/s5-dead-submit-gate.js`), so this branch is
+ *    provably unreachable in production — kept so a future status value, or a
+ *    job that still emits it, is not silently unenforced.
+ *  - `status === "complete"` at the job's own submission phase, derived from
+ *    its real phase graph (issue #1276, gating-only rebuild of #1157 Change
+ *    1): the unique phase whose `onSuccess` targets `address-feedback`. This
+ *    is the trigger that actually fires. No hardcoded phase-name list — a
+ *    personalized job with a differently-named submission phase is still
+ *    caught, and a job whose graph doesn't uniquely name one (`phases`
+ *    omitted, or the derivation is ambiguous) is not gated at all rather than
+ *    guessed at.
  */
-function isSubmitPhase(currentPhase, status) {
-    return status === 'awaiting_mentor';
+function isSubmitPhase(currentPhase, status, phases) {
+    if (status === 'awaiting_mentor')
+        return true;
+    if (status === 'complete' && phases) {
+        return (0, resolve_phase_edge_1.derivePredecessorPhase)(phases, resolve_phase_edge_1.FEEDBACK_PHASE_ID) === currentPhase;
+    }
+    return false;
 }
 /**
  * Returns true when a seekMentoring call is a retrospective completion.
@@ -221,7 +241,14 @@ function validateHandoffContracts(args) {
     const phase = args.currentPhase ?? '';
     const status = args.status ?? '';
     const evidence = args.evidence ?? {};
-    if (isSubmitPhase(phase, status)) {
+    const findings = args.findings ?? {};
+    if (isSubmitPhase(phase, status, args.phases) && !evidence.reviewHandoff && findings.reviewHandoff) {
+        return ['reviewHandoff was found in findings but must be nested under evidence. Move reviewHandoff out of findings and into the top-level evidence object.'];
+    }
+    if (isRetrospectivePhase(phase, status) && !evidence.nextJobRecommendations && findings.nextJobRecommendations) {
+        return ['nextJobRecommendations was found in findings but must be nested under evidence. Move nextJobRecommendations out of findings and into the top-level evidence object.'];
+    }
+    if (isSubmitPhase(phase, status, args.phases)) {
         const errors = validateReviewHandoff(evidence.reviewHandoff);
         if (errors)
             return errors;
@@ -246,48 +273,48 @@ function validateHandoffContracts(args) {
 // ---------------------------------------------------------------------------
 // Rejection message builder
 // ---------------------------------------------------------------------------
-const ADDRESS_FEEDBACK_APPROVAL_SCHEMA = `\`\`\`javascript
-evidence: {
-  approved: true  // Set only after the manager explicitly approves via the Hub review action
-}
+const ADDRESS_FEEDBACK_APPROVAL_SCHEMA = `\`\`\`javascript
+evidence: {
+  approved: true  // Set only after the manager explicitly approves via the Hub review action
+}
 \`\`\``;
-const REVIEW_HANDOFF_SCHEMA = `\`\`\`javascript
-evidence: {
-  reviewHandoff: {
-    reviewRequired: true,
-    reviewTarget: { kind: "pull_request", url: "<PR URL>" } | { kind: "artifact_set", files: ["<path>"] } | null,
-    artifacts: [{ label: "<label>", path: "<path>", kind: "<kind>" }],
-    summary: "<optional summary>",
-    reviewActions: [
-      { kind: "approve", label: "Approve" },
-      { kind: "request_changes", label: "Request Changes" }
-    ]
-  }
-}
+const REVIEW_HANDOFF_SCHEMA = `\`\`\`javascript
+evidence: {
+  reviewHandoff: {
+    reviewRequired: true,
+    reviewTarget: { kind: "pull_request", url: "<PR URL>" } | { kind: "artifact_set", files: ["<path>"] } | null,
+    artifacts: [{ label: "<label>", path: "<path>", kind: "<kind>" }],
+    summary: "<optional summary>",
+    reviewActions: [
+      { kind: "approve", label: "Approve" },
+      { kind: "request_changes", label: "Request Changes" }
+    ]
+  }
+}
 \`\`\``;
-const NEXT_JOB_RECOMMENDATIONS_SCHEMA = `\`\`\`javascript
-evidence: {
-  nextJobRecommendations: [
-    {
-      jobId: "<job-slug>",
-      label: "<human-readable label>",
-      reason: "<optional: why this job is recommended>",
-      contextSummary: "<optional: one sentence context for the next agent>"
-    }
-    // 0–3 entries; an empty array [] is valid
-  ]
-}
+const NEXT_JOB_RECOMMENDATIONS_SCHEMA = `\`\`\`javascript
+evidence: {
+  nextJobRecommendations: [
+    {
+      jobId: "<job-slug>",
+      label: "<human-readable label>",
+      reason: "<optional: why this job is recommended>",
+      contextSummary: "<optional: one sentence context for the next agent>"
+    }
+    // 0–3 entries; an empty array [] is valid
+  ]
+}
 \`\`\``;
-const DELEGATION_LEDGER_SCHEMA = `\`\`\`javascript
-evidence: {
-  delegationLedger: {
-    delegationRequired: true,
-    objective: "<optional objective string>",
-    tasks: [
-      { jobId: "<job-slug>", personaKey: "<persona key or null>", briefing: "<optional briefing>" }
-    ]
-  }
-}
+const DELEGATION_LEDGER_SCHEMA = `\`\`\`javascript
+evidence: {
+  delegationLedger: {
+    delegationRequired: true,
+    objective: "<optional objective string>",
+    tasks: [
+      { jobId: "<job-slug>", personaKey: "<persona key or null>", briefing: "<optional briefing>" }
+    ]
+  }
+}
 \`\`\``;
 const FIELD_SCHEMAS = {
     approved: ADDRESS_FEEDBACK_APPROVAL_SCHEMA,

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

@@ -15,9 +15,11 @@
  * change inert for every job that authors no map.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.FEEDBACK_PHASE_ID = void 0;
 exports.resolvePhaseEdge = resolvePhaseEdge;
 exports.resolveDiscriminant = resolveDiscriminant;
 exports.discriminantKeys = discriminantKeys;
+exports.derivePredecessorPhase = derivePredecessorPhase;
 /** The default discriminant, and the mandatory key on every authored map. */
 const DEFAULT_DISCRIMINANT = 'default';
 /**
@@ -73,3 +75,34 @@ function discriminantKeys(edge) {
         return [];
     return Object.keys(edge).filter((key) => key !== DEFAULT_DISCRIMINANT);
 }
+/** The framework's one review/decision phase; every reviewable job routes into it. */
+exports.FEEDBACK_PHASE_ID = 'address-feedback';
+/**
+ * Finds the unique phase in a job's phase map whose `onSuccess` edge can
+ * resolve to `targetPhaseId` for some discriminant (including `default`).
+ *
+ * Gating-only rebuild of #1157 Change 1 ("graph-derived phase identity"),
+ * scoped per #1276: that change also added routing behavior and was reverted
+ * before merge because the two were bundled. Only the lookup survives here —
+ * it answers "which phase is this job's submission phase" without changing
+ * how any phase transition resolves. No hardcoded phase-name list: the
+ * derivation reads whatever the job's own graph declares, so it is correct
+ * for every current and future job without per-job edits.
+ *
+ * Returns `null` when zero or multiple phases match, so a caller can fail
+ * safe (treat as "unknown") rather than guess at an ambiguous graph.
+ */
+function derivePredecessorPhase(phases, targetPhaseId) {
+    const predecessors = [];
+    for (const [phaseId, edges] of Object.entries(phases ?? {})) {
+        if (phaseId === targetPhaseId || !edges)
+            continue;
+        const edge = edges.onSuccess;
+        const targets = typeof edge === 'string'
+            ? [edge]
+            : (edge && typeof edge === 'object' ? Object.values(edge) : []);
+        if (targets.includes(targetPhaseId))
+            predecessors.push(phaseId);
+    }
+    return predecessors.length === 1 ? predecessors[0] : null;
+}