feat: preserve readiness action details in runtime

Jacobinwwey · Jacobinwwey · commit 321a6eb52cf7 · 2026-04-20T23:04:09.000-05:00
diff --git a/docs/brainstorms/2026-04-19-mainline-progress-reconciliation-and-post-m7-direction-requirements.md b/docs/brainstorms/2026-04-19-mainline-progress-reconciliation-and-post-m7-direction-requirements.md
@@ -233,6 +233,10 @@ This document re-baselines current mainline truth on 2026-04-19, records what ch
   - agent-workspace diagnostics snapshots now persist `mandatoryCheckIds`
   - toolbar summaries now render the same gate ids exposed by `mandatoryChecks`
   - overall status still remains `in_progress` / `no-go`.
+- The next bounded execution slice after that makes runtime actionable-detail parity explicit:
+  - agent-workspace diagnostics snapshots now persist full `mandatoryChecks`, `promotionBlockers`, and `recommendations`
+  - toolbar summaries now expose recommendation counts alongside the existing gate/blocker ids
+  - overall status still remains `in_progress` / `no-go`.
 - Current expected outcome on `main` remains:
   - status `in_progress`
   - decision `no-go`
diff --git a/docs/diataxis/en/explanation/development-progress-dashboard.md b/docs/diataxis/en/explanation/development-progress-dashboard.md
@@ -340,6 +340,20 @@ Execution anchor:
   - decision stays `no-go`,
   - gate parity improves inspectability only; it does not weaken the promotion contract.
 
+## Latest Mainline Increment (2026-04-20 M8.17 Foundation Runtime Actionable-Detail Parity)
+
+- Closed the next operator-runtime parity gap for actionable readiness detail arrays already present in the typed payload:
+  - `lastFoundationReadiness.mandatoryChecks`
+  - `lastFoundationReadiness.promotionBlockers`
+  - `lastFoundationReadiness.recommendations`
+- Runtime/operator visibility now keeps the same actionable detail used by exported diagnostics:
+  - toolbar summaries expose `recommendations 2` alongside existing gate/blocker ids,
+  - diagnostics snapshots preserve full gate commands, blocker summaries, and recommendation strings for downstream report consumers.
+- Guardrail remains unchanged on `main`:
+  - status stays `in_progress`,
+  - decision stays `no-go`,
+  - actionable-detail parity improves inspectability only; it does not relax the no-go contract.
+
 ## Latest Mainline Increment (2026-04-20 M8.13 Foundation Readiness Provenance Evidence)
 
 - Added machine-readable provenance so operator tooling can tell whether readiness is reading the runtime project root or falling back to real repo evidence:
diff --git a/docs/diataxis/en/explanation/foundation-reentry-readiness-checklist.md b/docs/diataxis/en/explanation/foundation-reentry-readiness-checklist.md
@@ -54,6 +54,7 @@ Bundle note:
   - runbook link `foundation-reentry-readiness-checklist`
   - runtime snapshots now preserve both `promotionCriteriaSatisfiedIds` and `promotionCriteriaUnsatisfiedIds`
   - runtime snapshots now preserve `mandatoryCheckIds` for the active gate contract
+  - runtime snapshots now preserve full `mandatoryChecks`, `promotionBlockers`, and `recommendations`
 - Current expected result on `main` is:
   - status `In Progress`
   - decision `No-Go`
@@ -90,6 +91,7 @@ Bundle note:
   - `promotionCriteriaUnsatisfiedIds = [graph_backend_independent, vector_backend_independent]`
 - Current expected runtime/operator summary phrasing on `main` is:
   - `gates contract, core_behavior, persistence_safety, interaction_non_regression, documentation`
+  - `recommendations 2`
   - `satisfied store_backend_evidence_present, query_backend_boundary_present, vector_backend_present, docs_aligned, readiness_verifier_present`
   - `unmet graph_backend_independent, vector_backend_independent`
 - Current expected provenance behavior is:
