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,832 @@
1
+ from __future__ import annotations
2
+
3
+ import json
4
+ import shlex
5
+ from dataclasses import asdict, dataclass, field
6
+ from pathlib import Path
7
+ from typing import Any
8
+
9
+ from multi_agent_brief.orchestrator_contract import ORCHESTRATOR_LOOP, contract_reference_bullets
10
+
11
+ HERMES_SKILL_NAME = "multi-agent-brief-hermes"
12
+ DEFAULT_DAILY_SCHEDULE = "0 7 * * *"
13
+ DEFAULT_WEEKLY_SCHEDULE = "0 9 * * 1"
14
+ DEFAULT_MONTHLY_SCHEDULE = "30 8 1 * *"
15
+ REPAIR_GUIDANCE_NOTE = (
16
+ "Repair guidance is bounded runtime guidance, not an automatic trajectory regulator: "
17
+ "if the same stage has already needed roughly three retry/repair rounds, prefer "
18
+ "request_human_review or block_run; if a repair would touch more than two sections, "
19
+ "narrow the scope before delegating or request human review. Audit warnings, "
20
+ "overstatement findings, support-calibration findings, and quality-gate findings "
21
+ "do not authorize direct edits to frozen artifacts. For owner-stage artifact "
22
+ "repair, run `briefloop repair route --workspace <workspace>` and "
23
+ "`briefloop repair start --workspace <workspace>` before delegation; after "
24
+ "the owner edits only allowed_artifacts, run `briefloop repair complete "
25
+ "--workspace <workspace> --reason \"<reason>\"` and rerun downstream stages from "
26
+ "must_rerun_from."
27
+ )
28
+
29
+
30
+ @dataclass
31
+ class HermesCronJob:
32
+ name: str
33
+ schedule: str
34
+ prompt: str
35
+ skills: list[str] = field(default_factory=lambda: [HERMES_SKILL_NAME])
36
+ workdir: str = ""
37
+ profile: str = ""
38
+ deliver: str = "local"
39
+ context_from: list[str] = field(default_factory=list)
40
+ enabled_toolsets: list[str] = field(default_factory=lambda: ["web", "file", "terminal"])
41
+ purpose: str = ""
42
+
43
+ def to_dict(self) -> dict[str, Any]:
44
+ return asdict(self)
45
+
46
+
47
+ @dataclass
48
+ class HermesCronPlan:
49
+ version: str
50
+ workspace: str
51
+ project_name: str
52
+ cadences: list[str]
53
+ cache_dir: str
54
+ jobs: list[HermesCronJob]
55
+ notes: list[str] = field(default_factory=list)
56
+
57
+ def to_dict(self) -> dict[str, Any]:
58
+ data = asdict(self)
59
+ data["jobs"] = [job.to_dict() for job in self.jobs]
60
+ return data
61
+
62
+
63
+ def _as_list(value: Any) -> list[str]:
64
+ if value is None:
65
+ return []
66
+ if isinstance(value, list):
67
+ return [str(v).strip() for v in value if str(v).strip()]
68
+ if isinstance(value, tuple):
69
+ return [str(v).strip() for v in value if str(v).strip()]
70
+ text = str(value).strip()
71
+ if not text:
72
+ return []
73
+ return [part.strip() for part in text.replace(";", ",").split(",") if part.strip()]
74
+
75
+
76
+ def _project_summary(config: dict[str, Any]) -> dict[str, str]:
77
+ project = config.get("project", {}) or {}
78
+ report = config.get("report", {}) or {}
79
+ language = config.get("language", {}) or {}
80
+ return {
81
+ "name": str(project.get("name") or project.get("title") or "BriefLoop Brief"),
82
+ "company": str(project.get("company") or ""),
83
+ "industry": str(project.get("industry") or ""),
84
+ "audience": str(project.get("audience") or "management"),
85
+ "language": str(language.get("output") or project.get("language") or "zh-CN"),
86
+ "cadence": str(report.get("cadence") or project.get("cadence") or ""),
87
+ }
88
+
89
+
90
+ def _resolve_cadences(config: dict[str, Any], requested: list[str] | None) -> list[str]:
91
+ explicit = [c.lower().replace("-", "_") for c in (requested or [])]
92
+ if explicit:
93
+ return [c for c in explicit if c in {"daily", "weekly", "monthly"}]
94
+
95
+ summary = _project_summary(config)
96
+ raw = summary.get("cadence") or "weekly"
97
+ cadences = [c.lower().replace("-", "_") for c in _as_list(raw)]
98
+ if not cadences:
99
+ cadences = ["weekly"]
100
+ return [c for c in cadences if c in {"daily", "weekly", "monthly"}] or ["weekly"]
101
+
102
+
103
+ def _prompt_context(summary: dict[str, str], workspace: Path, cache_dir: Path) -> str:
104
+ bits = [
105
+ f"Workspace: {workspace}",
106
+ f"Project: {summary['name']}",
107
+ f"Audience: {summary['audience']}",
108
+ f"Language: {summary['language']}",
109
+ ]
110
+ if summary["company"]:
111
+ bits.append(f"Company: {summary['company']}")
112
+ if summary["industry"]:
113
+ bits.append(f"Industry/theme: {summary['industry']}")
114
+ bits.append(f"Daily cache directory: {cache_dir}")
115
+ return "\n".join(bits)
116
+
117
+
118
+ def build_hermes_cron_plan(
119
+ *,
120
+ config: dict[str, Any],
121
+ workspace: str | Path,
122
+ repo_workdir: str | Path,
123
+ cadences: list[str] | None = None,
124
+ deliver: str = "local",
125
+ profile: str = "",
126
+ daily_schedule: str = DEFAULT_DAILY_SCHEDULE,
127
+ weekly_schedule: str = DEFAULT_WEEKLY_SCHEDULE,
128
+ monthly_schedule: str = DEFAULT_MONTHLY_SCHEDULE,
129
+ ) -> HermesCronPlan:
130
+ workspace_path = Path(workspace).resolve()
131
+ repo_path = Path(repo_workdir).resolve()
132
+ summary = _project_summary(config)
133
+ resolved_cadences = _resolve_cadences(config, cadences)
134
+ cache_dir = workspace_path / "input" / "hermes_cache"
135
+ prompt_context = _prompt_context(summary, workspace_path, cache_dir)
136
+
137
+ jobs: list[HermesCronJob] = []
138
+ daily_job = HermesCronJob(
139
+ name=f"BriefLoop daily cache - {summary['name']}",
140
+ schedule=daily_schedule,
141
+ workdir=str(repo_path),
142
+ profile=profile,
143
+ deliver=deliver,
144
+ purpose="Collect daily source signals into the workspace cache for later weekly/monthly synthesis.",
145
+ prompt=(
146
+ "Run a Hermes daily source cache collection for this BriefLoop workspace.\n\n"
147
+ f"{prompt_context}\n\n"
148
+ "Use the multi-agent-brief-hermes skill.\n"
149
+ "Collect source signals and write YYYY-MM-DD.json.\n"
150
+ "Report saved item count and source gaps."
151
+ ),
152
+ )
153
+ jobs.append(daily_job)
154
+
155
+ if "weekly" in resolved_cadences:
156
+ jobs.append(HermesCronJob(
157
+ name=f"BriefLoop weekly brief - {summary['name']}",
158
+ schedule=weekly_schedule,
159
+ workdir=str(repo_path),
160
+ profile=profile,
161
+ deliver=deliver,
162
+ context_from=[daily_job.name],
163
+ purpose="Run the audited weekly brief workflow using Hermes delegate_task children.",
164
+ prompt=(
165
+ "Run a Hermes-native delegated BriefLoop brief workflow as the Orchestrator main agent.\n\n"
166
+ f"{prompt_context}\n\n"
167
+ "Use the multi-agent-brief-hermes skill.\n"
168
+ "Read contract references before delegation:\n"
169
+ f"{contract_reference_bullets()}\n\n"
170
+ "Read runtime state files before selecting the next stage:\n"
171
+ "- output/intermediate/runtime_manifest.json\n"
172
+ "- output/intermediate/workflow_state.json\n"
173
+ "- output/intermediate/artifact_registry.json\n"
174
+ "- output/intermediate/event_log.jsonl\n\n"
175
+ "Read audience memory snapshot for this run:\n"
176
+ "- output/intermediate/audience_profile_snapshot.md\n"
177
+ "Summarize relevant taste guidance for delegated roles. Do not treat audience_profile.md as source evidence, and do not use mid-run profile edits until the next run.\n\n"
178
+ "Read the Orchestrator control switchboard:\n"
179
+ "- output/intermediate/orchestrator_control_switchboard.json\n"
180
+ "Record control selections with briefloop controls select. Selection is not execution.\n\n"
181
+ f"{REPAIR_GUIDANCE_NOTE}\n\n"
182
+ "Optional feedback state files are created only by feedback commands:\n"
183
+ "- output/intermediate/feedback_issues.json\n"
184
+ "- output/intermediate/repair_plan.json\n"
185
+ "- output/intermediate/delta_audit_report.json\n\n"
186
+ "Optional quality gate state files are created only by gates commands:\n"
187
+ "- output/intermediate/gates/auditor_quality_gate_report.json\n"
188
+ "- output/intermediate/gates/finalize_quality_gate_report.json\n"
189
+ "- output/intermediate/quality_gate_report.json (legacy/latest projection)\n\n"
190
+ "Optional provenance projection files are created only by provenance commands:\n"
191
+ "- output/intermediate/provenance_graph.json\n\n"
192
+ f"Orchestrator loop: {ORCHESTRATOR_LOOP}\n"
193
+ "Run doctor, then use Hermes delegate_task children for:\n"
194
+ "default topology: scout(discovery+screening) -> claim-ledger -> analyst -> editor/Delivery Editor -> auditor.\n"
195
+ "strict topology: scout -> screener -> claim-ledger -> analyst -> editor/Delivery Editor -> auditor.\n"
196
+ "After audit_report.json exists, run:\n"
197
+ f"briefloop controls select --workspace {workspace_path} --control quality_gates --selection enable --reason \"Use quality gates before finalize.\"\n"
198
+ f"briefloop gates check --workspace {workspace_path} --stage auditor\n"
199
+ f"briefloop state check --workspace {workspace_path} --strict\n"
200
+ f"briefloop state stage-complete --workspace {workspace_path} --stage auditor --reason \"Audit and quality gates passed.\"\n"
201
+ f"Then run briefloop finalize --config {workspace_path}/config.yaml.\n"
202
+ f"After finalize writes reader-facing artifacts, run briefloop gates check --workspace {workspace_path} --stage finalize --brief {workspace_path}/output/brief.md, then run briefloop state finalize-complete --workspace {workspace_path} --reason \"Reader-facing artifacts passed finalize checks.\"\n"
203
+ "finalize is not a quality-gate executor.\n"
204
+ "Optionally run briefloop provenance build/show/validate after runtime state exists for an audit/debug projection; it is not semantic proof."
205
+ ),
206
+ ))
207
+
208
+ if "monthly" in resolved_cadences:
209
+ jobs.append(HermesCronJob(
210
+ name=f"BriefLoop monthly brief - {summary['name']}",
211
+ schedule=monthly_schedule,
212
+ workdir=str(repo_path),
213
+ profile=profile,
214
+ deliver=deliver,
215
+ context_from=[daily_job.name],
216
+ purpose="Run the audited monthly brief workflow using Hermes delegate_task children.",
217
+ prompt=(
218
+ "Run a Hermes-native delegated BriefLoop brief workflow as the Orchestrator main agent.\n\n"
219
+ f"{prompt_context}\n\n"
220
+ "Use the multi-agent-brief-hermes skill.\n"
221
+ "Read contract references before delegation:\n"
222
+ f"{contract_reference_bullets()}\n\n"
223
+ "Read runtime state files before selecting the next stage:\n"
224
+ "- output/intermediate/runtime_manifest.json\n"
225
+ "- output/intermediate/workflow_state.json\n"
226
+ "- output/intermediate/artifact_registry.json\n"
227
+ "- output/intermediate/event_log.jsonl\n\n"
228
+ "Read audience memory snapshot for this run:\n"
229
+ "- output/intermediate/audience_profile_snapshot.md\n"
230
+ "Summarize relevant taste guidance for delegated roles. Do not treat audience_profile.md as source evidence, and do not use mid-run profile edits until the next run.\n\n"
231
+ "Read the Orchestrator control switchboard:\n"
232
+ "- output/intermediate/orchestrator_control_switchboard.json\n"
233
+ "Record control selections with briefloop controls select. Selection is not execution.\n\n"
234
+ f"{REPAIR_GUIDANCE_NOTE}\n\n"
235
+ "Optional feedback state files are created only by feedback commands:\n"
236
+ "- output/intermediate/feedback_issues.json\n"
237
+ "- output/intermediate/repair_plan.json\n"
238
+ "- output/intermediate/delta_audit_report.json\n\n"
239
+ "Optional quality gate state files are created only by gates commands:\n"
240
+ "- output/intermediate/gates/auditor_quality_gate_report.json\n"
241
+ "- output/intermediate/gates/finalize_quality_gate_report.json\n"
242
+ "- output/intermediate/quality_gate_report.json (legacy/latest projection)\n\n"
243
+ "Optional provenance projection files are created only by provenance commands:\n"
244
+ "- output/intermediate/provenance_graph.json\n\n"
245
+ f"Orchestrator loop: {ORCHESTRATOR_LOOP}\n"
246
+ "Favor month-level patterns over daily noise.\n"
247
+ "Run doctor, then use Hermes delegate_task children for:\n"
248
+ "default topology: scout(discovery+screening) -> claim-ledger -> analyst -> editor/Delivery Editor -> auditor.\n"
249
+ "strict topology: scout -> screener -> claim-ledger -> analyst -> editor/Delivery Editor -> auditor.\n"
250
+ "After audit_report.json exists, run:\n"
251
+ f"briefloop controls select --workspace {workspace_path} --control quality_gates --selection enable --reason \"Use quality gates before finalize.\"\n"
252
+ f"briefloop gates check --workspace {workspace_path} --stage auditor\n"
253
+ f"briefloop state check --workspace {workspace_path} --strict\n"
254
+ f"briefloop state stage-complete --workspace {workspace_path} --stage auditor --reason \"Audit and quality gates passed.\"\n"
255
+ f"Then run briefloop finalize --config {workspace_path}/config.yaml.\n"
256
+ f"After finalize writes reader-facing artifacts, run briefloop gates check --workspace {workspace_path} --stage finalize --brief {workspace_path}/output/brief.md, then run briefloop state finalize-complete --workspace {workspace_path} --reason \"Reader-facing artifacts passed finalize checks.\"\n"
257
+ "finalize is not a quality-gate executor.\n"
258
+ "Optionally run briefloop provenance build/show/validate after runtime state exists for an audit/debug projection; it is not semantic proof."
259
+ ),
260
+ ))
261
+
262
+ notes = [
263
+ "Hermes cron sessions are fresh sessions; every job attaches the BriefLoop skill and sets an absolute workdir.",
264
+ "The daily job is intentionally source-only so weekly/monthly jobs can synthesize from a stable cache.",
265
+ "For low-cost frequent polling, convert the daily job to a wakeAgent/script gate in Hermes after the source pattern stabilizes.",
266
+ ]
267
+ return HermesCronPlan(
268
+ version="v0.11.12",
269
+ workspace=str(workspace_path),
270
+ project_name=summary["name"],
271
+ cadences=resolved_cadences,
272
+ cache_dir=str(cache_dir),
273
+ jobs=jobs,
274
+ notes=notes,
275
+ )
276
+
277
+
278
+ def render_hermes_cron_commands(plan: HermesCronPlan) -> str:
279
+ lines: list[str] = []
280
+ for job in plan.jobs:
281
+ parts = [
282
+ "hermes",
283
+ "cron",
284
+ "create",
285
+ job.schedule,
286
+ job.prompt,
287
+ ]
288
+ for skill in job.skills:
289
+ parts.extend(["--skill", skill])
290
+ parts.extend(["--workdir", job.workdir])
291
+ parts.extend(["--name", job.name])
292
+ if job.profile:
293
+ parts.extend(["--profile", job.profile])
294
+ if job.deliver and job.deliver != "local":
295
+ parts.extend(["--deliver", job.deliver])
296
+ lines.append(" ".join(shlex.quote(part) for part in parts))
297
+ return "\n\n".join(lines) + "\n"
298
+
299
+
300
+ def render_hermes_cron_markdown(plan: HermesCronPlan) -> str:
301
+ lines = [
302
+ "# Hermes Cron Plan",
303
+ "",
304
+ f"- Version: {plan.version}",
305
+ f"- Workspace: `{plan.workspace}`",
306
+ f"- Project: {plan.project_name}",
307
+ f"- Cadences: {', '.join(plan.cadences)}",
308
+ f"- Cache directory: `{plan.cache_dir}`",
309
+ "",
310
+ "## Jobs",
311
+ "",
312
+ ]
313
+ for job in plan.jobs:
314
+ lines.extend([
315
+ f"### {job.name}",
316
+ "",
317
+ f"- Schedule: `{job.schedule}`",
318
+ f"- Purpose: {job.purpose}",
319
+ f"- Workdir: `{job.workdir}`",
320
+ f"- Deliver: `{job.deliver}`",
321
+ f"- Skills: {', '.join(job.skills)}",
322
+ f"- Context from: {', '.join(job.context_from) if job.context_from else 'none'}",
323
+ "",
324
+ "Prompt:",
325
+ "",
326
+ "```text",
327
+ job.prompt,
328
+ "```",
329
+ "",
330
+ ])
331
+ lines.extend(["## Notes", ""])
332
+ for note in plan.notes:
333
+ lines.append(f"- {note}")
334
+ lines.append("")
335
+ return "\n".join(lines)
336
+
337
+
338
+ # The SKILL_MD template is intentionally short. Detailed role prompts live in
339
+ # `.agents/hermes-skills/multi-agent-brief-hermes/references/` so Hermes loads
340
+ # only the relevant contract for the current mode.
341
+ _SKILL_MD_TEMPLATE = '''---
342
+ name: multi-agent-brief-hermes
343
+ description: Use when running BriefLoop workspaces inside Hermes with delegate_task subagents, source cache, cron scheduling, and deterministic CLI controls.
344
+ version: 0.11.12
345
+ author: multi-agent-brief-workflow
346
+ license: MIT
347
+ platforms:
348
+ - linux
349
+ - macos
350
+ - windows
351
+ tags:
352
+ - hermes
353
+ - cron
354
+ - brief
355
+ - research
356
+ - workflow
357
+ - delegate_task
358
+ ---
359
+
360
+ # BriefLoop for Hermes
361
+
362
+ Use this skill for a Hermes-native delegated BriefLoop run. Hermes is the
363
+ Orchestrator main agent; Hermes `delegate_task` children draft role-owned
364
+ artifacts, while BriefLoop CLI transactions validate, freeze, gate, and render.
365
+
366
+ ## Read First
367
+
368
+ - Delegated run sequence: `references/delegate-task-sequence.md`
369
+ - Source cache mode: `references/source-cache-contract.md`
370
+ - Cron usage: `references/cron-patterns.md`
371
+ - Contracts: `configs/orchestrator_contract.yaml`, `configs/stage_specs.yaml`,
372
+ `configs/artifact_contracts.yaml`, `configs/policy_packs/default.yaml`
373
+
374
+ ## Operating Model
375
+
376
+ Parent control loop: read workspace context -> read contracts -> identify next
377
+ stage -> delegate a specialist or Python tool -> check the expected artifact ->
378
+ decide `continue`, `retry_stage`, `delegate_repair`, `request_human_review`,
379
+ `block_run`, or `finalize`.
380
+
381
+ Runtime files to inspect, not hand-edit:
382
+
383
+ - `output/intermediate/runtime_manifest.json`
384
+ - `output/intermediate/workflow_state.json`
385
+ - `output/intermediate/artifact_registry.json`
386
+ - `output/intermediate/event_log.jsonl`
387
+ - `output/intermediate/audience_profile_snapshot.md`
388
+ - `output/intermediate/orchestrator_control_switchboard.json`
389
+ - `output/intermediate/control_selections.json`
390
+ - `output/intermediate/feedback_issues.json`
391
+ - `output/intermediate/repair_plan.json`
392
+ - `output/intermediate/gates/auditor_quality_gate_report.json`
393
+ - `output/intermediate/gates/finalize_quality_gate_report.json`
394
+ - `output/intermediate/quality_gate_report.json`
395
+ - `output/intermediate/provenance_graph.json`
396
+
397
+ Use `briefloop controls select`; Selection is not execution.
398
+ Use feedback commands as `feedback ingest/plan/resolve/show/validate`, gate
399
+ commands as `gates check/show/validate`, and provenance commands as
400
+ `provenance build/show/validate`.
401
+ Do not treat `audience_profile.md` as evidence.
402
+
403
+ ## Setup Workflow
404
+
405
+ Preferred Path: Hermes Plugin from `integrations/hermes-plugin/mabw`.
406
+
407
+ ```text
408
+ /mabw <workspace>
409
+ -> mabw_create_onboarding
410
+ -> mabw_init_workspace
411
+ -> mabw_run_handoff
412
+ -> read agent_handoff.md
413
+ -> continue delegated workflow
414
+ ```
415
+
416
+ Fallback: chat-to-JSON onboarding. Collect brief profile in chat, validate with
417
+ `briefloop onboard --validate onboarding.json`, initialize with
418
+ `briefloop init <workspace> --from-onboarding onboarding.json`, then run
419
+ `briefloop run --workspace <workspace>`. Do not call `briefloop run` again mid-pipeline; use status, state, gates, and repair commands.
420
+
421
+ Project is cloned and ready.
422
+ I can continue generating the brief inside Hermes with delegate_task children.
423
+
424
+ ## Daily Source Cache Workflow
425
+
426
+ For cache-only jobs, read workspace `config.yaml`, `sources.yaml`, and `user.md`,
427
+ write `input/hermes_cache/YYYY-MM-DD.json`, use `hermes_daily_cache`, report item
428
+ count and source gaps, then stop. Details: `references/source-cache-contract.md`.
429
+
430
+ ## Hermes-native Delegated Brief Workflow
431
+
432
+ Parent Orchestration is summarized here; role details live in
433
+ `references/delegate-task-sequence.md`.
434
+
435
+ Roles: scout, screener, claim-ledger, analyst, editor, auditor, finalize.
436
+ Sections: Scout child, Screener child, Claim-ledger child, Analyst child, Editor child, Auditor child. source_url only for HTTP(S) URLs.
437
+
438
+ batch delegation with up to 3 scout children is runtime-internal only: child
439
+ outputs are scratch/intermediate runtime material, not workflow artifacts. The
440
+ parent must join chunk outputs deterministically before writing `candidate_claims.json`; stable ordering must use source identity, source path or URL, source date, topic, and evidence text, not child completion order. do not silently drop chunk-level outputs. Only the final joined
441
+ `candidate_claims.json` and, in default topology, `screened_candidates.json`
442
+ count for stage completion. In default topology, do not delegate Screener and do not call `state stage-complete --stage screener`.
443
+
444
+ If runtime WebSearch reports `Did 0 searches`, or every query returns an empty result set, stop and request human review. Do not switch to source-planner or
445
+ continue with stale sources.
446
+
447
+ Atomic graph boundary: `atomic_claim_graph.json` is an optional experimental
448
+ structural decomposition aid, not source evidence or proof of support. If it is
449
+ absent or invalid, do not repair it. Do not create, edit, rewrite, repair, or
450
+ extend it. Do not cite atom IDs in reader-facing prose or introduce material
451
+ atoms absent from the frozen Claim Ledger.
452
+
453
+ Required success-path ordering: gates check + state check + state stage-complete.
454
+
455
+ ```bash
456
+ briefloop state freeze-claim-ledger --workspace <workspace>
457
+ briefloop state stage-complete --workspace <workspace> --stage claim-ledger --reason "Claim Ledger frozen from claim drafts."
458
+ #### 4. Analyst child
459
+ briefloop gates check --workspace <workspace> --stage auditor
460
+ briefloop state check --workspace <workspace> --strict
461
+ briefloop state stage-complete --workspace <workspace> --stage auditor --reason "Audit and quality gates passed."
462
+ briefloop finalize --config <workspace>/config.yaml
463
+ briefloop gates check --workspace <workspace> --stage finalize --brief <workspace>/output/brief.md
464
+ briefloop state finalize-complete --workspace <workspace> --reason "Reader-facing artifacts passed finalize checks."
465
+ ```
466
+
467
+ Audit warnings, overstatement findings, support-calibration findings, and
468
+ quality-gate findings do not authorize direct edits to frozen artifacts. Use
469
+ `briefloop repair route`, `briefloop repair start`, and `briefloop repair
470
+ complete` or choose `request_human_review` / `block_run`.
471
+
472
+ Formatter/finalize reads `output/intermediate/audited_brief.md` as frozen input;
473
+ route repair to Editor if wording changes are needed. `finalize` is not a quality-gate executor. Provenance projection is not semantic proof.
474
+ '''
475
+
476
+ def render_hermes_skill() -> str:
477
+ return _SKILL_MD_TEMPLATE
478
+
479
+
480
+ def render_hermes_setup_success(
481
+ *,
482
+ repo: str | Path,
483
+ venv: str | Path,
484
+ workspace: str | Path,
485
+ version: str = "v0.11.12",
486
+ doctor_status: str = "passed",
487
+ ) -> str:
488
+ return f"""Project is cloned and ready.
489
+
490
+ Repository: {repo}
491
+ Virtual environment: {venv}
492
+ Workspace: {workspace}
493
+ Version: {version}
494
+ Doctor: {doctor_status}
495
+
496
+ I can continue generating the brief inside Hermes with the Orchestrator main agent. Recommended next steps:
497
+
498
+ briefloop hermes install-skill
499
+ briefloop hermes prompt --config {workspace}/config.yaml
500
+
501
+ Then use the generated prompt in Hermes to run the delegated brief workflow.
502
+ """
503
+
504
+
505
+ def render_hermes_prompt(
506
+ *,
507
+ workspace: str | Path,
508
+ repo_workdir: str | Path,
509
+ venv_path: str | Path,
510
+ ) -> str:
511
+ workspace = str(Path(workspace).resolve())
512
+ repo = str(Path(repo_workdir).resolve())
513
+ venv = str(Path(venv_path).resolve())
514
+ contract_refs = contract_reference_bullets()
515
+ return f"""Use the multi-agent-brief-hermes skill to run a Hermes-native delegated brief workflow for this workspace.
516
+
517
+ Repository: {repo}
518
+ Workspace: {workspace}
519
+ Venv activate: source {venv}
520
+
521
+ You are the Hermes Orchestrator main agent. Read shared contract references, identify the next stage, delegate specialist child tasks or Python tools, check expected artifacts, and decide continue / retry_stage / delegate_repair / request_human_review / block_run / finalize.
522
+
523
+ Contract references:
524
+ {contract_refs}
525
+
526
+ Runtime state files:
527
+ - output/intermediate/runtime_manifest.json
528
+ - output/intermediate/workflow_state.json
529
+ - output/intermediate/artifact_registry.json
530
+ - output/intermediate/event_log.jsonl
531
+
532
+ Audience memory snapshot:
533
+ - output/intermediate/audience_profile_snapshot.md
534
+
535
+ Read the snapshot at run start, summarize relevant taste guidance for delegated roles, and use that summary as runtime context. Do not treat audience_profile.md as source evidence, and do not use mid-run profile edits until the next run.
536
+
537
+ Control switchboard files:
538
+ - output/intermediate/orchestrator_control_switchboard.json
539
+ - output/intermediate/control_selections.json
540
+
541
+ Read the switchboard after handoff and record enable/defer/reject choices with briefloop controls select. Selection is not execution; explicitly run selected controls afterward.
542
+
543
+ Optional feedback state files:
544
+ - output/intermediate/feedback_issues.json
545
+ - output/intermediate/repair_plan.json
546
+ - output/intermediate/delta_audit_report.json
547
+
548
+ Optional quality gate state files:
549
+ - output/intermediate/gates/auditor_quality_gate_report.json
550
+ - output/intermediate/gates/finalize_quality_gate_report.json
551
+ - output/intermediate/quality_gate_report.json (legacy/latest projection)
552
+
553
+ Optional provenance projection files:
554
+ - output/intermediate/provenance_graph.json
555
+
556
+ Orchestrator loop: {ORCHESTRATOR_LOOP}
557
+
558
+ ## Preferred: Hermes Plugin
559
+
560
+ If the BriefLoop Hermes plugin is installed and enabled, use the plugin path:
561
+
562
+ ```text
563
+ /mabw {workspace}
564
+ → mabw_create_onboarding (if workspace is new)
565
+ → mabw_init_workspace
566
+ → mabw_run_handoff
567
+ → read agent_handoff.md
568
+ → continue delegated workflow
569
+ ```
570
+
571
+ Install from the BriefLoop repo:
572
+
573
+ ```bash
574
+ cp -R integrations/hermes-plugin/mabw ~/.hermes/plugins/mabw
575
+ hermes plugins enable mabw
576
+ ```
577
+
578
+ ## Fallback: chat-to-JSON onboarding
579
+
580
+ If the plugin is not available and this workspace does not yet have config.yaml:
581
+
582
+ 1. Collect brief profile in chat — ask for company, industry, task objective, audience, language, cadence, source style, output style, must-watch topics, excluded sources, and source/search mode. Accept natural-language answers and confirm defaults.
583
+ 2. Write onboarding.json from the collected answers.
584
+ 3. Validate with: briefloop onboard --validate onboarding.json
585
+ 4. Create the workspace: briefloop init <workspace> --from-onboarding onboarding.json
586
+ 5. Create runtime handoff: briefloop run --workspace <workspace>
587
+ 6. Read agent_handoff.md and continue with the delegated workflow below.
588
+
589
+ ## Existing workspace: delegated brief run
590
+
591
+ As the Hermes Orchestrator main agent, execute:
592
+
593
+ 1. Read contract references:
594
+ - configs/orchestrator_contract.yaml
595
+ - configs/stage_specs.yaml
596
+ - configs/artifact_contracts.yaml
597
+ - configs/policy_packs/default.yaml
598
+
599
+ 2. Read runtime state files:
600
+ - output/intermediate/runtime_manifest.json
601
+ - output/intermediate/workflow_state.json
602
+ - output/intermediate/artifact_registry.json
603
+ - output/intermediate/event_log.jsonl
604
+
605
+ 3. Read audience memory snapshot:
606
+ - output/intermediate/audience_profile_snapshot.md
607
+ Summarize relevant taste guidance for delegated roles. Do not treat the profile as source evidence or as a correctness contract.
608
+
609
+ 4. Read the Orchestrator control switchboard:
610
+ - output/intermediate/orchestrator_control_switchboard.json
611
+ Record control choices with briefloop controls select. Selection is not execution.
612
+
613
+ 5. Run doctor:
614
+ briefloop doctor --config {workspace}/config.yaml
615
+
616
+ 6. If source discovery is configured:
617
+ briefloop sources decide --config {workspace}/config.yaml
618
+ If runtime WebSearch reports `Did 0 searches`, or every query returns an empty result set, stop and request human review. Do not switch to source-planner or continue with stale sources.
619
+
620
+ 7. If non-text input files are present:
621
+ briefloop inputs extract --config {workspace}/config.yaml
622
+
623
+ 8. If input governance is available:
624
+ briefloop inputs classify --config {workspace}/config.yaml
625
+
626
+ 9. Refresh runtime state without running stages:
627
+ briefloop state check --workspace {workspace}
628
+
629
+ 10. If audit findings or human feedback exist, structure them without running repair:
630
+ briefloop feedback ingest --workspace {workspace} --feedback <path> --source human|audit
631
+ briefloop feedback plan --workspace {workspace}
632
+ briefloop feedback resolve --workspace {workspace} --issue-id <id> --repair-plan-id <id> --reason <reason>
633
+ briefloop feedback show --workspace {workspace} --json
634
+ briefloop feedback validate --workspace {workspace}
635
+
636
+ 11. Repair guidance is bounded runtime guidance, not an automatic trajectory regulator. If the same stage has already needed roughly three retry/repair rounds, prefer request_human_review or block_run; if a repair would touch more than two sections, narrow the scope before delegating or request human review.
637
+
638
+ 12. Delegate scout child via delegate_task:
639
+ Goal: "Extract candidate reportable items for a BriefLoop brief; in default topology, screen them in the same Scout stage"
640
+ Write: output/intermediate/candidate_claims.json
641
+ Default topology also writes: output/intermediate/screened_candidates.json
642
+ Source identity: source_url is only for HTTP(S) URLs; use source_path for local/package sources. Preserve source_title/source_name, publisher, source_category, source_type, source dates, and evidence text.
643
+ toolsets: ["file", "terminal", "web"]
644
+
645
+ 13. If role_topology is `strict`, after candidate_claims.json exists and is non-empty, delegate screener child. If role_topology is `default`, Scout must already have written screened_candidates.json and the screener stage is satisfied by topology:
646
+ Do not delegate Screener and do not call `state stage-complete --stage screener` in default topology.
647
+ Goal: "Screen and rank BriefLoop candidate claims"
648
+ Input: output/intermediate/candidate_claims.json
649
+ Write: output/intermediate/screened_candidates.json
650
+ toolsets: ["file", "terminal"]
651
+
652
+ 14. After screened_candidates.json exists, delegate claim-ledger child:
653
+ Goal: "Build the BriefLoop Claim Ledger"
654
+ Input: output/intermediate/screened_candidates.json
655
+ Write: output/intermediate/claim_drafts.json
656
+ Preserve source_url/source_path, source_title/source_name, publisher, source_category, source_type, published_at/retrieved_at, and evidence text. Never put titles, source names, source IDs, search queries, or local paths in source_url.
657
+ toolsets: ["file", "terminal"]
658
+
659
+ 15. After claim_drafts.json exists, freeze the Claim Ledger, confirm claim_ledger.json exists, and record claim-ledger completion before delegating Analyst:
660
+ briefloop state freeze-claim-ledger --workspace {workspace}
661
+ briefloop state stage-complete --workspace {workspace} --stage claim-ledger --reason "Claim Ledger frozen from claim drafts."
662
+
663
+ 16. Then delegate analyst child:
664
+ Goal: "Draft the audited BriefLoop brief"
665
+ Inputs: user.md and output/intermediate/claim_ledger.json
666
+ Write: output/intermediate/audited_brief.md as the Analyst working draft
667
+ Optional atomic graph boundary: if output/intermediate/atomic_claim_graph.json is present and valid, use it only as an optional experimental structural decomposition aid for frozen Claim Ledger claims; it is not source evidence or proof of support. Do not cite atom IDs, create/edit/repair/extend the graph, or introduce material atoms absent from the frozen Claim Ledger and valid graph.
668
+ toolsets: ["file", "terminal"]
669
+
670
+ 17. After analyst stage-complete freezes analyst_draft_snapshot.md, delegate editor / Delivery Editor child:
671
+ Goal: "Polish the audited BriefLoop brief without adding facts"
672
+ Inputs: output/intermediate/analyst_draft_snapshot.md and output/intermediate/audited_brief.md
673
+ Write: output/intermediate/audited_brief.md as the Editor-owned final auditable brief
674
+ Optional atomic graph boundary: if output/intermediate/atomic_claim_graph.json is present and valid, use it only as an optional experimental structural decomposition aid; if it is absent or invalid, do not repair it. Do not create/edit/repair/extend the graph, cite atom IDs, or introduce material atoms absent from the frozen Claim Ledger and valid graph.
675
+ toolsets: ["file", "terminal"]
676
+
677
+ 18. After editor completes, delegate auditor child:
678
+ Goal: "Audit the BriefLoop brief against the Claim Ledger"
679
+ Inputs: output/intermediate/audited_brief.md and output/intermediate/claim_ledger.json
680
+ Write: output/intermediate/audit_report.json
681
+ toolsets: ["file", "terminal"]
682
+
683
+ 19. After audit_report.json exists, select and run deterministic quality gates, then refresh runtime state:
684
+ briefloop controls select --workspace {workspace} --control quality_gates --selection enable --reason "Use quality gates before finalize."
685
+ briefloop gates check --workspace {workspace} --stage auditor
686
+ briefloop state check --workspace {workspace} --strict
687
+
688
+ 20. If state is not blocked, record the auditor completion:
689
+ briefloop state stage-complete --workspace {workspace} --stage auditor --reason "Audit and quality gates passed."
690
+
691
+ 21. If state is blocked by owner-stage artifact repair, run `briefloop repair route --workspace {workspace}` and `briefloop repair start --workspace {workspace}`. Delegate only the repair_owner role and allow edits only to allowed_artifacts, then run `briefloop repair complete --workspace {workspace} --reason "<reason>"` and rerun downstream stages from must_rerun_from. Otherwise choose request_human_review or block_run. Audit warnings, overstatement findings, support-calibration findings, and quality-gate findings do not authorize direct edits to frozen artifacts. Do not finalize.
692
+
693
+ 22. Run finalize only after the gates/state completion path passes. finalize is not a quality-gate executor:
694
+ briefloop finalize --config {workspace}/config.yaml
695
+
696
+ 23. After finalize writes delivery artifacts under output/delivery/, verify completion:
697
+ briefloop gates check --workspace {workspace} --stage finalize --brief {workspace}/output/brief.md
698
+ briefloop state finalize-complete --workspace {workspace} --reason "Reader-facing artifacts passed finalize checks."
699
+
700
+ 24. Optional audit/debug projection after runtime state exists:
701
+ briefloop provenance build --workspace {workspace}
702
+ briefloop provenance show --workspace {workspace} --json
703
+ briefloop provenance validate --workspace {workspace}
704
+ Provenance projection is not semantic proof and is not required to finalize.
705
+
706
+ 25. Report artifact paths, audit status, quality gate status, switchboard selections, and optional provenance_graph.json when created.
707
+
708
+ For each delegate_task call, write complete goal and context with the workspace path, input paths, and output paths fully specified. After each child returns, verify the expected artifact exists and is non-empty before selecting continue, retry_stage, delegate_repair, request_human_review, block_run, or finalize.
709
+
710
+ Expected artifacts:
711
+ - {workspace}/output/intermediate/candidate_claims.json
712
+ - {workspace}/output/intermediate/screened_candidates.json
713
+ - {workspace}/output/intermediate/claim_ledger.json
714
+ - {workspace}/output/intermediate/audited_brief.md
715
+ - {workspace}/output/intermediate/audit_report.json
716
+ - {workspace}/output/delivery/brief.md
717
+ """
718
+
719
+
720
+ def _find_hermes_skill_dirs() -> list[Path]:
721
+ home = Path.home()
722
+ candidates = [
723
+ home / ".hermes" / "skills",
724
+ home / ".config" / "hermes" / "skills",
725
+ home / "hermes" / "skills",
726
+ ]
727
+ return [d for d in candidates if d.exists()]
728
+
729
+
730
+ def install_hermes_skill(target_dir: str | Path | None = None) -> dict[str, Any]:
731
+ skill_content = render_hermes_skill()
732
+ target = Path(target_dir) if target_dir else None
733
+
734
+ if target is None:
735
+ dirs = _find_hermes_skill_dirs()
736
+ if dirs:
737
+ target = dirs[0] / "multi-agent-brief-hermes"
738
+ else:
739
+ target = Path(".agents/hermes-skills/multi-agent-brief-hermes")
740
+
741
+ target.mkdir(parents=True, exist_ok=True)
742
+ skill_path = target / "SKILL.md"
743
+ skill_path.write_text(skill_content, encoding="utf-8")
744
+
745
+ return {
746
+ "installed": True,
747
+ "skill_path": str(skill_path.resolve()),
748
+ "skill_dir": str(target.resolve()),
749
+ "auto_detected": target_dir is None and bool(_find_hermes_skill_dirs()),
750
+ "hint": (
751
+ "Copy this skill into ~/.hermes/skills/ or configure Hermes skills.external_dirs"
752
+ if target_dir is None and not _find_hermes_skill_dirs()
753
+ else ""
754
+ ),
755
+ }
756
+
757
+
758
+ def write_json(path: Path, data: dict[str, Any]) -> None:
759
+ path.parent.mkdir(parents=True, exist_ok=True)
760
+ path.write_text(json.dumps(data, ensure_ascii=False, indent=2), encoding="utf-8")
761
+
762
+
763
+ def sync_cached_package_source(
764
+ *,
765
+ sources_path: str | Path,
766
+ cache_dir: str = "input/hermes_cache",
767
+ dry_run: bool = False,
768
+ ) -> dict[str, Any]:
769
+ try:
770
+ import yaml
771
+ except ModuleNotFoundError as exc: # pragma: no cover
772
+ raise RuntimeError("PyYAML is required to update sources.yaml") from exc
773
+
774
+ path = Path(sources_path)
775
+ if not path.exists():
776
+ raise FileNotFoundError(f"sources.yaml not found: {path}")
777
+
778
+ data = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
779
+ if not isinstance(data, dict):
780
+ raise ValueError(f"sources.yaml must be a mapping: {path}")
781
+
782
+ strategy = data.setdefault("source_strategy", {})
783
+ enabled = strategy.setdefault("enabled_providers", [])
784
+ if isinstance(enabled, str):
785
+ enabled = [enabled]
786
+ if not isinstance(enabled, list):
787
+ raise ValueError("source_strategy.enabled_providers must be a list")
788
+
789
+ changed = False
790
+ if "cached_package" not in enabled:
791
+ enabled.append("cached_package")
792
+ strategy["enabled_providers"] = enabled
793
+ changed = True
794
+
795
+ cached = data.setdefault("cached_package", {})
796
+ if cached.get("enabled") is not True:
797
+ cached["enabled"] = True
798
+ changed = True
799
+
800
+ paths = cached.setdefault("paths", [])
801
+ if isinstance(paths, str):
802
+ paths = [paths]
803
+ if not isinstance(paths, list):
804
+ raise ValueError("cached_package.paths must be a list")
805
+ if cache_dir not in paths:
806
+ paths.append(cache_dir)
807
+ changed = True
808
+ cached["paths"] = paths
809
+
810
+ formats = cached.setdefault("formats", ["json", "md", "txt"])
811
+ if isinstance(formats, str):
812
+ formats = [formats]
813
+ for fmt in ["json", "md", "txt"]:
814
+ if fmt not in formats:
815
+ formats.append(fmt)
816
+ changed = True
817
+ cached["formats"] = formats
818
+
819
+ if changed and not dry_run:
820
+ path.write_text(
821
+ yaml.safe_dump(data, sort_keys=False, default_flow_style=False, allow_unicode=True),
822
+ encoding="utf-8",
823
+ )
824
+
825
+ return {
826
+ "changed": changed,
827
+ "sources_path": str(path),
828
+ "enabled_providers": enabled,
829
+ "cache_dir": cache_dir,
830
+ "formats": formats,
831
+ "dry_run": dry_run,
832
+ }