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,451 @@
1
+ """Deterministic Improvement Ledger projection and runtime snapshot helpers."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import hashlib
6
+ import json
7
+ import os
8
+ import re
9
+ import uuid
10
+ from dataclasses import asdict, dataclass
11
+ from pathlib import Path
12
+ from typing import Any
13
+
14
+ from multi_agent_brief.improvement.contract import (
15
+ LEDGER_RELATIVE_PATH,
16
+ read_ledger_text,
17
+ supersedes_id,
18
+ )
19
+ from multi_agent_brief.improvement.product_definition import (
20
+ ProductDefinitionDecision,
21
+ classify_ledger_entry_materialization,
22
+ )
23
+ from multi_agent_brief.improvement.state import ImprovementLedgerError
24
+
25
+
26
+ IMPROVEMENT_MEMORY_SCHEMA = "multi-agent-brief-improvement-memory/v1"
27
+ IMPROVEMENT_MEMORY_FILE = "improvement/memory.md"
28
+ IMPROVEMENT_MEMORY_SNAPSHOT_FILE = "output/intermediate/improvement_memory_snapshot.md"
29
+ MAX_INLINE_IDENTIFIER_LENGTH = 200
30
+ _CONTROL_CHAR_RE = re.compile(r"[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]")
31
+ _WINDOWS_ABSOLUTE_RE = re.compile(r"\b[A-Za-z]:[\\/]")
32
+ _TOKEN_PATTERNS = [
33
+ re.compile(r"sk-[A-Za-z0-9_-]{16,}"),
34
+ re.compile(r"ghp_[A-Za-z0-9_]{16,}"),
35
+ re.compile(r"xox[baprs]-[A-Za-z0-9-]{10,}"),
36
+ re.compile(r"AKIA[0-9A-Z]{16}"),
37
+ re.compile(r"\b[A-Za-z0-9_-]{40,}\b"),
38
+ ]
39
+ _FORBIDDEN_PATH_FRAGMENTS = ("/Users/", "/home/", "/var/", "file://")
40
+ _INJECTION_PHRASES = ("system:", "developer:", "assistant:", "ignore previous", "ignore all previous")
41
+
42
+
43
+ @dataclass(frozen=True)
44
+ class SkippedImprovementEntry:
45
+ entry_id: str
46
+ reason_code: str
47
+ message: str
48
+
49
+
50
+ @dataclass(frozen=True)
51
+ class ImprovementMemoryProjection:
52
+ workspace: Path
53
+ ledger_path: Path
54
+ memory_path: Path
55
+ ledger_sha256: str | None
56
+ memory_sha256: str
57
+ selected_entry_ids: list[str]
58
+ eligible_count: int
59
+ skipped_entries: list[SkippedImprovementEntry]
60
+ warnings: list[SkippedImprovementEntry]
61
+ memory_text: str
62
+
63
+ def to_dict(self) -> dict[str, Any]:
64
+ return {
65
+ "ok": True,
66
+ "workspace": str(self.workspace),
67
+ "ledger_path": str(self.ledger_path),
68
+ "memory_path": IMPROVEMENT_MEMORY_FILE,
69
+ "ledger_sha256": self.ledger_sha256,
70
+ "memory_sha256": self.memory_sha256,
71
+ "selected_entry_ids": list(self.selected_entry_ids),
72
+ "eligible_count": self.eligible_count,
73
+ "skipped_entries": [asdict(item) for item in self.skipped_entries],
74
+ "warnings": [asdict(item) for item in self.warnings],
75
+ }
76
+
77
+
78
+ @dataclass(frozen=True)
79
+ class ImprovementMemoryFreezeResult:
80
+ projection: ImprovementMemoryProjection
81
+ manifest_improvement: dict[str, Any]
82
+ snapshot_path: str | None
83
+ snapshot_sha256: str | None
84
+ snapshot_created_or_changed: bool
85
+
86
+ def to_dict(self) -> dict[str, Any]:
87
+ payload = self.projection.to_dict()
88
+ payload.update({
89
+ "manifest_improvement": dict(self.manifest_improvement),
90
+ "snapshot_path": self.snapshot_path,
91
+ "snapshot_sha256": self.snapshot_sha256,
92
+ "snapshot_created_or_changed": self.snapshot_created_or_changed,
93
+ })
94
+ return payload
95
+
96
+
97
+ def improvement_memory_path(workspace: str | Path) -> Path:
98
+ return Path(workspace).expanduser().resolve() / IMPROVEMENT_MEMORY_FILE
99
+
100
+
101
+ def improvement_memory_snapshot_path(workspace: str | Path) -> Path:
102
+ return Path(workspace).expanduser().resolve() / IMPROVEMENT_MEMORY_SNAPSHOT_FILE
103
+
104
+
105
+ def rebuild_improvement_memory(*, workspace: str | Path) -> dict[str, Any]:
106
+ """Project the ledger into improvement/memory.md only."""
107
+ ws = _require_workspace(workspace)
108
+ projection = _build_projection(ws)
109
+ _write_text_if_changed(projection.memory_path, projection.memory_text)
110
+ return projection.to_dict()
111
+
112
+
113
+ def freeze_improvement_memory_for_run(
114
+ *,
115
+ workspace: str | Path,
116
+ run_id: str,
117
+ ) -> ImprovementMemoryFreezeResult:
118
+ """Recompute memory and freeze it for the current runtime run."""
119
+ ws = _require_workspace(workspace)
120
+ _validate_runtime_identifier(run_id, label="run_id")
121
+ projection = _build_projection(ws)
122
+ _write_text_if_changed(projection.memory_path, projection.memory_text)
123
+
124
+ snapshot_path = improvement_memory_snapshot_path(ws)
125
+ snapshot_rel_path: str | None = None
126
+ snapshot_sha256: str | None = None
127
+ changed = False
128
+
129
+ if projection.selected_entry_ids:
130
+ snapshot_text = _snapshot_text(projection=projection, run_id=run_id)
131
+ new_sha = sha256_text(snapshot_text)
132
+ old_sha = sha256_file(snapshot_path) if snapshot_path.exists() else None
133
+ if old_sha != new_sha:
134
+ _write_text_atomic(snapshot_path, snapshot_text)
135
+ changed = True
136
+ snapshot_rel_path = IMPROVEMENT_MEMORY_SNAPSHOT_FILE
137
+ snapshot_sha256 = new_sha
138
+ else:
139
+ if snapshot_path.exists():
140
+ snapshot_path.unlink()
141
+
142
+ manifest_block = {
143
+ "ledger_sha256": projection.ledger_sha256,
144
+ "memory_sha256": projection.memory_sha256,
145
+ "snapshot_path": snapshot_rel_path,
146
+ "snapshot_sha256": snapshot_sha256,
147
+ "materialized_entry_ids": list(projection.selected_entry_ids),
148
+ }
149
+ _update_runtime_manifest_improvement(ws, manifest_block)
150
+ return ImprovementMemoryFreezeResult(
151
+ projection=projection,
152
+ manifest_improvement=manifest_block,
153
+ snapshot_path=snapshot_rel_path,
154
+ snapshot_sha256=snapshot_sha256,
155
+ snapshot_created_or_changed=changed,
156
+ )
157
+
158
+
159
+ def sha256_text(text: str) -> str:
160
+ return hashlib.sha256(_text_bytes(text)).hexdigest()
161
+
162
+
163
+ def sha256_file(path: Path) -> str:
164
+ digest = hashlib.sha256()
165
+ with path.open("rb") as handle:
166
+ for chunk in iter(lambda: handle.read(1024 * 1024), b""):
167
+ digest.update(chunk)
168
+ return digest.hexdigest()
169
+
170
+
171
+ def _build_projection(workspace: Path) -> ImprovementMemoryProjection:
172
+ ledger_path = workspace / LEDGER_RELATIVE_PATH
173
+ ledger_sha = sha256_file(ledger_path) if ledger_path.exists() else None
174
+ text = ledger_path.read_text(encoding="utf-8") if ledger_path.exists() else ""
175
+ read_result = read_ledger_text(text)
176
+ if read_result.diagnostics:
177
+ raise ImprovementLedgerError(
178
+ "Improvement ledger is not valid for memory projection.",
179
+ details={"diagnostics": [asdict(item) for item in read_result.diagnostics]},
180
+ )
181
+
182
+ selected: list[dict[str, Any]] = []
183
+ skipped: list[SkippedImprovementEntry] = []
184
+ warnings: list[SkippedImprovementEntry] = []
185
+ superseded_by = _superseded_by_map(read_result.current_entries)
186
+ for entry_id, entry in sorted(read_result.current_entries.items()):
187
+ if entry.get("status") != "approved":
188
+ continue
189
+ superseders = superseded_by.get(entry_id) or []
190
+ if superseders:
191
+ skipped.append(SkippedImprovementEntry(
192
+ entry_id=entry_id,
193
+ reason_code="superseded_by_active_guidance",
194
+ message=f"Entry is superseded by {', '.join(superseders)}.",
195
+ ))
196
+ continue
197
+ decision = classify_ledger_entry_materialization(entry)
198
+ if decision.materializable:
199
+ selected.append(entry)
200
+ else:
201
+ skipped.append(_skipped(entry_id=entry_id, decision=decision))
202
+ target_id = supersedes_id(entry)
203
+ if target_id is not None and not decision.materializable:
204
+ warnings.append(SkippedImprovementEntry(
205
+ entry_id=entry_id,
206
+ reason_code="non_materializable_superseder_suppresses_target",
207
+ message=f"{entry_id} suppresses {target_id} but is not materializable.",
208
+ ))
209
+
210
+ memory_text = _memory_text(ledger_sha256=ledger_sha, entries=selected)
211
+ return ImprovementMemoryProjection(
212
+ workspace=workspace,
213
+ ledger_path=ledger_path,
214
+ memory_path=improvement_memory_path(workspace),
215
+ ledger_sha256=ledger_sha,
216
+ memory_sha256=sha256_text(memory_text),
217
+ selected_entry_ids=[str(entry["entry_id"]) for entry in selected],
218
+ eligible_count=len(selected),
219
+ skipped_entries=skipped,
220
+ warnings=warnings,
221
+ memory_text=memory_text,
222
+ )
223
+
224
+
225
+ def _memory_text(*, ledger_sha256: str | None, entries: list[dict[str, Any]]) -> str:
226
+ selected_ids = [str(entry["entry_id"]) for entry in entries]
227
+ selected_text = ", ".join(selected_ids) if selected_ids else "none"
228
+ lines = [
229
+ "<!-- mabw:improvement-memory",
230
+ f"schema: {IMPROVEMENT_MEMORY_SCHEMA}",
231
+ f"ledger_sha256: {ledger_sha256 or 'null'}",
232
+ f"entry_count: {len(entries)}",
233
+ f"selected_entry_ids: {selected_text}",
234
+ "-->",
235
+ "",
236
+ "# Improvement Memory",
237
+ "",
238
+ "- Runtime use: audience/taste guidance only.",
239
+ "- Not evidence, not a source, not Claim Ledger input, and not a repair instruction.",
240
+ "- Must not alter material facts, claims, citations, or source support.",
241
+ "",
242
+ "## Entries",
243
+ "",
244
+ ]
245
+ if not entries:
246
+ lines.extend(["No approved materializable improvement entries.", ""])
247
+ return "\n".join(lines)
248
+
249
+ for entry in entries:
250
+ change = entry.get("change") if isinstance(entry.get("change"), dict) else {}
251
+ lines.extend([
252
+ f"### {entry.get('entry_id')}",
253
+ "",
254
+ f"- Category: {change.get('category')}",
255
+ f"- Scope: {change.get('scope')}",
256
+ f"- Guidance: {change.get('guidance_text')}",
257
+ f"- {_source_line(entry)}",
258
+ "",
259
+ ])
260
+ return "\n".join(lines)
261
+
262
+
263
+ def _snapshot_text(*, projection: ImprovementMemoryProjection, run_id: str) -> str:
264
+ safe_run_id = _inline_identifier(run_id)
265
+ selected_text = ", ".join(projection.selected_entry_ids)
266
+ return "\n".join([
267
+ "<!-- mabw:improvement-memory-snapshot",
268
+ f"schema: {IMPROVEMENT_MEMORY_SCHEMA}",
269
+ f"run_id: {safe_run_id}",
270
+ f"ledger_sha256: {projection.ledger_sha256 or 'null'}",
271
+ f"memory_sha256: {projection.memory_sha256}",
272
+ f"selected_entry_ids: {selected_text}",
273
+ "-->",
274
+ "",
275
+ "# Improvement Memory Snapshot",
276
+ "",
277
+ f"- Run ID: {safe_run_id}",
278
+ f"- Source: {IMPROVEMENT_MEMORY_FILE}",
279
+ f"- Ledger SHA256: {projection.ledger_sha256 or 'null'}",
280
+ f"- Memory SHA256: {projection.memory_sha256}",
281
+ "- Runtime use: read this frozen snapshot only.",
282
+ "- Taste/audience guidance only; not evidence, not source, not Claim Ledger, and not repair instruction.",
283
+ "- Must not alter material facts, claims, citations, or source support.",
284
+ "- Mid-run ledger or memory edits apply to later runs only.",
285
+ "",
286
+ "## Captured Improvement Memory",
287
+ "",
288
+ projection.memory_text.rstrip(),
289
+ "",
290
+ ])
291
+
292
+
293
+ def _source_line(entry: dict[str, Any]) -> str:
294
+ approved_by = str(entry.get("approved_by") or "unknown")
295
+ approved_at = str(entry.get("approved_at") or "")
296
+ approved_date = approved_at.split("T", 1)[0] if approved_at else "unknown"
297
+ evidence = entry.get("source_evidence") or []
298
+ source_parts: list[str] = []
299
+ if isinstance(evidence, list):
300
+ for item in evidence:
301
+ if not isinstance(item, dict):
302
+ continue
303
+ if item.get("source_type") == "feedback_issue":
304
+ safe_run_id = _inline_identifier(item.get("run_id"))
305
+ safe_issue_id = _inline_identifier(item.get("issue_id"))
306
+ source_parts.append(_source_ref_with_runtime(
307
+ item,
308
+ base=f"run {safe_run_id} / issue {safe_issue_id}",
309
+ ))
310
+ elif item.get("source_type") == "human_feedback":
311
+ source_parts.append(_source_ref_with_runtime(item, base="human_feedback"))
312
+ source_text = ", ".join(sorted(set(source_parts))) or "unknown"
313
+ return f"approved_by: {approved_by} ({approved_date}) · source: {source_text}"
314
+
315
+
316
+ def _source_ref_with_runtime(item: dict[str, Any], *, base: str) -> str:
317
+ origin = item.get("origin") if isinstance(item.get("origin"), dict) else {}
318
+ runtime = origin.get("origin_runtime") if isinstance(origin, dict) else None
319
+ if runtime is None:
320
+ return base
321
+ return f"{base} / runtime: {_inline_identifier(runtime)}"
322
+
323
+
324
+ def _validate_runtime_identifier(value: str, *, label: str) -> None:
325
+ text = str(value or "").strip()
326
+ if not text:
327
+ raise ImprovementLedgerError(
328
+ f"{label} is required before freezing improvement memory.",
329
+ details={"label": label},
330
+ )
331
+ if _unsafe_inline_identifier(text):
332
+ raise ImprovementLedgerError(
333
+ f"{label} is not safe for improvement memory snapshot metadata.",
334
+ details={"label": label},
335
+ )
336
+
337
+
338
+ def _inline_identifier(value: Any) -> str:
339
+ text = str(value or "").strip()
340
+ if not text:
341
+ return "unknown"
342
+ if _unsafe_inline_identifier(text):
343
+ return "unsafe"
344
+ return text
345
+
346
+
347
+ def _unsafe_inline_identifier(text: str) -> bool:
348
+ lower = text.lower()
349
+ return (
350
+ len(text) > MAX_INLINE_IDENTIFIER_LENGTH
351
+ or "\n" in text
352
+ or "\r" in text
353
+ or text.lstrip().startswith("#")
354
+ or "```" in text
355
+ or "~~~" in text
356
+ or "<!--" in text
357
+ or "-->" in text
358
+ or bool(_CONTROL_CHAR_RE.search(text))
359
+ or bool(_WINDOWS_ABSOLUTE_RE.search(text))
360
+ or any(fragment.lower() in lower for fragment in _FORBIDDEN_PATH_FRAGMENTS)
361
+ or any(pattern.search(text) for pattern in _TOKEN_PATTERNS)
362
+ or any(phrase in lower for phrase in _INJECTION_PHRASES)
363
+ )
364
+
365
+
366
+ def _skipped(*, entry_id: str, decision: ProductDefinitionDecision) -> SkippedImprovementEntry:
367
+ return SkippedImprovementEntry(
368
+ entry_id=entry_id,
369
+ reason_code=decision.reason_code,
370
+ message=decision.message,
371
+ )
372
+
373
+
374
+ def _superseded_by_map(current_entries: dict[str, dict[str, Any]]) -> dict[str, list[str]]:
375
+ superseded: dict[str, list[str]] = {}
376
+ for entry_id, entry in sorted(current_entries.items()):
377
+ if entry.get("status") != "approved":
378
+ continue
379
+ target_id = supersedes_id(entry)
380
+ if target_id is None:
381
+ continue
382
+ superseded.setdefault(target_id, []).append(entry_id)
383
+ return {key: sorted(value) for key, value in superseded.items()}
384
+
385
+
386
+ def _update_runtime_manifest_improvement(workspace: Path, improvement: dict[str, Any]) -> None:
387
+ manifest_path = workspace / "output" / "intermediate" / "runtime_manifest.json"
388
+ if not manifest_path.exists():
389
+ raise ImprovementLedgerError(
390
+ "runtime_manifest.json is required before freezing improvement memory.",
391
+ details={"path": str(manifest_path)},
392
+ )
393
+ try:
394
+ manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
395
+ except json.JSONDecodeError as exc:
396
+ raise ImprovementLedgerError(
397
+ "runtime_manifest.json is not valid JSON.",
398
+ details={"path": str(manifest_path), "error": str(exc)},
399
+ ) from exc
400
+ if not isinstance(manifest, dict):
401
+ raise ImprovementLedgerError(
402
+ "runtime_manifest.json must contain an object.",
403
+ details={"path": str(manifest_path)},
404
+ )
405
+ manifest["improvement"] = improvement
406
+ _write_json_atomic(manifest_path, manifest)
407
+
408
+
409
+ def _require_workspace(workspace: str | Path) -> Path:
410
+ ws = Path(workspace).expanduser().resolve()
411
+ if not ws.exists():
412
+ raise ImprovementLedgerError(
413
+ f"Workspace does not exist: {ws}",
414
+ details={"workspace": str(ws)},
415
+ )
416
+ if not (ws / "config.yaml").exists():
417
+ raise ImprovementLedgerError(
418
+ f"Workspace config.yaml not found: {ws / 'config.yaml'}",
419
+ details={"workspace": str(ws)},
420
+ )
421
+ return ws
422
+
423
+
424
+ def _write_text_if_changed(path: Path, text: str) -> bool:
425
+ data = _text_bytes(text)
426
+ if path.exists() and path.read_bytes() == data:
427
+ return False
428
+ _write_text_atomic(path, text)
429
+ return True
430
+
431
+
432
+ def _write_text_atomic(path: Path, text: str) -> None:
433
+ path.parent.mkdir(parents=True, exist_ok=True)
434
+ tmp = path.with_name(f".{path.name}.{uuid.uuid4().hex}.tmp")
435
+ try:
436
+ tmp.write_bytes(_text_bytes(text))
437
+ os.replace(tmp, path)
438
+ finally:
439
+ try:
440
+ tmp.unlink(missing_ok=True)
441
+ except OSError:
442
+ pass
443
+
444
+
445
+ def _text_bytes(text: str) -> bytes:
446
+ return text.encode("utf-8")
447
+
448
+
449
+ def _write_json_atomic(path: Path, payload: dict[str, Any]) -> None:
450
+ text = json.dumps(payload, ensure_ascii=False, indent=2, sort_keys=True) + "\n"
451
+ _write_text_atomic(path, text)
@@ -0,0 +1,228 @@
1
+ """Product-definition guardrails for Improvement Ledger materialization.
2
+
3
+ This module is deliberately side-effect free. It separates audience guidance
4
+ from deterministic correctness, delivery, and repair findings before PR3 can
5
+ materialize approved ledger entries into runtime memory.
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ from dataclasses import asdict, dataclass
11
+ from pathlib import Path
12
+ from typing import Any
13
+
14
+
15
+ AUDIENCE_GUIDANCE_ISSUE_CATEGORIES = {
16
+ "audience_mismatch",
17
+ "tone",
18
+ "structure",
19
+ "length",
20
+ "source_presentation",
21
+ }
22
+
23
+ REPAIR_ONLY_ISSUE_CATEGORIES = {
24
+ "unsupported_claim",
25
+ "unsupported_affiliation_claim",
26
+ "missing_source",
27
+ "stale_source",
28
+ "freshness_required",
29
+ "metric_definition_missing",
30
+ "format_field_missing",
31
+ "source_link_format_noncompliant",
32
+ }
33
+
34
+ REPAIR_ONLY_FINDING_TYPES = set(REPAIR_ONLY_ISSUE_CATEGORIES)
35
+
36
+ TARGET_RELEVANCE_FINDING_TYPES = {
37
+ "target_relevance",
38
+ "target_relevance_failed",
39
+ "target_relevance_gap",
40
+ "target_priority_claim_missing_from_summary",
41
+ }
42
+
43
+ GATE_OR_AUDIT_SOURCES = {"audit", "gate", "quality_gate"}
44
+ QUALITY_GATE_CONTROL_FILES = {"quality_gate_report.json"}
45
+
46
+
47
+ @dataclass(frozen=True)
48
+ class ProductDefinitionDecision:
49
+ guidance_eligible: bool
50
+ action: str
51
+ classification: str
52
+ reason_code: str
53
+ message: str
54
+ materializable: bool
55
+ requires_product_definition_review: bool
56
+
57
+ def to_dict(self) -> dict[str, Any]:
58
+ return asdict(self)
59
+
60
+
61
+ def classify_improvement_source(
62
+ *,
63
+ source_type: str,
64
+ issue_category: str | None = None,
65
+ finding_type: str | None = None,
66
+ source: str | None = None,
67
+ control_file: str | None = None,
68
+ ) -> ProductDefinitionDecision:
69
+ """Classify whether an improvement source can become audience guidance."""
70
+ source_type_value = _normalize(source_type)
71
+ issue_category_value = _normalize(issue_category)
72
+ finding_type_value = _normalize(finding_type)
73
+ source_value = _normalize(source)
74
+ control_file_value = _basename(control_file)
75
+
76
+ if source_type_value == "human_feedback":
77
+ if issue_category_value == "other":
78
+ return _warn_other()
79
+ return _allow("human_feedback_guidance", "Human-authored guidance is eligible after ledger hygiene and approval.")
80
+
81
+ if source_type_value != "feedback_issue":
82
+ return _reject_rewrite(
83
+ "unknown_source_type",
84
+ "Only human_feedback and feedback_issue can source audience guidance proposals.",
85
+ classification="ambiguous_rewrite_required",
86
+ )
87
+
88
+ if issue_category_value in REPAIR_ONLY_ISSUE_CATEGORIES:
89
+ return _reject_rewrite(
90
+ "repair_only_issue_category",
91
+ "This feedback issue category is machine-checkable or repair-only; use feedback/repair for this run, or rewrite a persistent preference as explicit human_feedback guidance with --source-summary.",
92
+ classification="repair_only",
93
+ )
94
+
95
+ if finding_type_value in REPAIR_ONLY_FINDING_TYPES:
96
+ return _reject_rewrite(
97
+ "repair_only_finding_type",
98
+ "This finding type is machine-checkable or repair-only; use feedback/repair for this run, or rewrite a persistent preference as explicit human_feedback guidance with --source-summary.",
99
+ classification="repair_only",
100
+ )
101
+
102
+ if (
103
+ finding_type_value in TARGET_RELEVANCE_FINDING_TYPES
104
+ and (
105
+ source_value in GATE_OR_AUDIT_SOURCES
106
+ or control_file_value in QUALITY_GATE_CONTROL_FILES
107
+ )
108
+ ):
109
+ return _reject_rewrite(
110
+ "target_relevance_rewrite_required",
111
+ "Audit/gate target relevance findings mix coverage defects with possible audience preference. Use feedback/repair for this run; if there is a durable reader preference, rewrite it as explicit human_feedback guidance with --source-summary.",
112
+ classification="ambiguous_rewrite_required",
113
+ )
114
+
115
+ if issue_category_value == "other":
116
+ return _warn_other()
117
+
118
+ if issue_category_value in AUDIENCE_GUIDANCE_ISSUE_CATEGORIES:
119
+ return _allow("audience_feedback_issue", "Audience feedback issue can be used as evidence because the guidance text is still human-authored.")
120
+
121
+ if source_value == "human":
122
+ return _allow("human_feedback_issue", "Human feedback issue can be used as evidence because the guidance text is still human-authored.")
123
+
124
+ return _reject_rewrite(
125
+ "issue_requires_human_rewrite",
126
+ "This feedback issue is not clearly audience guidance. Use feedback/repair for this run, or rewrite a persistent preference as explicit human_feedback guidance with --source-summary.",
127
+ classification="ambiguous_rewrite_required",
128
+ )
129
+
130
+
131
+ def classify_ledger_entry_materialization(entry: dict[str, Any]) -> ProductDefinitionDecision:
132
+ """Classify a current ledger entry for future PR3 materialization."""
133
+ change = entry.get("change") if isinstance(entry.get("change"), dict) else {}
134
+ category = str(change.get("category") or "")
135
+ evidence = entry.get("source_evidence") or []
136
+ if not isinstance(evidence, list) or not evidence:
137
+ return _reject_rewrite(
138
+ "missing_source_evidence",
139
+ "Entry has no source evidence and cannot be materialized safely.",
140
+ classification="ambiguous_rewrite_required",
141
+ )
142
+
143
+ saw_warning: ProductDefinitionDecision | None = None
144
+ for item in evidence:
145
+ if not isinstance(item, dict):
146
+ return _reject_rewrite(
147
+ "invalid_source_evidence",
148
+ "Entry source evidence is invalid and cannot be materialized safely.",
149
+ classification="ambiguous_rewrite_required",
150
+ )
151
+ origin = item.get("origin") if isinstance(item.get("origin"), dict) else {}
152
+ source_type = _normalize(str(item.get("source_type") or ""))
153
+ if source_type == "feedback_issue" and not _has_feedback_issue_product_definition_origin(origin):
154
+ return _reject_rewrite(
155
+ "missing_feedback_issue_product_definition_origin",
156
+ "FeedbackIssue evidence needs product-definition origin metadata before materialization; review and rewrite as human_feedback guidance if this is a durable audience preference.",
157
+ classification="ambiguous_rewrite_required",
158
+ )
159
+ decision = classify_improvement_source(
160
+ source_type=source_type,
161
+ issue_category=str(origin.get("issue_category") or (category if source_type == "human_feedback" else "") or ""),
162
+ finding_type=str(origin.get("finding_type") or ""),
163
+ source=str(origin.get("issue_source") or ""),
164
+ control_file=str(origin.get("control_file") or ""),
165
+ )
166
+ if not decision.materializable:
167
+ return decision
168
+ if decision.action == "warn_other":
169
+ saw_warning = decision
170
+ return saw_warning or _allow("materializable_guidance", "Approved guidance is eligible for PR3 materialization.")
171
+
172
+
173
+ def _allow(reason_code: str, message: str) -> ProductDefinitionDecision:
174
+ return ProductDefinitionDecision(
175
+ guidance_eligible=True,
176
+ action="allow",
177
+ classification="audience_guidance",
178
+ reason_code=reason_code,
179
+ message=message,
180
+ materializable=True,
181
+ requires_product_definition_review=False,
182
+ )
183
+
184
+
185
+ def _warn_other() -> ProductDefinitionDecision:
186
+ return ProductDefinitionDecision(
187
+ guidance_eligible=True,
188
+ action="warn_other",
189
+ classification="audience_guidance",
190
+ reason_code="category_other",
191
+ message="category=other is allowed but should be reclassified when possible; it remains materializable after human approval.",
192
+ materializable=True,
193
+ requires_product_definition_review=False,
194
+ )
195
+
196
+
197
+ def _reject_rewrite(reason_code: str, message: str, *, classification: str) -> ProductDefinitionDecision:
198
+ return ProductDefinitionDecision(
199
+ guidance_eligible=False,
200
+ action="reject_with_rewrite_path",
201
+ classification=classification,
202
+ reason_code=reason_code,
203
+ message=message,
204
+ materializable=False,
205
+ requires_product_definition_review=True,
206
+ )
207
+
208
+
209
+ def _normalize(value: str | None) -> str:
210
+ if value is None:
211
+ return ""
212
+ return str(value).strip().lower().replace("-", "_")
213
+
214
+
215
+ def _basename(value: str | None) -> str:
216
+ if value is None:
217
+ return ""
218
+ text = str(value).strip()
219
+ if not text:
220
+ return ""
221
+ return Path(text).name.strip().lower()
222
+
223
+
224
+ def _has_feedback_issue_product_definition_origin(origin: dict[str, Any]) -> bool:
225
+ issue_category = _normalize(str(origin.get("issue_category") or ""))
226
+ issue_source = _normalize(str(origin.get("issue_source") or ""))
227
+ finding_type = _normalize(str(origin.get("finding_type") or ""))
228
+ return bool(issue_category and (issue_source or finding_type))