diff --git a/docs/diataxis/zh/explanation/development-progress-dashboard.md b/docs/diataxis/zh/explanation/development-progress-dashboard.md
@@ -340,6 +340,20 @@
   - 决策仍为 `no-go`，
   - gate 对齐只提升可检查性，不会削弱 promotion contract。
 
+## 主线最新增量（2026-04-20 M8.17 Foundation 运行时可执行细节对齐）
+
+- 已补齐 typed readiness payload 中可执行细节数组在运行时中的下一处对齐缺口：
+  - `lastFoundationReadiness.mandatoryChecks`
+  - `lastFoundationReadiness.promotionBlockers`
+  - `lastFoundationReadiness.recommendations`
+- 运行时/执行侧现在会保留导出诊断所需的同一组 actionable detail：
+  - 工具栏摘要会在既有 gate/blocker ids 之外显示 `recommendations 2`，
+  - diagnostics snapshot 会保留 gate command、blocker summary、recommendation string，便于后续报告消费。
+- `main` 上的护栏结论保持不变：
+  - 状态仍为 `in_progress`，
+  - 决策仍为 `no-go`，
+  - 可执行细节对齐只提升可检查性，不会放松 no-go contract。
+
 ## 主线最新增量（2026-04-20 M8.13 Foundation Readiness 来源证据）
 
 - 已新增 machine-readable provenance，执行侧现在可以直接知道 readiness 是读取 runtime project root，还是回退到真实 repo 证据：
diff --git a/docs/diataxis/zh/explanation/foundation-reentry-readiness-checklist.md b/docs/diataxis/zh/explanation/foundation-reentry-readiness-checklist.md
@@ -54,6 +54,7 @@
   - runbook link `foundation-reentry-readiness-checklist`
   - runtime snapshot 现在会同时保留 `promotionCriteriaSatisfiedIds` 与 `promotionCriteriaUnsatisfiedIds`
   - runtime snapshot 现在也会保留当前 gate contract 的 `mandatoryCheckIds`
+  - runtime snapshot 现在也会保留完整 `mandatoryChecks`、`promotionBlockers`、`recommendations`
 - 当前主线的预期结果是：
   - 状态 `In Progress`
   - 决策 `No-Go`
@@ -90,6 +91,7 @@
   - `promotionCriteriaUnsatisfiedIds = [graph_backend_independent, vector_backend_independent]`
 - 当前主线预期的运行时/执行侧摘要措辞为：
   - `gates contract, core_behavior, persistence_safety, interaction_non_regression, documentation`
+  - `recommendations 2`
   - `satisfied store_backend_evidence_present, query_backend_boundary_present, vector_backend_present, docs_aligned, readiness_verifier_present`
   - `unmet graph_backend_independent, vector_backend_independent`
 - 当前预期 provenance 行为为：
