briefloop 0.11.12__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (424) hide show
  1. briefloop-0.11.12.dist-info/METADATA +473 -0
  2. briefloop-0.11.12.dist-info/RECORD +424 -0
  3. briefloop-0.11.12.dist-info/WHEEL +5 -0
  4. briefloop-0.11.12.dist-info/entry_points.txt +3 -0
  5. briefloop-0.11.12.dist-info/licenses/LICENSE +22 -0
  6. briefloop-0.11.12.dist-info/top_level.txt +1 -0
  7. multi_agent_brief/__init__.py +36 -0
  8. multi_agent_brief/analysis_blocks/__init__.py +11 -0
  9. multi_agent_brief/analysis_blocks/builder.py +206 -0
  10. multi_agent_brief/analysis_blocks/renderer.py +237 -0
  11. multi_agent_brief/analysis_blocks/schemas.py +52 -0
  12. multi_agent_brief/analysis_modules/__init__.py +8 -0
  13. multi_agent_brief/analysis_modules/base.py +87 -0
  14. multi_agent_brief/analysis_modules/market_competitor/__init__.py +68 -0
  15. multi_agent_brief/analysis_modules/market_competitor/auditor.py +290 -0
  16. multi_agent_brief/analysis_modules/market_competitor/config.py +187 -0
  17. multi_agent_brief/analysis_modules/market_competitor/event_builder.py +226 -0
  18. multi_agent_brief/analysis_modules/market_competitor/renderer.py +199 -0
  19. multi_agent_brief/analysis_modules/market_competitor/schemas.py +518 -0
  20. multi_agent_brief/analysis_modules/policy_regulatory/__init__.py +7 -0
  21. multi_agent_brief/analysis_modules/policy_regulatory/audit.py +195 -0
  22. multi_agent_brief/analysis_modules/policy_regulatory/module.py +387 -0
  23. multi_agent_brief/analysis_modules/policy_regulatory/schemas.py +129 -0
  24. multi_agent_brief/analysis_modules/registry.py +73 -0
  25. multi_agent_brief/audience/__init__.py +19 -0
  26. multi_agent_brief/audience/profiles.py +246 -0
  27. multi_agent_brief/audience_memory/__init__.py +23 -0
  28. multi_agent_brief/audience_memory/profile.py +358 -0
  29. multi_agent_brief/audit/__init__.py +36 -0
  30. multi_agent_brief/audit/case_applicability.py +181 -0
  31. multi_agent_brief/audit/deterministic.py +471 -0
  32. multi_agent_brief/audit/editorial_governance.py +404 -0
  33. multi_agent_brief/audit/final_quality.py +764 -0
  34. multi_agent_brief/audit/harness.py +242 -0
  35. multi_agent_brief/audit/interfaces.py +96 -0
  36. multi_agent_brief/audit/limitation_hygiene.py +238 -0
  37. multi_agent_brief/audit/proposal_boundary.py +34 -0
  38. multi_agent_brief/audit/redaction.py +27 -0
  39. multi_agent_brief/audit/rule_packs.py +96 -0
  40. multi_agent_brief/audit/semantic.py +435 -0
  41. multi_agent_brief/capabilities/__init__.py +22 -0
  42. multi_agent_brief/capabilities/catalog.py +215 -0
  43. multi_agent_brief/capabilities/detect.py +199 -0
  44. multi_agent_brief/capabilities/models.py +60 -0
  45. multi_agent_brief/capabilities/recommend.py +206 -0
  46. multi_agent_brief/cli/__init__.py +2 -0
  47. multi_agent_brief/cli/analysis_commands.py +140 -0
  48. multi_agent_brief/cli/approval_commands.py +107 -0
  49. multi_agent_brief/cli/audit_commands.py +59 -0
  50. multi_agent_brief/cli/capability_commands.py +548 -0
  51. multi_agent_brief/cli/claude_commands.py +159 -0
  52. multi_agent_brief/cli/competitors_commands.py +182 -0
  53. multi_agent_brief/cli/controls_commands.py +137 -0
  54. multi_agent_brief/cli/deliver_commands.py +942 -0
  55. multi_agent_brief/cli/eval_cases_commands.py +99 -0
  56. multi_agent_brief/cli/experiments_commands.py +395 -0
  57. multi_agent_brief/cli/feedback_commands.py +192 -0
  58. multi_agent_brief/cli/finalize_commands.py +153 -0
  59. multi_agent_brief/cli/gates_commands.py +174 -0
  60. multi_agent_brief/cli/hermes_commands.py +356 -0
  61. multi_agent_brief/cli/improve_commands.py +224 -0
  62. multi_agent_brief/cli/init_commands.py +564 -0
  63. multi_agent_brief/cli/init_wizard.py +1473 -0
  64. multi_agent_brief/cli/input_commands.py +237 -0
  65. multi_agent_brief/cli/main.py +288 -0
  66. multi_agent_brief/cli/onboard_commands.py +193 -0
  67. multi_agent_brief/cli/product_commands.py +1449 -0
  68. multi_agent_brief/cli/provenance_commands.py +100 -0
  69. multi_agent_brief/cli/release_commands.py +68 -0
  70. multi_agent_brief/cli/repair_commands.py +169 -0
  71. multi_agent_brief/cli/run_commands.py +292 -0
  72. multi_agent_brief/cli/runtime_commands.py +81 -0
  73. multi_agent_brief/cli/secrets_commands.py +232 -0
  74. multi_agent_brief/cli/semantic_support_commands.py +80 -0
  75. multi_agent_brief/cli/sources_commands.py +647 -0
  76. multi_agent_brief/cli/start_commands.py +8 -0
  77. multi_agent_brief/cli/state_commands.py +446 -0
  78. multi_agent_brief/cli/status_commands.py +26 -0
  79. multi_agent_brief/cli/workbuddy_commands.py +103 -0
  80. multi_agent_brief/configs/artifact_contracts.yaml +514 -0
  81. multi_agent_brief/configs/orchestrator_contract.yaml +181 -0
  82. multi_agent_brief/configs/policy_packs/default.yaml +65 -0
  83. multi_agent_brief/configs/policy_profiles/evidence_extract_default.yaml +58 -0
  84. multi_agent_brief/configs/policy_profiles/finance_default.yaml +44 -0
  85. multi_agent_brief/configs/policy_profiles/internet_default.yaml +44 -0
  86. multi_agent_brief/configs/policy_profiles/manufacturing_default.yaml +33 -0
  87. multi_agent_brief/configs/policy_profiles/solar_manufacturing_default.yaml +64 -0
  88. multi_agent_brief/configs/report_packs/evidence_extract.yaml +48 -0
  89. multi_agent_brief/configs/report_packs/management_monthly.yaml +36 -0
  90. multi_agent_brief/configs/report_packs/market_weekly.yaml +36 -0
  91. multi_agent_brief/configs/report_packs/solar_industry_periodic.yaml +50 -0
  92. multi_agent_brief/configs/report_templates/evidence_extract.yaml +55 -0
  93. multi_agent_brief/configs/report_templates/management_monthly.yaml +48 -0
  94. multi_agent_brief/configs/report_templates/market_weekly.yaml +49 -0
  95. multi_agent_brief/configs/report_templates/solar_industry_periodic.yaml +75 -0
  96. multi_agent_brief/configs/stage_specs.yaml +180 -0
  97. multi_agent_brief/contracts/__init__.py +41 -0
  98. multi_agent_brief/contracts/base.py +99 -0
  99. multi_agent_brief/contracts/errors.py +41 -0
  100. multi_agent_brief/contracts/migrations/__init__.py +5 -0
  101. multi_agent_brief/contracts/migrations/claim_v1_to_v2.py +33 -0
  102. multi_agent_brief/contracts/registry.py +159 -0
  103. multi_agent_brief/contracts/role_topology.py +25 -0
  104. multi_agent_brief/contracts/schemas/__init__.py +35 -0
  105. multi_agent_brief/contracts/schemas/analysis_pack.py +135 -0
  106. multi_agent_brief/contracts/schemas/atomic_claim_graph.py +304 -0
  107. multi_agent_brief/contracts/schemas/audit_report.py +80 -0
  108. multi_agent_brief/contracts/schemas/candidate_item.py +51 -0
  109. multi_agent_brief/contracts/schemas/claim.py +197 -0
  110. multi_agent_brief/contracts/schemas/claim_draft.py +386 -0
  111. multi_agent_brief/contracts/schemas/claim_support_matrix.py +334 -0
  112. multi_agent_brief/contracts/schemas/evidence_span_registry.py +270 -0
  113. multi_agent_brief/contracts/schemas/policy_profile.py +247 -0
  114. multi_agent_brief/contracts/schemas/report_spec.py +257 -0
  115. multi_agent_brief/contracts/schemas/semantic_assessment_report.py +480 -0
  116. multi_agent_brief/contracts/schemas/source_evidence_pack_manifest.py +233 -0
  117. multi_agent_brief/contracts/schemas/source_item.py +96 -0
  118. multi_agent_brief/contracts/semantic_assessment_status.py +12 -0
  119. multi_agent_brief/contracts/source_metadata.py +252 -0
  120. multi_agent_brief/contracts/target_contract.py +460 -0
  121. multi_agent_brief/contracts/validator.py +225 -0
  122. multi_agent_brief/controls/__init__.py +23 -0
  123. multi_agent_brief/controls/contract.py +106 -0
  124. multi_agent_brief/controls/switchboard.py +1076 -0
  125. multi_agent_brief/core/__init__.py +2 -0
  126. multi_agent_brief/core/citations.py +14 -0
  127. multi_agent_brief/core/claim_ledger.py +94 -0
  128. multi_agent_brief/core/config.py +191 -0
  129. multi_agent_brief/core/env.py +69 -0
  130. multi_agent_brief/core/previous.py +83 -0
  131. multi_agent_brief/core/schemas.py +181 -0
  132. multi_agent_brief/core/selection.py +189 -0
  133. multi_agent_brief/delivery/__init__.py +6 -0
  134. multi_agent_brief/delivery/base.py +36 -0
  135. multi_agent_brief/delivery/feishu.py +204 -0
  136. multi_agent_brief/delivery/gws.py +237 -0
  137. multi_agent_brief/evaluation_cases/__init__.py +15 -0
  138. multi_agent_brief/evaluation_cases/contract.py +429 -0
  139. multi_agent_brief/evaluation_cases/fixtures/cases/approved_guidance_materialized/workspace/config.yaml +18 -0
  140. multi_agent_brief/evaluation_cases/fixtures/cases/approved_guidance_materialized/workspace/improvement/ledger.jsonl +2 -0
  141. multi_agent_brief/evaluation_cases/fixtures/cases/approved_guidance_materialized/workspace/sources.yaml +2 -0
  142. multi_agent_brief/evaluation_cases/fixtures/cases/approved_guidance_materialized/workspace/user.md +4 -0
  143. multi_agent_brief/evaluation_cases/fixtures/cases/company_event_missing_latest_official_check/workspace/config.yaml +13 -0
  144. multi_agent_brief/evaluation_cases/fixtures/cases/company_event_missing_latest_official_check/workspace/sources.yaml +9 -0
  145. multi_agent_brief/evaluation_cases/fixtures/cases/company_event_missing_latest_official_check/workspace/user.md +4 -0
  146. multi_agent_brief/evaluation_cases/fixtures/cases/control_switchboard_selection_is_not_execution/workspace/config.yaml +12 -0
  147. multi_agent_brief/evaluation_cases/fixtures/cases/control_switchboard_selection_is_not_execution/workspace/sources.yaml +6 -0
  148. multi_agent_brief/evaluation_cases/fixtures/cases/control_switchboard_selection_is_not_execution/workspace/user.md +4 -0
  149. multi_agent_brief/evaluation_cases/fixtures/cases/feedback_triage_required/workspace/config.yaml +6 -0
  150. multi_agent_brief/evaluation_cases/fixtures/cases/feedback_triage_required/workspace/input/human_feedback.md +1 -0
  151. multi_agent_brief/evaluation_cases/fixtures/cases/feedback_triage_required/workspace/sources.yaml +2 -0
  152. multi_agent_brief/evaluation_cases/fixtures/cases/feedback_triage_required/workspace/user.md +3 -0
  153. multi_agent_brief/evaluation_cases/fixtures/cases/final_abstract_quality_warning_surface/workspace/config.yaml +8 -0
  154. multi_agent_brief/evaluation_cases/fixtures/cases/final_abstract_quality_warning_surface/workspace/output/brief.md +14 -0
  155. multi_agent_brief/evaluation_cases/fixtures/cases/final_abstract_quality_warning_surface/workspace/output/intermediate/audit_report.json +1 -0
  156. multi_agent_brief/evaluation_cases/fixtures/cases/final_abstract_quality_warning_surface/workspace/output/intermediate/audited_brief.md +5 -0
  157. multi_agent_brief/evaluation_cases/fixtures/cases/final_abstract_quality_warning_surface/workspace/output/intermediate/candidate_claims.json +1 -0
  158. multi_agent_brief/evaluation_cases/fixtures/cases/final_abstract_quality_warning_surface/workspace/output/intermediate/claim_ledger.json +1 -0
  159. multi_agent_brief/evaluation_cases/fixtures/cases/final_abstract_quality_warning_surface/workspace/output/intermediate/screened_candidates.json +1 -0
  160. multi_agent_brief/evaluation_cases/fixtures/cases/final_abstract_quality_warning_surface/workspace/sources.yaml +2 -0
  161. multi_agent_brief/evaluation_cases/fixtures/cases/final_abstract_quality_warning_surface/workspace/user.md +3 -0
  162. multi_agent_brief/evaluation_cases/fixtures/cases/formal_release_missing_human_approval/workspace/config.yaml +13 -0
  163. multi_agent_brief/evaluation_cases/fixtures/cases/formal_release_missing_human_approval/workspace/sources.yaml +9 -0
  164. multi_agent_brief/evaluation_cases/fixtures/cases/formal_release_missing_human_approval/workspace/user.md +4 -0
  165. multi_agent_brief/evaluation_cases/fixtures/cases/guidance_manifestation_not_observable/workspace/config.yaml +4 -0
  166. multi_agent_brief/evaluation_cases/fixtures/cases/guidance_manifestation_not_observable/workspace/sources.yaml +2 -0
  167. multi_agent_brief/evaluation_cases/fixtures/cases/guidance_manifestation_not_observable/workspace/user.md +3 -0
  168. multi_agent_brief/evaluation_cases/fixtures/cases/media_only_legal_policy_blocks_research_review/workspace/config.yaml +13 -0
  169. multi_agent_brief/evaluation_cases/fixtures/cases/media_only_legal_policy_blocks_research_review/workspace/sources.yaml +9 -0
  170. multi_agent_brief/evaluation_cases/fixtures/cases/media_only_legal_policy_blocks_research_review/workspace/user.md +4 -0
  171. multi_agent_brief/evaluation_cases/fixtures/cases/mixed_metric_scope_support_blocker/workspace/config.yaml +13 -0
  172. multi_agent_brief/evaluation_cases/fixtures/cases/mixed_metric_scope_support_blocker/workspace/sources.yaml +9 -0
  173. multi_agent_brief/evaluation_cases/fixtures/cases/mixed_metric_scope_support_blocker/workspace/user.md +5 -0
  174. multi_agent_brief/evaluation_cases/fixtures/cases/planned_blocking_issue_cannot_continue/workspace/config.yaml +6 -0
  175. multi_agent_brief/evaluation_cases/fixtures/cases/planned_blocking_issue_cannot_continue/workspace/output/intermediate/audited_brief.md +3 -0
  176. multi_agent_brief/evaluation_cases/fixtures/cases/planned_blocking_issue_cannot_continue/workspace/output/intermediate/candidate_claims.json +1 -0
  177. multi_agent_brief/evaluation_cases/fixtures/cases/planned_blocking_issue_cannot_continue/workspace/output/intermediate/claim_ledger.json +1 -0
  178. multi_agent_brief/evaluation_cases/fixtures/cases/planned_blocking_issue_cannot_continue/workspace/output/intermediate/feedback_issues.json +25 -0
  179. multi_agent_brief/evaluation_cases/fixtures/cases/planned_blocking_issue_cannot_continue/workspace/output/intermediate/repair_plan.json +27 -0
  180. multi_agent_brief/evaluation_cases/fixtures/cases/planned_blocking_issue_cannot_continue/workspace/output/intermediate/screened_candidates.json +1 -0
  181. multi_agent_brief/evaluation_cases/fixtures/cases/planned_blocking_issue_cannot_continue/workspace/sources.yaml +2 -0
  182. multi_agent_brief/evaluation_cases/fixtures/cases/planned_blocking_issue_cannot_continue/workspace/user.md +3 -0
  183. multi_agent_brief/evaluation_cases/fixtures/cases/provenance_projection_minimal/workspace/config.yaml +8 -0
  184. multi_agent_brief/evaluation_cases/fixtures/cases/provenance_projection_minimal/workspace/output/intermediate/audit_report.json +1 -0
  185. multi_agent_brief/evaluation_cases/fixtures/cases/provenance_projection_minimal/workspace/output/intermediate/audited_brief.md +3 -0
  186. multi_agent_brief/evaluation_cases/fixtures/cases/provenance_projection_minimal/workspace/output/intermediate/candidate_claims.json +1 -0
  187. multi_agent_brief/evaluation_cases/fixtures/cases/provenance_projection_minimal/workspace/output/intermediate/claim_ledger.json +11 -0
  188. multi_agent_brief/evaluation_cases/fixtures/cases/provenance_projection_minimal/workspace/output/intermediate/quality_gate_report.json +22 -0
  189. multi_agent_brief/evaluation_cases/fixtures/cases/provenance_projection_minimal/workspace/output/intermediate/screened_candidates.json +1 -0
  190. multi_agent_brief/evaluation_cases/fixtures/cases/provenance_projection_minimal/workspace/sources.yaml +2 -0
  191. multi_agent_brief/evaluation_cases/fixtures/cases/provenance_projection_minimal/workspace/user.md +3 -0
  192. multi_agent_brief/evaluation_cases/fixtures/cases/reader_facing_source_appendix/workspace/config.yaml +13 -0
  193. multi_agent_brief/evaluation_cases/fixtures/cases/reader_facing_source_appendix/workspace/output/intermediate/audit_report.json +1 -0
  194. multi_agent_brief/evaluation_cases/fixtures/cases/reader_facing_source_appendix/workspace/output/intermediate/audited_brief.md +5 -0
  195. multi_agent_brief/evaluation_cases/fixtures/cases/reader_facing_source_appendix/workspace/output/intermediate/candidate_claims.json +1 -0
  196. multi_agent_brief/evaluation_cases/fixtures/cases/reader_facing_source_appendix/workspace/output/intermediate/claim_ledger.json +40 -0
  197. multi_agent_brief/evaluation_cases/fixtures/cases/reader_facing_source_appendix/workspace/output/intermediate/screened_candidates.json +1 -0
  198. multi_agent_brief/evaluation_cases/fixtures/cases/reader_facing_source_appendix/workspace/sources.yaml +3 -0
  199. multi_agent_brief/evaluation_cases/fixtures/cases/reader_facing_source_appendix/workspace/user.md +3 -0
  200. multi_agent_brief/evaluation_cases/fixtures/cases/reader_facing_target_relevance/workspace/config.yaml +8 -0
  201. multi_agent_brief/evaluation_cases/fixtures/cases/reader_facing_target_relevance/workspace/output/brief.md +3 -0
  202. multi_agent_brief/evaluation_cases/fixtures/cases/reader_facing_target_relevance/workspace/output/intermediate/audit_report.json +1 -0
  203. multi_agent_brief/evaluation_cases/fixtures/cases/reader_facing_target_relevance/workspace/output/intermediate/audited_brief.md +3 -0
  204. multi_agent_brief/evaluation_cases/fixtures/cases/reader_facing_target_relevance/workspace/output/intermediate/candidate_claims.json +1 -0
  205. multi_agent_brief/evaluation_cases/fixtures/cases/reader_facing_target_relevance/workspace/output/intermediate/claim_ledger.json +13 -0
  206. multi_agent_brief/evaluation_cases/fixtures/cases/reader_facing_target_relevance/workspace/output/intermediate/screened_candidates.json +1 -0
  207. multi_agent_brief/evaluation_cases/fixtures/cases/reader_facing_target_relevance/workspace/sources.yaml +2 -0
  208. multi_agent_brief/evaluation_cases/fixtures/cases/reader_facing_target_relevance/workspace/user.md +3 -0
  209. multi_agent_brief/evaluation_cases/fixtures/cases/release_readiness_forged_event_blocker/workspace/config.yaml +13 -0
  210. multi_agent_brief/evaluation_cases/fixtures/cases/release_readiness_forged_event_blocker/workspace/output/intermediate/release_readiness_report.json +31 -0
  211. multi_agent_brief/evaluation_cases/fixtures/cases/release_readiness_forged_event_blocker/workspace/sources.yaml +9 -0
  212. multi_agent_brief/evaluation_cases/fixtures/cases/release_readiness_forged_event_blocker/workspace/user.md +4 -0
  213. multi_agent_brief/evaluation_cases/fixtures/cases/reverted_entry_removed_from_next_snapshot/workspace/config.yaml +18 -0
  214. multi_agent_brief/evaluation_cases/fixtures/cases/reverted_entry_removed_from_next_snapshot/workspace/improvement/ledger.jsonl +3 -0
  215. multi_agent_brief/evaluation_cases/fixtures/cases/reverted_entry_removed_from_next_snapshot/workspace/improvement/memory.md +3 -0
  216. multi_agent_brief/evaluation_cases/fixtures/cases/reverted_entry_removed_from_next_snapshot/workspace/output/intermediate/improvement_memory_snapshot.md +3 -0
  217. multi_agent_brief/evaluation_cases/fixtures/cases/reverted_entry_removed_from_next_snapshot/workspace/sources.yaml +2 -0
  218. multi_agent_brief/evaluation_cases/fixtures/cases/reverted_entry_removed_from_next_snapshot/workspace/user.md +4 -0
  219. multi_agent_brief/evaluation_cases/fixtures/cases/same_evidence_reader_quality_regression/workspace/config.yaml +12 -0
  220. multi_agent_brief/evaluation_cases/fixtures/cases/same_evidence_reader_quality_regression/workspace/input/sources/source-001.txt +1 -0
  221. multi_agent_brief/evaluation_cases/fixtures/cases/same_evidence_reader_quality_regression/workspace/output/brief.md +37 -0
  222. multi_agent_brief/evaluation_cases/fixtures/cases/same_evidence_reader_quality_regression/workspace/output/delivery/brief.md +37 -0
  223. multi_agent_brief/evaluation_cases/fixtures/cases/same_evidence_reader_quality_regression/workspace/output/intermediate/atomic_claim_graph.json +17 -0
  224. multi_agent_brief/evaluation_cases/fixtures/cases/same_evidence_reader_quality_regression/workspace/output/intermediate/audit_report.json +5 -0
  225. multi_agent_brief/evaluation_cases/fixtures/cases/same_evidence_reader_quality_regression/workspace/output/intermediate/audited_brief.md +37 -0
  226. multi_agent_brief/evaluation_cases/fixtures/cases/same_evidence_reader_quality_regression/workspace/output/intermediate/claim_ledger.json +20 -0
  227. multi_agent_brief/evaluation_cases/fixtures/cases/same_evidence_reader_quality_regression/workspace/output/intermediate/evidence_span_registry.json +20 -0
  228. multi_agent_brief/evaluation_cases/fixtures/cases/same_evidence_reader_quality_regression/workspace/output/intermediate/finalize_report.json +40 -0
  229. multi_agent_brief/evaluation_cases/fixtures/cases/same_evidence_reader_quality_regression/workspace/output/intermediate/gates/auditor_quality_gate_report.json +42 -0
  230. multi_agent_brief/evaluation_cases/fixtures/cases/same_evidence_reader_quality_regression/workspace/output/intermediate/gates/finalize_quality_gate_report.json +42 -0
  231. multi_agent_brief/evaluation_cases/fixtures/cases/same_evidence_reader_quality_regression/workspace/output/intermediate/screened_candidates.json +33 -0
  232. multi_agent_brief/evaluation_cases/fixtures/cases/same_evidence_reader_quality_regression/workspace/output/source_appendix.md +12 -0
  233. multi_agent_brief/evaluation_cases/fixtures/cases/same_evidence_reader_quality_regression/workspace/output/source_appendix_trace.md +10 -0
  234. multi_agent_brief/evaluation_cases/fixtures/cases/same_evidence_reader_quality_regression/workspace/report_spec.yaml +24 -0
  235. multi_agent_brief/evaluation_cases/fixtures/cases/same_evidence_reader_quality_regression/workspace/sources.yaml +4 -0
  236. multi_agent_brief/evaluation_cases/fixtures/cases/same_evidence_reader_quality_regression/workspace/user.md +3 -0
  237. multi_agent_brief/evaluation_cases/fixtures/cases/source_evidence_pack_blocks_non_evidence_file/workspace/config.yaml +13 -0
  238. multi_agent_brief/evaluation_cases/fixtures/cases/source_evidence_pack_blocks_non_evidence_file/workspace/input/sources/README.md +4 -0
  239. multi_agent_brief/evaluation_cases/fixtures/cases/source_evidence_pack_blocks_non_evidence_file/workspace/output/intermediate/source_evidence_pack_manifest.json +26 -0
  240. multi_agent_brief/evaluation_cases/fixtures/cases/source_evidence_pack_blocks_non_evidence_file/workspace/sources.yaml +9 -0
  241. multi_agent_brief/evaluation_cases/fixtures/cases/source_evidence_pack_blocks_non_evidence_file/workspace/user.md +4 -0
  242. multi_agent_brief/evaluation_cases/fixtures/cases/stale_current_claim/workspace/config.yaml +9 -0
  243. multi_agent_brief/evaluation_cases/fixtures/cases/stale_current_claim/workspace/output/intermediate/audit_report.json +1 -0
  244. multi_agent_brief/evaluation_cases/fixtures/cases/stale_current_claim/workspace/output/intermediate/audited_brief.md +3 -0
  245. multi_agent_brief/evaluation_cases/fixtures/cases/stale_current_claim/workspace/output/intermediate/candidate_claims.json +1 -0
  246. multi_agent_brief/evaluation_cases/fixtures/cases/stale_current_claim/workspace/output/intermediate/claim_ledger.json +13 -0
  247. multi_agent_brief/evaluation_cases/fixtures/cases/stale_current_claim/workspace/output/intermediate/screened_candidates.json +1 -0
  248. multi_agent_brief/evaluation_cases/fixtures/cases/stale_current_claim/workspace/sources.yaml +2 -0
  249. multi_agent_brief/evaluation_cases/fixtures/cases/stale_current_claim/workspace/user.md +3 -0
  250. multi_agent_brief/evaluation_cases/fixtures/cases/third_party_price_snapshot_formal_block/workspace/config.yaml +13 -0
  251. multi_agent_brief/evaluation_cases/fixtures/cases/third_party_price_snapshot_formal_block/workspace/sources.yaml +9 -0
  252. multi_agent_brief/evaluation_cases/fixtures/cases/third_party_price_snapshot_formal_block/workspace/user.md +4 -0
  253. multi_agent_brief/evaluation_cases/fixtures/cases/trajectory_retry_budget_exhausted/workspace/config.yaml +4 -0
  254. multi_agent_brief/evaluation_cases/fixtures/cases/trajectory_retry_budget_exhausted/workspace/sources.yaml +2 -0
  255. multi_agent_brief/evaluation_cases/fixtures/cases/trajectory_retry_budget_exhausted/workspace/user.md +3 -0
  256. multi_agent_brief/evaluation_cases/fixtures/cases/unapproved_entry_not_materialized/workspace/config.yaml +18 -0
  257. multi_agent_brief/evaluation_cases/fixtures/cases/unapproved_entry_not_materialized/workspace/improvement/ledger.jsonl +1 -0
  258. multi_agent_brief/evaluation_cases/fixtures/cases/unapproved_entry_not_materialized/workspace/sources.yaml +2 -0
  259. multi_agent_brief/evaluation_cases/fixtures/cases/unapproved_entry_not_materialized/workspace/user.md +4 -0
  260. multi_agent_brief/evaluation_cases/fixtures/cases/unauthorized_institution_branding_blocks_release/workspace/config.yaml +18 -0
  261. multi_agent_brief/evaluation_cases/fixtures/cases/unauthorized_institution_branding_blocks_release/workspace/sources.yaml +9 -0
  262. multi_agent_brief/evaluation_cases/fixtures/cases/unauthorized_institution_branding_blocks_release/workspace/user.md +5 -0
  263. multi_agent_brief/evaluation_cases/fixtures/cases/unsupported_material_fact/workspace/config.yaml +8 -0
  264. multi_agent_brief/evaluation_cases/fixtures/cases/unsupported_material_fact/workspace/output/intermediate/audit_report.json +1 -0
  265. multi_agent_brief/evaluation_cases/fixtures/cases/unsupported_material_fact/workspace/output/intermediate/audited_brief.md +8 -0
  266. multi_agent_brief/evaluation_cases/fixtures/cases/unsupported_material_fact/workspace/output/intermediate/candidate_claims.json +1 -0
  267. multi_agent_brief/evaluation_cases/fixtures/cases/unsupported_material_fact/workspace/output/intermediate/claim_ledger.json +1 -0
  268. multi_agent_brief/evaluation_cases/fixtures/cases/unsupported_material_fact/workspace/output/intermediate/screened_candidates.json +1 -0
  269. multi_agent_brief/evaluation_cases/fixtures/cases/unsupported_material_fact/workspace/sources.yaml +2 -0
  270. multi_agent_brief/evaluation_cases/fixtures/cases/unsupported_material_fact/workspace/user.md +3 -0
  271. multi_agent_brief/evaluation_cases/fixtures/manifest.yaml +861 -0
  272. multi_agent_brief/evaluation_cases/fixtures.py +20 -0
  273. multi_agent_brief/evaluation_cases/runner.py +1603 -0
  274. multi_agent_brief/experiments/__init__.py +45 -0
  275. multi_agent_brief/experiments/experiment_080.py +5835 -0
  276. multi_agent_brief/experiments/schemas.py +63 -0
  277. multi_agent_brief/experiments/target_contract.py +10 -0
  278. multi_agent_brief/feedback/__init__.py +17 -0
  279. multi_agent_brief/feedback/feedback_contract.py +482 -0
  280. multi_agent_brief/feedback/feedback_state.py +898 -0
  281. multi_agent_brief/hermes/__init__.py +25 -0
  282. multi_agent_brief/hermes/adapter.py +832 -0
  283. multi_agent_brief/improvement/__init__.py +83 -0
  284. multi_agent_brief/improvement/contract.py +1114 -0
  285. multi_agent_brief/improvement/memory.py +451 -0
  286. multi_agent_brief/improvement/product_definition.py +228 -0
  287. multi_agent_brief/improvement/state.py +961 -0
  288. multi_agent_brief/inputs/__init__.py +2 -0
  289. multi_agent_brief/inputs/classifier.py +322 -0
  290. multi_agent_brief/inputs/contracts.py +59 -0
  291. multi_agent_brief/inputs/extractor.py +310 -0
  292. multi_agent_brief/install/__init__.py +2 -0
  293. multi_agent_brief/install/writer.py +97 -0
  294. multi_agent_brief/onboarding/__init__.py +11 -0
  295. multi_agent_brief/onboarding/io.py +103 -0
  296. multi_agent_brief/onboarding/mapper.py +484 -0
  297. multi_agent_brief/onboarding/schema.py +46 -0
  298. multi_agent_brief/orchestrator/__init__.py +2 -0
  299. multi_agent_brief/orchestrator/fact_layer_import.py +352 -0
  300. multi_agent_brief/orchestrator/handoff.py +2209 -0
  301. multi_agent_brief/orchestrator/role_topology.py +42 -0
  302. multi_agent_brief/orchestrator/run_archive.py +888 -0
  303. multi_agent_brief/orchestrator/run_integrity.py +346 -0
  304. multi_agent_brief/orchestrator/runtime_state/__init__.py +70 -0
  305. multi_agent_brief/orchestrator/runtime_state/_io.py +167 -0
  306. multi_agent_brief/orchestrator/runtime_state/_transactions.py +298 -0
  307. multi_agent_brief/orchestrator/runtime_state/artifact_registry.py +1825 -0
  308. multi_agent_brief/orchestrator/runtime_state/atomic_claim_graph.py +96 -0
  309. multi_agent_brief/orchestrator/runtime_state/claim_ledger_freeze.py +510 -0
  310. multi_agent_brief/orchestrator/runtime_state/claim_metadata_enrichment.py +836 -0
  311. multi_agent_brief/orchestrator/runtime_state/claim_support_matrix.py +582 -0
  312. multi_agent_brief/orchestrator/runtime_state/completion_gates.py +672 -0
  313. multi_agent_brief/orchestrator/runtime_state/contracts_loader.py +66 -0
  314. multi_agent_brief/orchestrator/runtime_state/decisions.py +239 -0
  315. multi_agent_brief/orchestrator/runtime_state/errors.py +61 -0
  316. multi_agent_brief/orchestrator/runtime_state/event_log.py +256 -0
  317. multi_agent_brief/orchestrator/runtime_state/evidence_span_registry.py +233 -0
  318. multi_agent_brief/orchestrator/runtime_state/fact_layer.py +755 -0
  319. multi_agent_brief/orchestrator/runtime_state/identity.py +90 -0
  320. multi_agent_brief/orchestrator/runtime_state/lifecycle.py +675 -0
  321. multi_agent_brief/orchestrator/runtime_state/manifest.py +82 -0
  322. multi_agent_brief/orchestrator/runtime_state/operations.py +224 -0
  323. multi_agent_brief/orchestrator/runtime_state/paths.py +38 -0
  324. multi_agent_brief/orchestrator/runtime_state/repair.py +984 -0
  325. multi_agent_brief/orchestrator/runtime_state/safety_surfaces.py +147 -0
  326. multi_agent_brief/orchestrator/runtime_state/semantic_assessment_report.py +692 -0
  327. multi_agent_brief/orchestrator/runtime_state/semantic_support_acceptance.py +683 -0
  328. multi_agent_brief/orchestrator/runtime_state/source_evidence_pack.py +131 -0
  329. multi_agent_brief/orchestrator/runtime_state/stage_completion.py +1320 -0
  330. multi_agent_brief/orchestrator/runtime_state/trajectory.py +200 -0
  331. multi_agent_brief/orchestrator/runtime_state/workflow.py +350 -0
  332. multi_agent_brief/orchestrator/source_evidence.py +43 -0
  333. multi_agent_brief/orchestrator/timing.py +410 -0
  334. multi_agent_brief/orchestrator_contract.py +96 -0
  335. multi_agent_brief/outputs/__init__.py +2 -0
  336. multi_agent_brief/outputs/atomic_reader_projection.py +288 -0
  337. multi_agent_brief/outputs/docx.py +32 -0
  338. multi_agent_brief/outputs/finalize.py +1036 -0
  339. multi_agent_brief/outputs/ib_docx.py +983 -0
  340. multi_agent_brief/outputs/naming.py +38 -0
  341. multi_agent_brief/outputs/pdf.py +20 -0
  342. multi_agent_brief/outputs/reader_final_gate.py +509 -0
  343. multi_agent_brief/outputs/reader_projection.py +397 -0
  344. multi_agent_brief/outputs/source_appendix.py +753 -0
  345. multi_agent_brief/outputs/templates/__init__.py +112 -0
  346. multi_agent_brief/product/__init__.py +49 -0
  347. multi_agent_brief/product/bundle_projection.py +686 -0
  348. multi_agent_brief/product/citation_profile.py +145 -0
  349. multi_agent_brief/product/guidance_manifestation.py +421 -0
  350. multi_agent_brief/product/materiality_selection.py +472 -0
  351. multi_agent_brief/product/policy_gate_adapter.py +116 -0
  352. multi_agent_brief/product/policy_profile.py +39 -0
  353. multi_agent_brief/product/policy_projection.py +161 -0
  354. multi_agent_brief/product/policy_registry.py +83 -0
  355. multi_agent_brief/product/policy_resolver.py +225 -0
  356. multi_agent_brief/product/quality_closeout.py +188 -0
  357. multi_agent_brief/product/quality_panel.py +2217 -0
  358. multi_agent_brief/product/release_approval.py +1034 -0
  359. multi_agent_brief/product/report_pack.py +130 -0
  360. multi_agent_brief/product/report_pack_aliases.py +68 -0
  361. multi_agent_brief/product/report_registry.py +101 -0
  362. multi_agent_brief/product/report_spec.py +181 -0
  363. multi_agent_brief/product/support_wording.py +525 -0
  364. multi_agent_brief/product/template_conformance.py +516 -0
  365. multi_agent_brief/product/template_projection.py +123 -0
  366. multi_agent_brief/product/template_registry.py +244 -0
  367. multi_agent_brief/product/template_render_plan.py +315 -0
  368. multi_agent_brief/product/template_renderer.py +224 -0
  369. multi_agent_brief/product/trajectory_regulation.py +441 -0
  370. multi_agent_brief/provenance/__init__.py +5 -0
  371. multi_agent_brief/provenance/builder.py +841 -0
  372. multi_agent_brief/provenance/contract.py +21 -0
  373. multi_agent_brief/provenance/io.py +144 -0
  374. multi_agent_brief/provenance/model.py +110 -0
  375. multi_agent_brief/provenance/references.py +43 -0
  376. multi_agent_brief/provenance/validator.py +135 -0
  377. multi_agent_brief/quality_gates/__init__.py +19 -0
  378. multi_agent_brief/quality_gates/contract.py +581 -0
  379. multi_agent_brief/quality_gates/state.py +2498 -0
  380. multi_agent_brief/repair/__init__.py +5 -0
  381. multi_agent_brief/repair/router.py +842 -0
  382. multi_agent_brief/runtime_assets.py +431 -0
  383. multi_agent_brief/sources/__init__.py +16 -0
  384. multi_agent_brief/sources/api_filings.py +236 -0
  385. multi_agent_brief/sources/api_news.py +174 -0
  386. multi_agent_brief/sources/base.py +142 -0
  387. multi_agent_brief/sources/cached_package.py +119 -0
  388. multi_agent_brief/sources/cli_provider.py +263 -0
  389. multi_agent_brief/sources/coverage.py +336 -0
  390. multi_agent_brief/sources/decider.py +756 -0
  391. multi_agent_brief/sources/doctor.py +373 -0
  392. multi_agent_brief/sources/evidence_pack.py +364 -0
  393. multi_agent_brief/sources/feishu_provider.py +326 -0
  394. multi_agent_brief/sources/filing_resolver.py +400 -0
  395. multi_agent_brief/sources/industry_packs.py +130 -0
  396. multi_agent_brief/sources/join.py +206 -0
  397. multi_agent_brief/sources/local_signal.py +81 -0
  398. multi_agent_brief/sources/local_signal_planner.py +636 -0
  399. multi_agent_brief/sources/manual.py +259 -0
  400. multi_agent_brief/sources/mcp_provider.py +309 -0
  401. multi_agent_brief/sources/mineru_provider.py +601 -0
  402. multi_agent_brief/sources/normalizer.py +95 -0
  403. multi_agent_brief/sources/opencli_provider.py +282 -0
  404. multi_agent_brief/sources/planner.py +178 -0
  405. multi_agent_brief/sources/registry.py +367 -0
  406. multi_agent_brief/sources/rss.py +190 -0
  407. multi_agent_brief/sources/search_backends/__init__.py +31 -0
  408. multi_agent_brief/sources/search_backends/base.py +51 -0
  409. multi_agent_brief/sources/search_backends/brave.py +192 -0
  410. multi_agent_brief/sources/search_backends/capabilities.py +94 -0
  411. multi_agent_brief/sources/search_backends/exa.py +180 -0
  412. multi_agent_brief/sources/search_backends/firecrawl.py +164 -0
  413. multi_agent_brief/sources/search_backends/serper.py +241 -0
  414. multi_agent_brief/sources/search_backends/tavily.py +124 -0
  415. multi_agent_brief/sources/sourcehub.py +505 -0
  416. multi_agent_brief/sources/web_search.py +267 -0
  417. multi_agent_brief/status.py +966 -0
  418. multi_agent_brief/tools/__init__.py +3 -0
  419. multi_agent_brief/tools/draft_cleanup.py +198 -0
  420. multi_agent_brief/workbuddy/__init__.py +1 -0
  421. multi_agent_brief/workbuddy/diagnose.py +569 -0
  422. multi_agent_brief/workbuddy/skill_pack.py +309 -0
  423. multi_agent_brief/workspace/__init__.py +1 -0
  424. multi_agent_brief/workspace/init_profile.py +45 -0