diff --git a/src/agent_workspace.runtime.behavior.test.ts b/src/agent_workspace.runtime.behavior.test.ts
@@ -1809,6 +1809,7 @@ describe('agent workspace runtime behavior', () => {
         expect(messages.textContent || '').toContain(
             'gates contract, core_behavior, persistence_safety, interaction_non_regression, documentation'
         );
+        expect(messages.textContent || '').toContain('recommendations 2');
         expect(messages.textContent || '').toContain(
             'satisfied store_backend_evidence_present, query_backend_boundary_present, vector_backend_present, docs_aligned, readiness_verifier_present'
         );
@@ -1846,6 +1847,28 @@ describe('agent workspace runtime behavior', () => {
                     'interaction_non_regression',
                     'documentation',
                 ],
+                mandatoryChecks: [
+                    {
+                        gateId: 'contract',
+                        command: 'npm test -- src/knowledge.api.contract.test.ts --runInBand',
+                    },
+                    {
+                        gateId: 'core_behavior',
+                        command: 'npm test -- src/learning/KnowledgeLearningPlatform.test.ts --runInBand',
+                    },
+                    {
+                        gateId: 'persistence_safety',
+                        command: 'npm test -- src/learning/KnowledgeLearningPlatform.persistence.test.ts --runInBand',
+                    },
+                    {
+                        gateId: 'interaction_non_regression',
+                        command: 'npm run test:agent-workspace:contracts',
+                    },
+                    {
+                        gateId: 'documentation',
+                        command: 'npm run docs:diataxis:check && npm run docs:site:build',
+                    },
+                ],
                 promotionCriteriaSatisfiedIds: [
                     'store_backend_evidence_present',
                     'query_backend_boundary_present',
@@ -1861,10 +1884,24 @@ describe('agent workspace runtime behavior', () => {
                     'graph_backend_not_independent',
                     'vector_backend_not_independent',
                 ],
+                promotionBlockers: [
+                    {
+                        blockerId: 'graph_backend_not_independent',
+                        summary: 'Graph backend still resolves to file-backed snapshot semantics.',
+                    },
+                    {
+                        blockerId: 'vector_backend_not_independent',
+                        summary: 'Vector backend still resolves to lexical prefilter semantics.',
+                    },
+                ],
                 promotionCriteriaPassed: 5,
                 promotionCriteriaTotal: 7,
                 mandatoryChecksCount: 5,
                 promotionBlockersCount: 2,
+                recommendations: [
+                    'Keep foundation re-entry at no-go while graph persistence remains file-backed snapshot storage without independent graph backend semantics on mainline.',
+                    'Keep foundation re-entry at no-go while the vector adapter remains a local prefilter boundary without independent ANN evidence on mainline.',
+                ],
                 recommendationsCount: 2,
             })
         );
diff --git a/src/frontend/agent_workspace_runtime.js b/src/frontend/agent_workspace_runtime.js
@@ -1445,13 +1445,16 @@
                     repoRootSource: '',
                     runtimeProjectRootAligned: false,
                     mandatoryCheckIds: [],
+                    mandatoryChecks: [],
                     promotionCriteriaPassed: 0,
                     promotionCriteriaTotal: 0,
                     mandatoryChecksCount: 0,
                     promotionCriteriaSatisfiedIds: [],
                     promotionCriteriaUnsatisfiedIds: [],
                     promotionBlockerIds: [],
+                    promotionBlockers: [],
                     promotionBlockersCount: 0,
+                    recommendations: [],
                     recommendationsCount: 0,
                 };
                 setBusy(true);
@@ -1478,6 +1481,17 @@
                             })
                             .filter(Boolean)
                         : [];
+                    const mandatoryChecks = Array.isArray(readiness && readiness.mandatoryChecks)
+                        ? readiness.mandatoryChecks
+                            .map((entry) => {
+                                const source = entry && typeof entry === 'object' ? entry : {};
+                                return {
+                                    gateId: trimString(source.gateId),
+                                    command: trimString(source.command),
+                                };
+                            })
+                            .filter((entry) => entry.gateId)
+                        : [];
                     const provenance = readiness && readiness.provenance && typeof readiness.provenance === 'object'
                         ? readiness.provenance
                         : {};
@@ -1538,13 +1552,18 @@
                         repoRootSource: trimString(provenance.repoRootSource),
                         runtimeProjectRootAligned: Boolean(provenance.runtimeProjectRootAligned),
                         mandatoryCheckIds,
+                        mandatoryChecks,
                         promotionCriteriaPassed,
                         promotionCriteriaTotal,
                         mandatoryChecksCount: mandatoryCheckIds.length,
                         promotionCriteriaSatisfiedIds,
                         promotionCriteriaUnsatisfiedIds,
                         promotionBlockerIds,
+                        promotionBlockers,
                         promotionBlockersCount: promotionBlockerIds.length,
+                        recommendations: Array.isArray(readiness && readiness.recommendations)
+                            ? readiness.recommendations.map((entry) => trimString(entry)).filter(Boolean)
+                            : [],
                         recommendationsCount,
                     };
                     const queryBackendScoreSignals = Array.isArray(baseline.queryBackendScoreSignals)