@@ -0,0 +1,1076 @@
1
+ """Build, record, and validate Orchestrator control switchboards."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import json
6
+ import hashlib
7
+ import os
8
+ import re
9
+ import uuid
10
+ from pathlib import Path
11
+ from typing import Any
12
+
13
+ import yaml
14
+
15
+ from multi_agent_brief.controls.contract import (
16
+ CONTROL_IDS,
17
+ CONTROL_SELECTIONS_SCHEMA,
18
+ CONTROL_SWITCHBOARD_SCHEMA,
19
+ EXECUTION_TYPES,
20
+ HUMAN_APPROVAL_CONTROLS,
21
+ RECOMMENDATIONS,
22
+ SELECTIONS,
23
+ ControlSwitchboardError,
24
+ control_switchboard_paths,
25
+ ensure_safe_relative_path,
26
+ )
27
+ from multi_agent_brief.orchestrator.runtime_state import (
28
+ RUNTIME_MANIFEST_SCHEMA,
29
+ RuntimeStateError,
30
+ append_event,
31
+ initialize_runtime_state,
32
+ runtime_state_paths,
33
+ utc_now,
34
+ )
35
+ from multi_agent_brief.orchestrator_contract import resolve_repo_workdir
36
+
37
+
38
+ TEXT_TRIGGERS = {
39
+ "executive": {"board", "management", "executive", "investor", "董事会", "管理层", "高管", "投关"},
40
+ "case": {"case", "comparable", "benchmark", "precedent", "lesson", "案例", "对标", "可比", "先例"},
41
+ "limitation": {"forecast", "hypothesis", "estimate", "analog", "uncertainty", "risk", "caveat", "预测", "假设", "估计", "类比", "不确定", "风险", "限制"},
42
+ "local_signal": {"local market", "local-language", "consumer sentiment", "social signal", "市场信号", "本地", "社媒", "舆情", "消费者"},
43
+ "pain_point": {"pain point", "complaint", "review mining", "customer feedback", "用户痛点", "消费者痛点", "投诉", "评价", "反馈"},
44
+ }
45
+
46
+
47
+ def build_control_switchboard(
48
+ *,
49
+ workspace: str | Path,
50
+ repo_workdir: str | Path | None = None,
51
+ actor: str = "cli",
52
+ ) -> dict[str, Any]:
53
+ """Build the deterministic switchboard and append a lifecycle event."""
54
+ ws = _require_workspace(workspace)
55
+ repo = resolve_repo_workdir(repo_workdir, workspace=ws)
56
+ state_paths = runtime_state_paths(ws)
57
+ existing_manifest = _read_json_object_if_exists(
58
+ state_paths["runtime_manifest"],
59
+ label="runtime_manifest.json",
60
+ )
61
+ if existing_manifest is not None and state_paths["workflow_state"].exists():
62
+ if existing_manifest.get("schema_version") != RUNTIME_MANIFEST_SCHEMA:
63
+ raise ControlSwitchboardError(
64
+ "Existing runtime_manifest.json has an unsupported schema.",
65
+ details={
66
+ "path": str(state_paths["runtime_manifest"]),
67
+ "schema_version": existing_manifest.get("schema_version"),
68
+ },
69
+ )
70
+ manifest = existing_manifest
71
+ else:
72
+ existing_runtime = (
73
+ str(existing_manifest.get("runtime") or "")
74
+ if isinstance(existing_manifest, dict)
75
+ else ""
76
+ )
77
+ state = initialize_runtime_state(
78
+ workspace=ws,
79
+ repo_workdir=repo,
80
+ runtime=existing_runtime or "controls",
81
+ actor=actor,
82
+ )
83
+ manifest = state.get("manifest") or {}
84
+ run_id = str(manifest.get("run_id") or "")
85
+ if not run_id:
86
+ raise ControlSwitchboardError(
87
+ "runtime_manifest.json run_id is required before building the control switchboard.",
88
+ details={"path": str(state_paths["runtime_manifest"])},
89
+ )
90
+ paths = control_switchboard_paths(ws)
91
+ now = utc_now()
92
+
93
+ context = _load_context(ws)
94
+ controls = _build_controls(ws, context)
95
+ payload = {
96
+ "schema_version": CONTROL_SWITCHBOARD_SCHEMA,
97
+ "run_id": run_id,
98
+ "workspace": ".",
99
+ "created_at": now,
100
+ "context_signature": _context_signature(ws, context=context),
101
+ "inputs": _switchboard_inputs(ws),
102
+ "controls": controls,
103
+ "warnings": context["warnings"],
104
+ }
105
+ errors = validate_switchboard_payload(payload)
106
+ if errors:
107
+ raise ControlSwitchboardError(
108
+ "Generated control switchboard is invalid.",
109
+ details={"errors": errors},
110
+ )
111
+
112
+ archived_selections = _archive_selections_for_other_run(
113
+ paths=paths,
114
+ current_run_id=run_id,
115
+ )
116
+ archived_stale_selections = _archive_selections_for_other_context(
117
+ paths=paths,
118
+ current_run_id=run_id,
119
+ current_context_signature=str(payload.get("context_signature") or ""),
120
+ )
121
+ _write_json_atomic(paths["orchestrator_control_switchboard"], payload)
122
+ append_event(
123
+ workspace=ws,
124
+ run_id=run_id,
125
+ event_type="control_switchboard_built",
126
+ actor=actor,
127
+ reason="Orchestrator control switchboard built.",
128
+ metadata={
129
+ "orchestrator_control_switchboard": "output/intermediate/orchestrator_control_switchboard.json",
130
+ "control_count": len(controls),
131
+ "required_count": sum(1 for item in controls if item.get("recommendation") == "required"),
132
+ "human_approval_count": sum(1 for item in controls if item.get("requires_human_approval")),
133
+ "archived_control_selections": archived_selections,
134
+ "archived_stale_control_selections": archived_stale_selections,
135
+ },
136
+ )
137
+ return _state_payload(ws, switchboard=payload)
138
+
139
+
140
+ def show_control_switchboard(*, workspace: str | Path) -> dict[str, Any]:
141
+ ws = _require_workspace(workspace)
142
+ paths = control_switchboard_paths(ws)
143
+ switchboard = _load_switchboard(paths=paths)
144
+ selections = _read_json_object_if_exists(
145
+ paths["control_selections"],
146
+ label="control_selections.json",
147
+ )
148
+ return _state_payload(ws, switchboard=switchboard, selections=selections)
149
+
150
+
151
+ def select_control(
152
+ *,
153
+ workspace: str | Path,
154
+ control_id: str,
155
+ selection: str,
156
+ reason: str,
157
+ approved_by_human: bool = False,
158
+ human_approval_ref: str | None = None,
159
+ actor: str = "orchestrator",
160
+ ) -> dict[str, Any]:
161
+ """Record an Orchestrator selection without executing the control."""
162
+ ws = _require_workspace(workspace)
163
+ if control_id not in CONTROL_IDS:
164
+ raise ControlSwitchboardError(
165
+ f"Unknown control id: {control_id}",
166
+ details={"control_id": control_id, "known_controls": sorted(CONTROL_IDS)},
167
+ )
168
+ if selection not in SELECTIONS:
169
+ raise ControlSwitchboardError(
170
+ f"Invalid control selection: {selection}",
171
+ details={"selection": selection, "allowed_selections": sorted(SELECTIONS)},
172
+ )
173
+ if not reason.strip():
174
+ raise ControlSwitchboardError("Control selection reason is required.")
175
+
176
+ paths = control_switchboard_paths(ws)
177
+ switchboard = _load_switchboard(paths=paths)
178
+ if switchboard is None:
179
+ raise ControlSwitchboardError(
180
+ "Control switchboard is missing. Run controls build-switchboard first.",
181
+ details={"path": str(paths["orchestrator_control_switchboard"])},
182
+ )
183
+ switchboard_errors = validate_switchboard_payload(switchboard)
184
+ switchboard_errors.extend(_switchboard_stale_reasons(ws, switchboard))
185
+ if switchboard_errors:
186
+ raise ControlSwitchboardError(
187
+ "Control switchboard is invalid.",
188
+ details={"errors": switchboard_errors},
189
+ )
190
+ control = _control_by_id(switchboard, control_id)
191
+ if control is None:
192
+ raise ControlSwitchboardError(
193
+ f"Control id is not present in switchboard: {control_id}",
194
+ details={"control_id": control_id},
195
+ )
196
+
197
+ run_id = str(switchboard.get("run_id") or _current_run_id(ws) or "")
198
+ now = utc_now()
199
+ existing = _read_json_object_if_exists(
200
+ paths["control_selections"],
201
+ label="control_selections.json",
202
+ )
203
+ switchboard_context_signature = str(switchboard.get("context_signature") or "")
204
+ archived_stale_selections = None
205
+ if existing is None:
206
+ payload = {
207
+ "schema_version": CONTROL_SELECTIONS_SCHEMA,
208
+ "run_id": run_id,
209
+ "switchboard_context_signature": switchboard_context_signature,
210
+ "created_at": now,
211
+ "updated_at": now,
212
+ "selections": [],
213
+ }
214
+ else:
215
+ payload = existing
216
+ if payload.get("run_id") != run_id:
217
+ raise ControlSwitchboardError(
218
+ "control_selections.json run_id does not match switchboard run_id.",
219
+ details={"switchboard_run_id": run_id, "selections_run_id": payload.get("run_id")},
220
+ )
221
+ if payload.get("switchboard_context_signature") != switchboard_context_signature:
222
+ archived_stale_selections = _archive_control_selections_path(
223
+ paths=paths,
224
+ existing=payload,
225
+ suffix="stale",
226
+ )
227
+ payload = {
228
+ "schema_version": CONTROL_SELECTIONS_SCHEMA,
229
+ "run_id": run_id,
230
+ "switchboard_context_signature": switchboard_context_signature,
231
+ "created_at": now,
232
+ "updated_at": now,
233
+ "selections": [],
234
+ }
235
+ else:
236
+ payload["updated_at"] = now
237
+
238
+ requires_human = bool(control.get("requires_human_approval"))
239
+ clean_human_approval_ref = human_approval_ref.strip() if human_approval_ref else None
240
+ if (
241
+ requires_human
242
+ and selection == "enable"
243
+ and approved_by_human
244
+ and not clean_human_approval_ref
245
+ ):
246
+ raise ControlSwitchboardError(
247
+ "Human approval reference is required when enabling a human-approval control.",
248
+ details={"control_id": control_id},
249
+ )
250
+ execution_ready = (
251
+ selection == "enable"
252
+ and (not requires_human or bool(approved_by_human))
253
+ )
254
+ entry = {
255
+ "selection_id": f"sel_{uuid.uuid4().hex[:12]}",
256
+ "control_id": control_id,
257
+ "selection": selection,
258
+ "selected_at": now,
259
+ "selected_by": actor,
260
+ "reason": reason.strip(),
261
+ "approved_by_human": bool(approved_by_human),
262
+ "human_approval_ref": clean_human_approval_ref,
263
+ "switchboard_context_signature": switchboard_context_signature,
264
+ "execution_ready": bool(execution_ready),
265
+ "executed": False,
266
+ "execution_ref": None,
267
+ "metadata": {},
268
+ }
269
+ selections = [item for item in payload.get("selections", []) if item.get("control_id") != control_id]
270
+ selections.append(entry)
271
+ payload["selections"] = selections
272
+
273
+ selection_errors = validate_selections_payload(payload, switchboard=switchboard, strict=False)
274
+ if selection_errors:
275
+ raise ControlSwitchboardError(
276
+ "Control selection payload is invalid.",
277
+ details={"errors": selection_errors},
278
+ )
279
+
280
+ _write_json_atomic(paths["control_selections"], payload)
281
+ append_event(
282
+ workspace=ws,
283
+ run_id=run_id,
284
+ event_type="control_selection_recorded",
285
+ actor=actor,
286
+ reason=reason.strip(),
287
+ metadata={
288
+ "control_selections": "output/intermediate/control_selections.json",
289
+ "control_id": control_id,
290
+ "selection": selection,
291
+ "approved_by_human": bool(approved_by_human),
292
+ "execution_ready": bool(execution_ready),
293
+ "switchboard_context_signature": switchboard_context_signature,
294
+ "archived_stale_control_selections": archived_stale_selections,
295
+ },
296
+ )
297
+ return _state_payload(ws, switchboard=switchboard, selections=payload)
298
+
299
+
300
+ def validate_control_switchboard(
301
+ *,
302
+ workspace: str | Path,
303
+ strict: bool = False,
304
+ actor: str = "cli",
305
+ ) -> dict[str, Any]:
306
+ ws = _require_workspace(workspace)
307
+ paths = control_switchboard_paths(ws)
308
+ switchboard = _load_switchboard(paths=paths)
309
+ selections = _read_json_object_if_exists(
310
+ paths["control_selections"],
311
+ label="control_selections.json",
312
+ )
313
+ errors: list[str] = []
314
+ if switchboard is None:
315
+ errors.append("orchestrator_control_switchboard.json is missing.")
316
+ else:
317
+ errors.extend(validate_switchboard_payload(switchboard))
318
+ errors.extend(_switchboard_stale_reasons(ws, switchboard))
319
+ errors.extend(validate_selections_payload(selections, switchboard=switchboard, strict=strict))
320
+
321
+ result = {
322
+ "ok": not errors,
323
+ "switchboard_present": switchboard is not None,
324
+ "selection_present": selections is not None,
325
+ "control_count": len((switchboard or {}).get("controls") or []),
326
+ "selection_count": len((selections or {}).get("selections") or []),
327
+ "strict": strict,
328
+ "errors": errors,
329
+ }
330
+ if switchboard is not None:
331
+ run_id = str(_current_run_id(ws) or switchboard.get("run_id") or "")
332
+ try:
333
+ append_event(
334
+ workspace=ws,
335
+ run_id=run_id,
336
+ event_type="control_selection_validated",
337
+ actor=actor,
338
+ reason="Control switchboard validation completed.",
339
+ metadata={
340
+ "ok": result["ok"],
341
+ "strict": strict,
342
+ "error_count": len(errors),
343
+ },
344
+ )
345
+ except RuntimeStateError:
346
+ if result["ok"]:
347
+ raise
348
+ return result
349
+
350
+
351
+ def validate_switchboard_payload(payload: dict[str, Any]) -> list[str]:
352
+ errors: list[str] = []
353
+ if payload.get("schema_version") != CONTROL_SWITCHBOARD_SCHEMA:
354
+ errors.append("orchestrator_control_switchboard.json has an unsupported schema_version.")
355
+ if not payload.get("run_id"):
356
+ errors.append("orchestrator_control_switchboard.json run_id is required.")
357
+ if "context_signature" in payload and not isinstance(payload.get("context_signature"), str):
358
+ errors.append("orchestrator_control_switchboard.json context_signature must be a string.")
359
+ controls = payload.get("controls")
360
+ if not isinstance(controls, list):
361
+ errors.append("orchestrator_control_switchboard.json controls must be a list.")
362
+ return errors
363
+ seen: set[str] = set()
364
+ for idx, control in enumerate(controls):
365
+ prefix = f"controls[{idx}]"
366
+ if not isinstance(control, dict):
367
+ errors.append(f"{prefix} must be an object.")
368
+ continue
369
+ control_id = str(control.get("control_id") or "")
370
+ if control_id not in CONTROL_IDS:
371
+ errors.append(f"{prefix}.control_id is unknown: {control_id}.")
372
+ if control_id in seen:
373
+ errors.append(f"{prefix}.control_id is duplicated: {control_id}.")
374
+ seen.add(control_id)
375
+ if control.get("recommendation") not in RECOMMENDATIONS:
376
+ errors.append(f"{prefix}.recommendation must be one of {sorted(RECOMMENDATIONS)}.")
377
+ if control.get("execution_type") not in EXECUTION_TYPES:
378
+ errors.append(f"{prefix}.execution_type must be one of {sorted(EXECUTION_TYPES)}.")
379
+ if not isinstance(control.get("requires_human_approval"), bool):
380
+ errors.append(f"{prefix}.requires_human_approval must be a boolean.")
381
+ if control_id in HUMAN_APPROVAL_CONTROLS and control.get("requires_human_approval") is not True:
382
+ errors.append(f"{prefix}.requires_human_approval must be true for privacy-sensitive controls.")
383
+ for path_key in ("inputs", "outputs"):
384
+ values = control.get(path_key) or []
385
+ if not isinstance(values, list):
386
+ errors.append(f"{prefix}.{path_key} must be a list.")
387
+ continue
388
+ for path_idx, value in enumerate(values):
389
+ if not isinstance(value, str):
390
+ errors.append(f"{prefix}.{path_key}[{path_idx}] must be a string.")
391
+ continue
392
+ try:
393
+ ensure_safe_relative_path(value, label=f"{prefix}.{path_key}[{path_idx}]")
394
+ except ControlSwitchboardError as exc:
395
+ errors.append(str(exc))
396
+ return errors
397
+
398
+
399
+ def validate_selections_payload(
400
+ payload: dict[str, Any] | None,
401
+ *,
402
+ switchboard: dict[str, Any],
403
+ strict: bool,
404
+ ) -> list[str]:
405
+ errors: list[str] = []
406
+ controls = switchboard.get("controls") or []
407
+ by_id = {str(item.get("control_id")): item for item in controls if isinstance(item, dict)}
408
+ if payload is None:
409
+ if strict:
410
+ required = sorted(
411
+ control_id
412
+ for control_id, control in by_id.items()
413
+ if control.get("recommendation") == "required"
414
+ )
415
+ if required:
416
+ errors.append(f"control_selections.json is missing required selections: {', '.join(required)}.")
417
+ return errors
418
+ if payload.get("schema_version") != CONTROL_SELECTIONS_SCHEMA:
419
+ errors.append("control_selections.json has an unsupported schema_version.")
420
+ if payload.get("run_id") != switchboard.get("run_id"):
421
+ errors.append("control_selections.json run_id must match switchboard run_id.")
422
+ switchboard_context_signature = str(switchboard.get("context_signature") or "")
423
+ if payload.get("switchboard_context_signature") != switchboard_context_signature:
424
+ errors.append("control_selections.json switchboard_context_signature must match the current switchboard context_signature.")
425
+ selections = payload.get("selections")
426
+ if not isinstance(selections, list):
427
+ errors.append("control_selections.json selections must be a list.")
428
+ return errors
429
+ seen: set[str] = set()
430
+ for idx, item in enumerate(selections):
431
+ prefix = f"selections[{idx}]"
432
+ if not isinstance(item, dict):
433
+ errors.append(f"{prefix} must be an object.")
434
+ continue
435
+ control_id = str(item.get("control_id") or "")
436
+ if control_id not in by_id:
437
+ errors.append(f"{prefix}.control_id is unknown or not present in switchboard: {control_id}.")
438
+ if control_id in seen:
439
+ errors.append(f"{prefix}.control_id has more than one effective selection: {control_id}.")
440
+ seen.add(control_id)
441
+ if item.get("selection") not in SELECTIONS:
442
+ errors.append(f"{prefix}.selection must be one of {sorted(SELECTIONS)}.")
443
+ if item.get("switchboard_context_signature") != switchboard_context_signature:
444
+ errors.append(f"{prefix}.switchboard_context_signature must match the current switchboard context_signature.")
445
+ if not str(item.get("reason") or "").strip():
446
+ errors.append(f"{prefix}.reason is required.")
447
+ if not isinstance(item.get("approved_by_human"), bool):
448
+ errors.append(f"{prefix}.approved_by_human must be a boolean.")
449
+ if item.get("executed") is not False:
450
+ errors.append(f"{prefix}.executed must remain false; selection is not execution.")
451
+ control = by_id.get(control_id) or {}
452
+ if (
453
+ control.get("requires_human_approval")
454
+ and item.get("selection") == "enable"
455
+ and item.get("approved_by_human") is True
456
+ and not str(item.get("human_approval_ref") or "").strip()
457
+ ):
458
+ errors.append(f"{prefix}.human_approval_ref is required for approved human-approval controls.")
459
+ expected_ready = (
460
+ item.get("selection") == "enable"
461
+ and (not control.get("requires_human_approval") or item.get("approved_by_human") is True)
462
+ )
463
+ if item.get("execution_ready") != expected_ready:
464
+ errors.append(f"{prefix}.execution_ready is inconsistent with selection and human approval.")
465
+ if strict:
466
+ missing_required = sorted(
467
+ control_id
468
+ for control_id, control in by_id.items()
469
+ if control.get("recommendation") == "required" and control_id not in seen
470
+ )
471
+ if missing_required:
472
+ errors.append(f"Missing required control selections: {', '.join(missing_required)}.")
473
+ return errors
474
+
475
+
476
+ def _build_controls(ws: Path, context: dict[str, Any]) -> list[dict[str, Any]]:
477
+ text = context["search_text"]
478
+ current_stage = context["current_stage"]
479
+ files = context["files"]
480
+ controls = [
481
+ _control_quality_gates(current_stage=current_stage, files=files),
482
+ _control_feedback(files=files),
483
+ _control_analysis_blocks(text=text, files=files),
484
+ _control_case_applicability(text=text, claim_text=context["claim_text"]),
485
+ _control_limitation_hygiene(text=text, claim_text=context["claim_text"]),
486
+ _control_local_signal(text=text),
487
+ _control_consumer_pain_point(text=text),
488
+ _control_provenance(current_stage=current_stage, files=files),
489
+ ]
490
+ return controls
491
+
492
+
493
+ def _base_control(
494
+ *,
495
+ control_id: str,
496
+ title: str,
497
+ recommendation: str,
498
+ requires_human_approval: bool,
499
+ reason: str,
500
+ execution_type: str,
501
+ execution_hint: str,
502
+ inputs: list[str] | None = None,
503
+ outputs: list[str] | None = None,
504
+ selection_required: bool = False,
505
+ blocking_semantics: str = "",
506
+ ) -> dict[str, Any]:
507
+ return {
508
+ "control_id": control_id,
509
+ "title": title,
510
+ "recommendation": recommendation,
511
+ "requires_human_approval": requires_human_approval,
512
+ "reason": reason,
513
+ "execution_type": execution_type,
514
+ "execution_hint": execution_hint,
515
+ "inputs": inputs or [],
516
+ "outputs": outputs or [],
517
+ "blocking_semantics": blocking_semantics,
518
+ "selection_required": selection_required,
519
+ "metadata": {},
520
+ }
521
+
522
+
523
+ def _control_quality_gates(*, current_stage: str | None, files: dict[str, bool]) -> dict[str, Any]:
524
+ required = current_stage in {"auditor", "finalize"} or files["audited_brief"] or files["brief"]
525
+ recommendation = "required" if required else "recommended"
526
+ reason = (
527
+ "Auditor/finalize path should run material-fact, freshness, target-relevance, and editor-new-fact gates before delivery."
528
+ if required
529
+ else "Quality gates are available when auditable draft and claim ledger artifacts exist."
530
+ )
531
+ if current_stage == "finalize":
532
+ execution_hint = (
533
+ "multi-agent-brief gates check --workspace <workspace> "
534
+ "--stage finalize --brief <workspace>/output/brief.md"
535
+ )
536
+ inputs = ["output/brief.md", "output/intermediate/claim_ledger.json"]
537
+ outputs = [
538
+ "output/intermediate/gates/finalize_quality_gate_report.json",
539
+ "output/intermediate/quality_gate_report.json",
540
+ ]
541
+ else:
542
+ execution_hint = "multi-agent-brief gates check --workspace <workspace> --stage auditor"
543
+ inputs = ["output/intermediate/audited_brief.md", "output/intermediate/claim_ledger.json"]
544
+ outputs = [
545
+ "output/intermediate/gates/auditor_quality_gate_report.json",
546
+ "output/intermediate/quality_gate_report.json",
547
+ ]
548
+ return _base_control(
549
+ control_id="quality_gates",
550
+ title="Deterministic quality gates",
551
+ recommendation=recommendation,
552
+ requires_human_approval=False,
553
+ reason=reason,
554
+ execution_type="cli",
555
+ execution_hint=execution_hint,
556
+ inputs=inputs,
557
+ outputs=outputs,
558
+ selection_required=required,
559
+ blocking_semantics="Existing quality gate runtime blockers apply only after gates check creates the stage-scoped report or policy enables gates.",
560
+ )
561
+
562
+
563
+ def _control_feedback(*, files: dict[str, bool]) -> dict[str, Any]:
564
+ if files["feedback_issues"] and not files["repair_plan"]:
565
+ recommendation = "required"
566
+ reason = "Feedback issues exist and no repair plan is present."
567
+ elif files["feedback_issues"]:
568
+ recommendation = "recommended"
569
+ reason = "Feedback issue state exists; Orchestrator should inspect repair status before continuing."
570
+ else:
571
+ recommendation = "suggested"
572
+ reason = "Feedback controls are available if audit findings or human feedback need repair planning."
573
+ return _base_control(
574
+ control_id="feedback_repair_plan",
575
+ title="Feedback issue and repair-plan controls",
576
+ recommendation=recommendation,
577
+ requires_human_approval=False,
578
+ reason=reason,
579
+ execution_type="cli",
580
+ execution_hint="multi-agent-brief feedback show --workspace <workspace> --json",
581
+ inputs=["output/intermediate/feedback_issues.json"],
582
+ outputs=["output/intermediate/repair_plan.json"],
583
+ selection_required=recommendation == "required",
584
+ blocking_semantics="Existing feedback runtime blockers apply only from feedback_issues.json and repair_plan.json.",
585
+ )
586
+
587
+
588
+ def _control_analysis_blocks(*, text: str, files: dict[str, bool]) -> dict[str, Any]:
589
+ hit = _has_any(text, TEXT_TRIGGERS["executive"]) or files["claim_ledger"]
590
+ return _base_control(
591
+ control_id="analysis_blocks",
592
+ title="Analysis block grouping",
593
+ recommendation="recommended" if hit else "suggested",
594
+ requires_human_approval=False,
595
+ reason=(
596
+ "Executive or claim-ledger context benefits from grouped analysis blocks."
597
+ if hit
598
+ else "Analysis blocks can be used when the claim ledger is ready."
599
+ ),
600
+ execution_type="cli",
601
+ execution_hint="multi-agent-brief analysis-blocks --ledger <workspace>/output/intermediate/claim_ledger.json --output <workspace>/output/intermediate/analysis_blocks.json",
602
+ inputs=["output/intermediate/claim_ledger.json"],
603
+ outputs=["output/intermediate/analysis_blocks.json"],
604
+ )
605
+
606
+
607
+ def _control_case_applicability(*, text: str, claim_text: str) -> dict[str, Any]:
608
+ hit = _has_any(f"{text}\n{claim_text}", TEXT_TRIGGERS["case"])
609
+ return _base_control(
610
+ control_id="case_applicability",
611
+ title="Case applicability checks",
612
+ recommendation="recommended" if hit else "not_applicable",
613
+ requires_human_approval=False,
614
+ reason=(
615
+ "Case/comparable language is present; auditor should apply applicability checks."
616
+ if hit
617
+ else "No explicit case/comparable trigger detected."
618
+ ),
619
+ execution_type="audit_rule",
620
+ execution_hint="Ask auditor to apply case applicability checks to case/comparable claims.",
621
+ inputs=["output/intermediate/claim_ledger.json"],
622
+ outputs=[],
623
+ )
624
+
625
+
626
+ def _control_limitation_hygiene(*, text: str, claim_text: str) -> dict[str, Any]:
627
+ hit = _has_any(f"{text}\n{claim_text}", TEXT_TRIGGERS["limitation"])
628
+ return _base_control(
629
+ control_id="limitation_hygiene",
630
+ title="Limitation hygiene checks",
631
+ recommendation="recommended" if hit else "suggested",
632
+ requires_human_approval=False,
633
+ reason=(
634
+ "Forecast, hypothesis, analogy, risk, or caveat language is present."
635
+ if hit
636
+ else "Limitation hygiene is available for uncertainty-heavy briefs."
637
+ ),
638
+ execution_type="cli",
639
+ execution_hint="multi-agent-brief limitation-hygiene --ledger <workspace>/output/intermediate/claim_ledger.json --output <workspace>/output/intermediate/limitation_hygiene_report.json",
640
+ inputs=["output/intermediate/claim_ledger.json"],
641
+ outputs=["output/intermediate/limitation_hygiene_report.json"],
642
+ )
643
+
644
+
645
+ def _control_local_signal(*, text: str) -> dict[str, Any]:
646
+ hit = _has_any(text, TEXT_TRIGGERS["local_signal"])
647
+ return _base_control(
648
+ control_id="local_signal_discovery",
649
+ title="Local signal discovery",
650
+ recommendation="recommended" if hit else "suggested",
651
+ requires_human_approval=True,
652
+ reason=(
653
+ "Local market or social-signal context is present; human approval is required before collection."
654
+ if hit
655
+ else "Local signal discovery is available but requires human approval before any collection."
656
+ ),
657
+ execution_type="config_review",
658
+ execution_hint="Review and configure sources.yaml local signal discovery; do not collect without explicit approval.",
659
+ inputs=["sources.yaml"],
660
+ outputs=[],
661
+ )
662
+
663
+
664
+ def _control_consumer_pain_point(*, text: str) -> dict[str, Any]:
665
+ hit = _has_any(text, TEXT_TRIGGERS["pain_point"])
666
+ return _base_control(
667
+ control_id="consumer_pain_point_discovery",
668
+ title="Consumer pain-point discovery",
669
+ recommendation="recommended" if hit else "suggested",
670
+ requires_human_approval=True,
671
+ reason=(
672
+ "Consumer pain-point or review-mining context is present; human approval is required before collection."
673
+ if hit
674
+ else "Consumer pain-point discovery is available but requires human approval before any collection."
675
+ ),
676
+ execution_type="config_review",
677
+ execution_hint="Review consumer pain-point discovery scope with a human before configuring source collection.",
678
+ inputs=["sources.yaml"],
679
+ outputs=[],
680
+ )
681
+
682
+
683
+ def _control_provenance(*, current_stage: str | None, files: dict[str, bool]) -> dict[str, Any]:
684
+ ready = files["claim_ledger"] and (files["audited_brief"] or files["brief"] or current_stage in {None, "finalize"})
685
+ return _base_control(
686
+ control_id="provenance_projection",
687
+ title="Deterministic provenance projection",
688
+ recommendation="recommended" if ready else "suggested",
689
+ requires_human_approval=False,
690
+ reason=(
691
+ "Audit/final artifacts exist; provenance projection can summarize existing control records."
692
+ if ready
693
+ else "Provenance projection is available after runtime and audit/control files exist."
694
+ ),
695
+ execution_type="cli",
696
+ execution_hint="multi-agent-brief provenance build --workspace <workspace>",
697
+ inputs=[
698
+ "output/intermediate/runtime_manifest.json",
699
+ "output/intermediate/artifact_registry.json",
700
+ "output/intermediate/event_log.jsonl",
701
+ ],
702
+ outputs=["output/intermediate/provenance_graph.json"],
703
+ blocking_semantics="Provenance remains audit/debug tooling and is not a finalize gate by default.",
704
+ )
705
+
706
+
707
+ def _state_payload(
708
+ ws: Path,
709
+ *,
710
+ switchboard: dict[str, Any] | None,
711
+ selections: dict[str, Any] | None = None,
712
+ ) -> dict[str, Any]:
713
+ paths = control_switchboard_paths(ws)
714
+ if selections is None:
715
+ selections = _read_json_object_if_exists(paths["control_selections"], label="control_selections.json")
716
+ validation_errors = validate_switchboard_payload(switchboard) if switchboard is not None else []
717
+ if switchboard is not None:
718
+ validation_errors.extend(_switchboard_stale_reasons(ws, switchboard))
719
+ if switchboard is not None:
720
+ validation_errors.extend(validate_selections_payload(selections, switchboard=switchboard, strict=False))
721
+ return {
722
+ "ok": switchboard is not None and not validation_errors,
723
+ "control_switchboard_path": str(paths["orchestrator_control_switchboard"]),
724
+ "control_selections_path": str(paths["control_selections"]),
725
+ "orchestrator_control_switchboard": switchboard,
726
+ "control_selections": selections,
727
+ "validation": {
728
+ "ok": not validation_errors,
729
+ "errors": validation_errors,
730
+ "control_count": len((switchboard or {}).get("controls") or []),
731
+ "selection_count": len((selections or {}).get("selections") or []),
732
+ },
733
+ }
734
+
735
+
736
+ def _switchboard_inputs(ws: Path) -> dict[str, str]:
737
+ candidates = {
738
+ "config": "config.yaml",
739
+ "sources": "sources.yaml",
740
+ "user": "user.md",
741
+ "audience_profile_snapshot": "output/intermediate/audience_profile_snapshot.md",
742
+ "runtime_manifest": "output/intermediate/runtime_manifest.json",
743
+ "workflow_state": "output/intermediate/workflow_state.json",
744
+ "artifact_registry": "output/intermediate/artifact_registry.json",
745
+ }
746
+ return {key: rel for key, rel in candidates.items() if (ws / rel).exists()}
747
+
748
+
749
+ def _load_switchboard(*, paths: dict[str, Path]) -> dict[str, Any] | None:
750
+ return _read_json_object_if_exists(
751
+ paths["orchestrator_control_switchboard"],
752
+ label="orchestrator_control_switchboard.json",
753
+ )
754
+
755
+
756
+ def refresh_control_switchboard_if_stale(
757
+ *,
758
+ workspace: str | Path,
759
+ repo_workdir: str | Path | None = None,
760
+ actor: str = "cli",
761
+ ) -> dict[str, Any] | None:
762
+ """Refresh an existing switchboard if runtime context changed."""
763
+ ws = _require_workspace(workspace)
764
+ paths = control_switchboard_paths(ws)
765
+ switchboard = _read_json_object_if_exists(
766
+ paths["orchestrator_control_switchboard"],
767
+ label="orchestrator_control_switchboard.json",
768
+ )
769
+ if switchboard is None:
770
+ return None
771
+ if not _switchboard_stale_reasons(ws, switchboard):
772
+ return _state_payload(ws, switchboard=switchboard)
773
+ return build_control_switchboard(workspace=ws, repo_workdir=repo_workdir, actor=actor)
774
+
775
+
776
+ def _switchboard_stale_reasons(ws: Path, switchboard: dict[str, Any]) -> list[str]:
777
+ reasons: list[str] = []
778
+ current_run_id = _current_run_id(ws) or ""
779
+ if current_run_id and switchboard.get("run_id") != current_run_id:
780
+ reasons.append(
781
+ "orchestrator_control_switchboard.json run_id does not match current runtime run_id; "
782
+ "run controls build-switchboard to rebuild it."
783
+ )
784
+ expected_signature = _context_signature(ws)
785
+ if switchboard.get("context_signature") != expected_signature:
786
+ reasons.append(
787
+ "orchestrator_control_switchboard.json is stale for the current workspace context; "
788
+ "run controls build-switchboard to rebuild it."
789
+ )
790
+ return reasons
791
+
792
+
793
+ def _context_signature(ws: Path, *, context: dict[str, Any] | None = None) -> str:
794
+ if context is None:
795
+ context = _load_context(ws)
796
+ payload = {
797
+ "run_id": _current_run_id(ws) or "",
798
+ "current_stage": context.get("current_stage") or "",
799
+ "files": context.get("files") or {},
800
+ "inputs": {
801
+ rel_path: _file_fingerprint(ws / rel_path)
802
+ for rel_path in (
803
+ "config.yaml",
804
+ "sources.yaml",
805
+ "user.md",
806
+ "output/intermediate/audience_profile_snapshot.md",
807
+ "output/intermediate/claim_ledger.json",
808
+ "output/intermediate/audited_brief.md",
809
+ "output/brief.md",
810
+ "output/intermediate/feedback_issues.json",
811
+ "output/intermediate/repair_plan.json",
812
+ "output/intermediate/gates/auditor_quality_gate_report.json",
813
+ "output/intermediate/gates/finalize_quality_gate_report.json",
814
+ "output/intermediate/quality_gate_report.json",
815
+ )
816
+ },
817
+ }
818
+ text = json.dumps(payload, ensure_ascii=False, sort_keys=True)
819
+ return hashlib.sha256(text.encode("utf-8")).hexdigest()
820
+
821
+
822
+ def _file_fingerprint(path: Path) -> dict[str, Any]:
823
+ if not path.exists() or not path.is_file():
824
+ return {"exists": False}
825
+ digest = hashlib.sha256()
826
+ try:
827
+ with path.open("rb") as fh:
828
+ for chunk in iter(lambda: fh.read(1024 * 1024), b""):
829
+ digest.update(chunk)
830
+ except OSError:
831
+ return {"exists": True, "readable": False}
832
+ return {
833
+ "exists": True,
834
+ "size": path.stat().st_size,
835
+ "sha256": digest.hexdigest(),
836
+ }
837
+
838
+
839
+ def _archive_selections_for_other_run(
840
+ *,
841
+ paths: dict[str, Path],
842
+ current_run_id: str,
843
+ ) -> str | None:
844
+ selections_path = paths["control_selections"]
845
+ existing = _read_json_object_if_exists(selections_path, label="control_selections.json")
846
+ if existing is None or existing.get("run_id") == current_run_id:
847
+ return None
848
+ return _archive_control_selections_path(
849
+ paths=paths,
850
+ existing=existing,
851
+ suffix=None,
852
+ )
853
+
854
+
855
+ def _archive_selections_for_other_context(
856
+ *,
857
+ paths: dict[str, Path],
858
+ current_run_id: str,
859
+ current_context_signature: str,
860
+ ) -> str | None:
861
+ selections_path = paths["control_selections"]
862
+ existing = _read_json_object_if_exists(selections_path, label="control_selections.json")
863
+ if existing is None:
864
+ return None
865
+ if existing.get("run_id") != current_run_id:
866
+ return None
867
+ if existing.get("switchboard_context_signature") == current_context_signature:
868
+ return None
869
+ return _archive_control_selections_path(
870
+ paths=paths,
871
+ existing=existing,
872
+ suffix="stale",
873
+ )
874
+
875
+
876
+ def _archive_control_selections_path(
877
+ *,
878
+ paths: dict[str, Path],
879
+ existing: dict[str, Any],
880
+ suffix: str | None,
881
+ ) -> str:
882
+ selections_path = paths["control_selections"]
883
+ old_run_id = str(existing.get("run_id") or "unknown")
884
+ suffix_part = f".{suffix}" if suffix else ""
885
+ archive = selections_path.with_name(f"control_selections.{old_run_id}{suffix_part}.json")
886
+ if archive.exists():
887
+ archive = selections_path.with_name(
888
+ f"control_selections.{old_run_id}{suffix_part}.{uuid.uuid4().hex[:8]}.json"
889
+ )
890
+ os.replace(selections_path, archive)
891
+ return archive.name
892
+
893
+
894
+ def _load_context(ws: Path) -> dict[str, Any]:
895
+ warnings: list[str] = []
896
+ config = _read_yaml(ws / "config.yaml", warnings=warnings)
897
+ sources = _read_yaml(ws / "sources.yaml", warnings=warnings)
898
+ user = _read_text_if_exists(ws / "user.md")
899
+ audience_snapshot = _read_text_if_exists(ws / "output" / "intermediate" / "audience_profile_snapshot.md")
900
+ workflow = _read_json_object_if_exists(runtime_state_paths(ws)["workflow_state"], label="workflow_state.json") or {}
901
+ claim_ledger = _read_json_value_if_exists(ws / "output" / "intermediate" / "claim_ledger.json", label="claim_ledger.json")
902
+ search_text = "\n".join(
903
+ _redact_long_text(part)
904
+ for part in (
905
+ _dump_public_context(config),
906
+ _dump_public_context(sources),
907
+ user,
908
+ audience_snapshot,
909
+ )
910
+ if part
911
+ ).lower()
912
+ files = {
913
+ "audited_brief": (ws / "output" / "intermediate" / "audited_brief.md").exists(),
914
+ "brief": (ws / "output" / "brief.md").exists(),
915
+ "claim_ledger": claim_ledger is not None,
916
+ "feedback_issues": (ws / "output" / "intermediate" / "feedback_issues.json").exists(),
917
+ "repair_plan": (ws / "output" / "intermediate" / "repair_plan.json").exists(),
918
+ "quality_gate_report": (ws / "output" / "intermediate" / "quality_gate_report.json").exists(),
919
+ "auditor_quality_gate_report": (
920
+ ws / "output" / "intermediate" / "gates" / "auditor_quality_gate_report.json"
921
+ ).exists(),
922
+ "finalize_quality_gate_report": (
923
+ ws / "output" / "intermediate" / "gates" / "finalize_quality_gate_report.json"
924
+ ).exists(),
925
+ }
926
+ return {
927
+ "warnings": warnings,
928
+ "search_text": search_text,
929
+ "claim_text": _claim_metadata_text(claim_ledger).lower(),
930
+ "current_stage": workflow.get("current_stage"),
931
+ "files": files,
932
+ }
933
+
934
+
935
+ def _read_yaml(path: Path, *, warnings: list[str]) -> Any:
936
+ if not path.exists():
937
+ return {}
938
+ try:
939
+ return yaml.safe_load(path.read_text(encoding="utf-8")) or {}
940
+ except (OSError, yaml.YAMLError) as exc:
941
+ warnings.append(f"Failed to read {path.name}: {exc}")
942
+ return {}
943
+
944
+
945
+ def _dump_public_context(value: Any) -> str:
946
+ if isinstance(value, dict):
947
+ parts: list[str] = []
948
+ for key, item in value.items():
949
+ if str(key).lower() in {"api_key", "token", "secret", "password"}:
950
+ continue
951
+ parts.append(f"{key}: {_dump_public_context(item)}")
952
+ return "\n".join(parts)
953
+ if isinstance(value, list):
954
+ return "\n".join(_dump_public_context(item) for item in value)
955
+ return str(value)
956
+
957
+
958
+ def _claim_metadata_text(payload: Any) -> str:
959
+ if not payload:
960
+ return ""
961
+ claims = payload.get("claims") if isinstance(payload, dict) and isinstance(payload.get("claims"), list) else payload
962
+ if not isinstance(claims, list):
963
+ return ""
964
+ parts: list[str] = []
965
+ for claim in claims:
966
+ if not isinstance(claim, dict):
967
+ continue
968
+ metadata = claim.get("metadata") if isinstance(claim.get("metadata"), dict) else {}
969
+ for key in ("claim_type", "evidence_relation", "confidence"):
970
+ if claim.get(key):
971
+ parts.append(str(claim.get(key)))
972
+ for key in ("claim_type", "evidence_relation", "confidence", "limitations", "applicability_reason"):
973
+ if metadata.get(key):
974
+ parts.append(str(metadata.get(key)))
975
+ return "\n".join(parts)
976
+
977
+
978
+ def _redact_long_text(text: str) -> str:
979
+ text = re.sub(r"(?i)(api[_-]?key|token|secret|password)\s*[:=]\s*\S+", r"\1: [redacted]", text)
980
+ return text[:12000]
981
+
982
+
983
+ def _has_any(text: str, needles: set[str]) -> bool:
984
+ lowered = text.lower()
985
+ return any(needle.lower() in lowered for needle in needles)
986
+
987
+
988
+ def _control_by_id(switchboard: dict[str, Any], control_id: str) -> dict[str, Any] | None:
989
+ for item in switchboard.get("controls") or []:
990
+ if isinstance(item, dict) and item.get("control_id") == control_id:
991
+ return item
992
+ return None
993
+
994
+
995
+ def _current_run_id(ws: Path) -> str | None:
996
+ manifest = _read_json_object_if_exists(runtime_state_paths(ws)["runtime_manifest"], label="runtime_manifest.json")
997
+ if manifest:
998
+ return str(manifest.get("run_id") or "")
999
+ return None
1000
+
1001
+
1002
+ def _require_workspace(workspace: str | Path) -> Path:
1003
+ ws = Path(workspace).expanduser().resolve()
1004
+ if not (ws / "config.yaml").exists():
1005
+ raise ControlSwitchboardError(
1006
+ f"Workspace config.yaml not found: {ws / 'config.yaml'}",
1007
+ details={"workspace": str(ws)},
1008
+ )
1009
+ return ws
1010
+
1011
+
1012
+ def _read_text_if_exists(path: Path) -> str:
1013
+ if not path.exists():
1014
+ return ""
1015
+ try:
1016
+ return path.read_text(encoding="utf-8", errors="replace")
1017
+ except OSError:
1018
+ return ""
1019
+
1020
+
1021
+ def _read_json_object_if_exists(path: Path, *, label: str) -> dict[str, Any] | None:
1022
+ if not path.exists():
1023
+ return None
1024
+ try:
1025
+ data = json.loads(path.read_text(encoding="utf-8"))
1026
+ except json.JSONDecodeError as exc:
1027
+ raise ControlSwitchboardError(
1028
+ f"Invalid JSON {label}: {path}",
1029
+ details={"path": str(path), "reason": str(exc)},
1030
+ ) from exc
1031
+ except OSError as exc:
1032
+ raise ControlSwitchboardError(
1033
+ f"Failed to read {label}: {path}",
1034
+ details={"path": str(path), "reason": str(exc)},
1035
+ ) from exc
1036
+ if not isinstance(data, dict):
1037
+ raise ControlSwitchboardError(
1038
+ f"{label} must contain a JSON object: {path}",
1039
+ details={"path": str(path)},
1040
+ )
1041
+ return data
1042
+
1043
+
1044
+ def _read_json_value_if_exists(path: Path, *, label: str) -> Any:
1045
+ if not path.exists():
1046
+ return None
1047
+ try:
1048
+ return json.loads(path.read_text(encoding="utf-8"))
1049
+ except json.JSONDecodeError as exc:
1050
+ raise ControlSwitchboardError(
1051
+ f"Invalid JSON {label}: {path}",
1052
+ details={"path": str(path), "reason": str(exc)},
1053
+ ) from exc
1054
+ except OSError as exc:
1055
+ raise ControlSwitchboardError(
1056
+ f"Failed to read {label}: {path}",
1057
+ details={"path": str(path), "reason": str(exc)},
1058
+ ) from exc
1059
+
1060
+
1061
+ def _write_json_atomic(path: Path, payload: dict[str, Any]) -> None:
1062
+ path.parent.mkdir(parents=True, exist_ok=True)
1063
+ text = json.dumps(payload, ensure_ascii=False, indent=2, sort_keys=True) + "\n"
1064
+ tmp = path.with_name(f".{path.name}.{uuid.uuid4().hex}.tmp")
1065
+ try:
1066
+ tmp.write_text(text, encoding="utf-8")
1067
+ os.replace(tmp, path)
1068
+ except OSError as exc:
1069
+ try:
1070
+ tmp.unlink(missing_ok=True)
1071
+ except OSError:
1072
+ pass
1073
+ raise ControlSwitchboardError(
1074
+ f"Failed to write control switchboard file: {path}",
1075
+ details={"path": str(path), "reason": str(exc)},
1076
+ ) from exc