@@ -1554,7 +1573,7 @@
                         'assistant',
                         getI18nText(
                             'agentWorkspace.messages.foundationReadinessLoaded',
-                            `Foundation readiness ${trimString(readiness && readiness.status) || 'unknown'} / ${trimString(readiness && readiness.decision) || 'unknown'} (store ${trimString(baseline.storeType) || 'n/a'}, graph ${trimString(baseline.graphBackendStatus) || 'n/a'}/${trimString(baseline.graphBackendSignalKind) || 'n/a'}, graph-independent ${Boolean(baseline.graphBackendIndependent) ? 'yes' : 'no'}, backend ${trimString(baseline.queryBackendDefaultMode) || 'n/a'}, signals ${queryBackendScoreSignals.join(', ') || 'none'}, vector ${trimString(baseline.vectorAdapterStatus) || 'n/a'}, signal-kind ${trimString(baseline.vectorAdapterSignalKind) || 'n/a'}, independent ${Boolean(baseline.vectorAdapterIndependent) ? 'yes' : 'no'}, linked ${Boolean(baseline.vectorAdapterLinkedIntoQueryBackend) ? 'yes' : 'no'}, repo-source ${trimString(provenance.repoRootSource) || 'n/a'}, aligned ${Boolean(provenance.runtimeProjectRootAligned) ? 'yes' : 'no'}, gates ${mandatoryCheckIds.join(', ') || 'none'}, criteria ${promotionCriteriaPassed}/${promotionCriteriaTotal}, satisfied ${promotionCriteriaSatisfiedIds.join(', ') || 'none'}, unmet ${promotionCriteriaUnsatisfiedIds.join(', ') || 'none'}, blockers ${promotionBlockerIds.join(', ') || 'none'}).`,
+                            `Foundation readiness ${trimString(readiness && readiness.status) || 'unknown'} / ${trimString(readiness && readiness.decision) || 'unknown'} (store ${trimString(baseline.storeType) || 'n/a'}, graph ${trimString(baseline.graphBackendStatus) || 'n/a'}/${trimString(baseline.graphBackendSignalKind) || 'n/a'}, graph-independent ${Boolean(baseline.graphBackendIndependent) ? 'yes' : 'no'}, backend ${trimString(baseline.queryBackendDefaultMode) || 'n/a'}, signals ${queryBackendScoreSignals.join(', ') || 'none'}, vector ${trimString(baseline.vectorAdapterStatus) || 'n/a'}, signal-kind ${trimString(baseline.vectorAdapterSignalKind) || 'n/a'}, independent ${Boolean(baseline.vectorAdapterIndependent) ? 'yes' : 'no'}, linked ${Boolean(baseline.vectorAdapterLinkedIntoQueryBackend) ? 'yes' : 'no'}, repo-source ${trimString(provenance.repoRootSource) || 'n/a'}, aligned ${Boolean(provenance.runtimeProjectRootAligned) ? 'yes' : 'no'}, gates ${mandatoryCheckIds.join(', ') || 'none'}, criteria ${promotionCriteriaPassed}/${promotionCriteriaTotal}, satisfied ${promotionCriteriaSatisfiedIds.join(', ') || 'none'}, unmet ${promotionCriteriaUnsatisfiedIds.join(', ') || 'none'}, blockers ${promotionBlockerIds.join(', ') || 'none'}, recommendations ${recommendationsCount}).`,
                             {
                                 status: trimString(readiness && readiness.status) || 'unknown',
                                 decision: trimString(readiness && readiness.decision) || 'unknown',
@@ -1578,6 +1597,7 @@
                                 promotionCriteriaSatisfiedIds: promotionCriteriaSatisfiedIds.join(', ') || 'none',
                                 promotionCriteriaUnsatisfiedIds: promotionCriteriaUnsatisfiedIds.join(', ') || 'none',
                                 promotionBlockerIds: promotionBlockerIds.join(', ') || 'none',
+                                recommendationsCount,
                             }
                         )
                     );
@@ -1601,13 +1621,16 @@
                         repoRootSource: '',
                         runtimeProjectRootAligned: false,
                         mandatoryCheckIds: [],
+                        mandatoryChecks: [],
                         promotionCriteriaPassed: 0,
                         promotionCriteriaTotal: 0,
                         mandatoryChecksCount: 0,
                         promotionCriteriaSatisfiedIds: [],
                         promotionCriteriaUnsatisfiedIds: [],
                         promotionBlockerIds: [],
+                        promotionBlockers: [],
                         promotionBlockersCount: 0,
+                        recommendations: [],
                         recommendationsCount: 0,
                     };
                     recordFailure('loadFoundationReadiness', errorMessage);
diff --git a/src/frontend/locales/en.json b/src/frontend/locales/en.json
@@ -282,7 +282,7 @@
       "learningQualitySnapshotFailed": "Learning quality snapshot request failed.",
       "learningQualitySnapshotLoaded": "Learning quality snapshot loaded (retest {retestPassRatePct}%, recurrence {misconceptionRecurrenceRatePct}%).",
       "foundationReadinessFailed": "Foundation readiness request failed.",
-      "foundationReadinessLoaded": "Foundation readiness {status} / {decision} (store {storeType}, graph {graphBackendStatus}/{graphBackendSignalKind}, graph-independent {graphBackendIndependent}, backend {queryBackendDefaultMode}, signals {queryBackendScoreSignals}, vector {vectorAdapterStatus}, signal-kind {vectorAdapterSignalKind}, independent {vectorAdapterIndependent}, linked {vectorAdapterLinkedIntoQueryBackend}, repo-source {repoRootSource}, aligned {runtimeProjectRootAligned}, gates {mandatoryCheckIds}, criteria {promotionCriteriaPassed}/{promotionCriteriaTotal}, satisfied {promotionCriteriaSatisfiedIds}, unmet {promotionCriteriaUnsatisfiedIds}, blockers {promotionBlockerIds}).",
+      "foundationReadinessLoaded": "Foundation readiness {status} / {decision} (store {storeType}, graph {graphBackendStatus}/{graphBackendSignalKind}, graph-independent {graphBackendIndependent}, backend {queryBackendDefaultMode}, signals {queryBackendScoreSignals}, vector {vectorAdapterStatus}, signal-kind {vectorAdapterSignalKind}, independent {vectorAdapterIndependent}, linked {vectorAdapterLinkedIntoQueryBackend}, repo-source {repoRootSource}, aligned {runtimeProjectRootAligned}, gates {mandatoryCheckIds}, criteria {promotionCriteriaPassed}/{promotionCriteriaTotal}, satisfied {promotionCriteriaSatisfiedIds}, unmet {promotionCriteriaUnsatisfiedIds}, blockers {promotionBlockerIds}, recommendations {recommendationsCount}).",
       "memoryPolicyFailed": "Memory snapshot request failed.",
       "memoryPolicyLoaded": "Memory snapshot loaded ({layer}/{operation}): {entriesCount} entries, evicted {evictedCount}, totals session {sessionCount}, unit {unitCount}, long-term {longTermCount}, recommended {recommendedActionsCount} actions."
     }
diff --git a/src/frontend/locales/zh.json b/src/frontend/locales/zh.json
@@ -282,7 +282,7 @@
       "learningQualitySnapshotFailed": "学习质量快照请求失败。",
       "learningQualitySnapshotLoaded": "学习质量快照已加载（复测通过率 {retestPassRatePct}% ，误解复发率 {misconceptionRecurrenceRatePct}%）。",
       "foundationReadinessFailed": "基础就绪性请求失败。",
-      "foundationReadinessLoaded": "基础就绪性 {status} / {decision}（存储 {storeType}，图后端 {graphBackendStatus}/{graphBackendSignalKind}，图独立性 {graphBackendIndependent}，后端 {queryBackendDefaultMode}，打分信号 {queryBackendScoreSignals}，向量阶段 {vectorAdapterStatus}，信号类型 {vectorAdapterSignalKind}，独立性 {vectorAdapterIndependent}，接线 {vectorAdapterLinkedIntoQueryBackend}，repo 来源 {repoRootSource}，对齐 {runtimeProjectRootAligned}，门禁 {mandatoryCheckIds}，条件 {promotionCriteriaPassed}/{promotionCriteriaTotal}，已满足 {promotionCriteriaSatisfiedIds}，未满足 {promotionCriteriaUnsatisfiedIds}，阻塞项 {promotionBlockerIds}）。",
+      "foundationReadinessLoaded": "基础就绪性 {status} / {decision}（存储 {storeType}，图后端 {graphBackendStatus}/{graphBackendSignalKind}，图独立性 {graphBackendIndependent}，后端 {queryBackendDefaultMode}，打分信号 {queryBackendScoreSignals}，向量阶段 {vectorAdapterStatus}，信号类型 {vectorAdapterSignalKind}，独立性 {vectorAdapterIndependent}，接线 {vectorAdapterLinkedIntoQueryBackend}，repo 来源 {repoRootSource}，对齐 {runtimeProjectRootAligned}，门禁 {mandatoryCheckIds}，条件 {promotionCriteriaPassed}/{promotionCriteriaTotal}，已满足 {promotionCriteriaSatisfiedIds}，未满足 {promotionCriteriaUnsatisfiedIds}，阻塞项 {promotionBlockerIds}，建议 {recommendationsCount} 条）。",
       "memoryPolicyFailed": "记忆快照请求失败。",
       "memoryPolicyLoaded": "记忆快照已加载（{layer}/{operation}）：{entriesCount} 条，清理 {evictedCount} 条，总量 session {sessionCount}、unit {unitCount}、long-term {longTermCount}，推荐动作 {recommendedActionsCount} 个。"
     }

Original file line number	Diff line number	Diff line change
`@@ -282,7 +282,7 @@`
`282`	`282`	`"learningQualitySnapshotFailed": "Learning quality snapshot request failed.",`
`283`	`283`	`"learningQualitySnapshotLoaded": "Learning quality snapshot loaded (retest {retestPassRatePct}%, recurrence {misconceptionRecurrenceRatePct}%).",`
`284`	`284`	`"foundationReadinessFailed": "Foundation readiness request failed.",`
`285`		- "foundationReadinessLoaded": "Foundation readiness {status} / {decision} (store {storeType}, graph {graphBackendStatus}/{graphBackendSignalKind}, graph-independent {graphBackendIndependent}, backend {queryBackendDefaultMode}, signals {queryBackendScoreSignals}, vector {vectorAdapterStatus}, signal-kind {vectorAdapterSignalKind}, independent {vectorAdapterIndependent}, linked {vectorAdapterLinkedIntoQueryBackend}, repo-source {repoRootSource}, aligned {runtimeProjectRootAligned}, gates {mandatoryCheckIds}, criteria {promotionCriteriaPassed}/{promotionCriteriaTotal}, satisfied {promotionCriteriaSatisfiedIds}, unmet {promotionCriteriaUnsatisfiedIds}, blockers {promotionBlockerIds}).",
	`285`	+ "foundationReadinessLoaded": "Foundation readiness {status} / {decision} (store {storeType}, graph {graphBackendStatus}/{graphBackendSignalKind}, graph-independent {graphBackendIndependent}, backend {queryBackendDefaultMode}, signals {queryBackendScoreSignals}, vector {vectorAdapterStatus}, signal-kind {vectorAdapterSignalKind}, independent {vectorAdapterIndependent}, linked {vectorAdapterLinkedIntoQueryBackend}, repo-source {repoRootSource}, aligned {runtimeProjectRootAligned}, gates {mandatoryCheckIds}, criteria {promotionCriteriaPassed}/{promotionCriteriaTotal}, satisfied {promotionCriteriaSatisfiedIds}, unmet {promotionCriteriaUnsatisfiedIds}, blockers {promotionBlockerIds}, recommendations {recommendationsCount}).",
`286`	`286`	`"memoryPolicyFailed": "Memory snapshot request failed.",`
`287`	`287`	`"memoryPolicyLoaded": "Memory snapshot loaded ({layer}/{operation}): {entriesCount} entries, evicted {evictedCount}, totals session {sessionCount}, unit {unitCount}, long-term {longTermCount}, recommended {recommendedActionsCount} actions."`
`288`	`288`	`}`