briefloop 0.11.12__tar.gz

briefloop-0.11.12/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 multi-agent-brief-workflow contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

briefloop-0.11.12/PKG-INFO

@@ -0,0 +1,473 @@
+Metadata-Version: 2.4
+Name: briefloop
+Version: 0.11.12
+Summary: Source-grounded, audit-ready multi-agent workflow for business and research briefs.
+Author: BriefLoop contributors
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Stahl-G/briefloop
+Project-URL: Repository, https://github.com/Stahl-G/briefloop
+Project-URL: Issues, https://github.com/Stahl-G/briefloop/issues
+Project-URL: Documentation, https://github.com/Stahl-G/briefloop/tree/main/docs
+Project-URL: Changelog, https://github.com/Stahl-G/briefloop/blob/main/CHANGELOG.md
+Keywords: briefing,workflow,audit,traceability,multi-agent
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Office/Business
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: docx
+Requires-Dist: python-docx>=1.0.0; extra == "docx"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: python-docx>=1.0.0; extra == "dev"
+Requires-Dist: ruff>=0.8.0; extra == "dev"
+Dynamic: license-file
+
+# 🧾 BriefLoop
+
+**AI-assisted business briefings you can question later.**
+
+[English](README.md) | [简体中文](README.zh-CN.md)
+
+Website: [briefloop.ai](https://briefloop.ai) · Contact: [contact@briefloop.ai](mailto:contact@briefloop.ai)
+
+[15-Minute Pilot](docs/15-minute-pilot.md) · [Getting Started](docs/getting-started.md) · [Weekly Loop](docs/weekly-loop.md) · [Troubleshooting](docs/troubleshooting.md) · [Reference Workspace](examples/reference-workspaces/industry-weekly-demo/README.md) · [Contact](docs/contact.md)
+
+Writer entry: use `/briefloop` in Claude Code, or `briefloop` in a shell.
+
+---
+
+## ✨ In one sentence
+
+BriefLoop is an open-source workflow for recurring business briefings.
+
+It does not try to be “a better prompt.” It keeps track of the process behind a brief:
+
+- Which source did this number come from?
+- Which claims were registered?
+- Which checks passed or failed?
+- Which reader preferences were approved by a human?
+- What should be reused next time, and what should not?
+
+> When someone asks where a number came from, BriefLoop does not ask the model to improvise an explanation. It opens the ledger.
+
+---
+
+## 🧯 The problem
+
+Many teams write the same kind of material every week:
+
+- market updates
+- industry briefings
+- competitor tracking
+- policy monitoring
+- equity research notes
+- investor-relations materials
+- executive briefings
+- project status reports
+
+LLMs can draft these documents quickly. The hard part is not drafting. The hard part is trust.
+
+Common problems:
+
+1. **Sources disappear.**
+   A number enters the final brief, and two weeks later nobody knows where it came from.
+
+2. **Small errors become confident conclusions.**
+   A weak source, stale data point, or misread paragraph can survive several editing passes and look authoritative.
+
+3. **Feedback evaporates.**
+   “Lead with the business impact,” “do not use generic wording,” or “verify this category against the original filing” often stays in someone’s head instead of the workflow.
+
+4. **Handoffs are painful.**
+   The real rules for writing the brief live with one experienced person, not in a visible process.
+
+BriefLoop turns those hidden rules into a workflow that can be inspected, repeated, and improved.
+
+---
+
+## 👥 Who is this for?
+
+BriefLoop is useful for:
+
+- analysts, associates, management trainees, IR teams, strategy teams, and market-intelligence teams who write recurring briefings;
+- teams that want AI-assisted writing to be traceable instead of merely fluent;
+- researchers studying agent workflows, human-in-the-loop systems, and auditable AI processes.
+
+It is not the right tool if you only want:
+
+- a one-click pretty report generator;
+- an autonomous agent that publishes without review;
+- a system that proves every claim is true;
+- a way to make an externally generated AI report “safe” after the fact.
+
+---
+
+## 🧱 What BriefLoop actually does
+
+Think of BriefLoop as a briefing pipeline with ledgers.
+
+| Step | What happens | Why it matters |
+|---|---|---|
+| 1. Prepare materials | Collect local files, source packs, or search results | The model should not start from nothing |
+| 2. Register claims | Important numbers, dates, entities, and claims are written into a Claim Ledger | Later you can ask where a claim came from |
+| 3. Draft by roles | Scout, Analyst, Editor, Auditor, and related roles work within boundaries | Writing becomes staged work, not one giant prompt |
+| 4. Run gates | Quality gates check source age, new facts, missing support, and delivery state | Deterministic checks do not rely on prompt memory |
+| 5. Deliver by human action | Final delivery is explicitly triggered by a human | The system does not publish or bypass review |
+| 6. Keep approved feedback | Only human-approved reader preferences are reused | “Do this next time” becomes visible and reversible |
+
+The design rule is simple:
+
+> Smart parts may write and propose. Authoritative parts must be checkable. Nothing takes effect without a human decision.
+
+---
+
+## 📚 The four questions it keeps answerable
+
+| Question | What BriefLoop records | Where to look |
+|---|---|---|
+| Where is this run? | Current stage, missing artifacts, blockers, next safe action | `/briefloop status`, `workflow_state.json`, `agent_handoff.md` |
+| Where did each number come from? | Claim Ledger entries, source dates, source appendix, gate findings | `claim_ledger.json`, `source_appendix.md`, `quality_gate_report.json` |
+| What has it learned? | Human-approved reader preferences only | `improvement/ledger.jsonl`, `improvement_memory_snapshot.md` |
+| What guards delivery? | Stage-completion records, reader-final gate, delivery checks | `finalize_report.json`, `state finalize-complete` |
+
+It can observe and propose. Only what you approve is remembered, and it is remembered in a ledger you can open, audit, and undo.
+
+---
+
+## 📦 What you get from a run
+
+A normal delivered brief is usually:
+
+- `output/delivery/brief.md`
+- `output/delivery/<report-name>.docx`
+
+The workflow also keeps audit artifacts, such as:
+
+- `output/intermediate/claim_ledger.json`
+- `output/source_appendix.md`
+- `output/intermediate/quality_gate_report.json`
+- `event_log.jsonl`
+- `improvement/ledger.jsonl`
+
+Those audit files are not meant to be read by every end user. They exist so a team can answer questions, debug failures, review decisions, and hand the process to someone else.
+
+---
+
+## 🔎 A tiny example
+
+A delivered brief might say:
+
+```markdown
+This week, the sample PV module spot price fell 1.8% week over week,
+the third consecutive weekly decline.
+```
+
+BriefLoop expects that claim to have a registered entry:
+
+```json
+{
+  "claim_id": "CL-0012",
+  "statement": "The sample PV module spot price fell 1.8% week over week.",
+  "source_id": "SRC-003",
+  "evidence_text": "Example source excerpt showing the week-over-week price change.",
+  "metadata": {
+    "published_at": "2026-06-05",
+    "source_title": "Example PV price sheet"
+  }
+}
+```
+
+If a source is stale, a number is unregistered, or an editor adds a new material fact late in the process, gates should surface the issue instead of letting it silently enter the final document.
+
+---
+
+## 🚀 Quick start
+
+### macOS / Linux
+
+```bash
+git clone https://github.com/Stahl-G/briefloop.git
+cd briefloop
+bash scripts/setup.sh
+source .venv/bin/activate
+bash scripts/demo.sh
+```
+
+`scripts/demo.sh` creates an API-free reference workspace with a final brief,
+Claim Ledger, Quality Panel HTML, Quality Summary, source appendix, and
+event-log excerpt.
+
+For the shortest walkthrough, use the
+[15-Minute Pilot](docs/15-minute-pilot.md).
+
+Package-index installs are not the launch path yet. `pipx` / PyPI packaging is
+tracked in [pipx And PyPI Packaging Prep](docs/packaging-pipx.md); do not use
+`pipx install briefloop` until release notes say a real package-index artifact
+has been published and smoked.
+
+When you are ready to use your own materials, create your first briefing
+workspace:
+
+```bash
+briefloop onboard
+briefloop init ~/briefloop-workspace --from-onboarding onboarding.json
+briefloop run --workspace ~/briefloop-workspace
+```
+
+Common setup helpers:
+
+```bash
+briefloop init --from-onboarding onboarding.json <workspace>
+briefloop sources decide --config <workspace>/config.yaml
+```
+
+`sources decide` is the explicit source-discovery helper for workspaces that use
+the `llm_decide` source profile.
+
+### Windows PowerShell
+
+Windows does not require WSL or Git Bash. PowerShell is the recommended path.
+
+```powershell
+winget install Python.Python.3.12
+
+git clone https://github.com/Stahl-G/briefloop.git
+cd briefloop
+
+.\scripts\setup.ps1
+.\.venv\Scripts\Activate.ps1
+
+briefloop version
+```
+
+If PowerShell blocks script execution:
+
+```powershell
+powershell -ExecutionPolicy Bypass -File .\scripts\setup.ps1
+```
+
+---
+
+## 🤖 Claude Code path
+
+If you use Claude Code, install the writer entrypoint:
+
+```bash
+source .venv/bin/activate
+briefloop claude install --repo-workdir .
+```
+
+Then use the five main writer commands:
+
+```text
+/briefloop new
+/briefloop run <workspace>
+/briefloop status <workspace>
+/briefloop feedback <workspace> [text-or-file]
+/briefloop deliver <workspace>
+```
+
+Good next reads:
+
+- [Getting Started](docs/getting-started.md)
+- [Weekly Loop](docs/weekly-loop.md)
+- [Troubleshooting](docs/troubleshooting.md)
+- [Claude Code quickstart](docs/claude-code-quickstart.md)
+
+---
+
+## 🧪 Three ways to try it
+
+Start from the product entry that matches your report:
+
+| Report job | Start with | Best for |
+|---|---|---|
+| Industry or market weekly | `industry-weekly` | recurring market updates, competitor tracking, policy monitoring |
+| Management monthly | `management-monthly` | executive reviews, monthly operating updates, management briefing packs |
+| Document review | `document-review` | reviewing a set of documents with page/source traceability |
+
+```bash
+briefloop new industry-weekly ./weekly-brief
+briefloop new management-monthly ./monthly-review
+briefloop new document-review ./document-review
+```
+
+`document-review` prepares a document evidence review workspace. It does not
+make legal, compliance, or disclosure judgments.
+
+Start with the three supported entries above. Other experimental entries are
+documented later for users who already understand the basic loop.
+
+| Path | Best for | What to do |
+|---|---|---|
+| Look once | You want to understand the project quickly | Run the demos and read the reference runs |
+| Run once | You want to test it on a few local files | Create a workspace, add materials, run one brief |
+| Use weekly | You want a recurring workflow | Configure sources, sections, reader preferences, and feedback |
+
+Optional demo commands:
+
+```bash
+bash scripts/demo.sh
+bash scripts/demo-deep-dive.sh
+```
+
+The demos use synthetic materials. They show the evidence chain and gate behavior. Real use starts with your own workspace and sources.
+
+---
+
+## 🧭 Current status
+
+Current version: **v0.11.12**
+
+Current main entrypoints:
+
+- CLI: `briefloop`
+- Claude command: `/briefloop`
+- experimental WorkBuddy / CodeBuddy guide: [docs/workbuddy.md](docs/workbuddy.md)
+
+v0.11.12 releases the accumulated v0.11 product-baseline, WorkBuddy adapter,
+operator-runtime, and semantic-support auditor hardening line, including:
+
+- `ReportSpec`, `ReportPack`, `ReportTemplate`, and `PolicyProfile` contracts
+- workspace skeletons and deterministic PolicyProfile resolution
+- delivery / audit bundle manifests and clean bundle archives
+- supported `industry-weekly`, `management-monthly`, and `document-review`
+  product entrypoints
+- bounded `evidence_extract` source/scope registration, source locks, logical
+  page inventory seeds, and text-span seed registries
+- experimental SourceHub Lite setup for local files, RSS feeds, and runtime web-search handoff tasks
+- durable source evidence pack materialization and source taxonomy normalization
+- internal release-mode approval records
+- Quality Panel JSON / Markdown / HTML projections and audit-bundle integration
+- reader-quality warning/projection surfaces for template conformance,
+  materiality selection, support-calibrated wording, citation profiles,
+  coverage/omission, and scoped final-abstract diagnostics
+- trajectory-regulation decision narrowing for repeated retry/repair/blocker
+  loops
+- experimental source-clone WorkBuddy Skill packaging and first-use routing
+- experimental source-clone CodeBuddy project Skill and role-agent handoff
+  through `--runtime codebuddy`
+- `operator` runtime for host-agnostic compact operation, with `manual` kept as
+  a legacy alias
+- proposal-only Semantic Support Auditor surfaces and human adjudication records
+  that do not create support truth, gates, delivery approval, or release
+  authority
+- public-safe reference, synthetic regression, minimal comparative evaluation,
+  launch smoke, and release checklist guardrails
+
+These features are meant to make report types, source evidence, default policies,
+delivery bundles, and operator quality visibility more product-like.
+
+These features are still contracts, metadata, defaults, setup paths, approval
+records, deterministic warnings, and projection controls. They do not parse PDFs automatically,
+execute hidden web search or crawling, judge industry compliance, detect
+investment advice, verify internet rumors, claim IR/disclosure readiness,
+prove semantic truth, publish reports, or authorize public release.
+
+---
+
+## 🚧 What it is not
+
+BriefLoop currently does not:
+
+- publish reports automatically;
+- bypass human review;
+- prove that a source semantically supports every sub-claim;
+- replace legal, compliance, investment, or disclosure judgment;
+- claim that generated content is ready for IR, SEC, or regulatory disclosure;
+- turn unapproved feedback into long-term memory;
+- promise one-click perfect reports.
+
+The current core claim is deliberately narrow:
+
+> **Traceability, not semantic proof yet.**
+> BriefLoop aims to make a briefing process traceable, reviewable, and accountable. Semantic proof and automatic judgment are future work, not current guarantees.
+
+---
+
+## 💡 Why this exists
+
+Coding agents improved quickly because software work has infrastructure: tests, CI, git history, code review, and rollbacks.
+
+Business briefings usually do not. A junior analyst is corrected verbally, and the correction disappears. A stale number enters a weekly report, and nobody can tell which step allowed it. A team learns what “good” looks like, but the learning stays informal.
+
+BriefLoop brings software-engineering discipline into recurring briefing work: auditability, structured feedback, human gates, execution traces, and tests.
+
+The goal is not to remove human judgment. The goal is to let humans spend more time judging, questioning, and advising, and less time re-checking the same preventable mistakes.
+
+---
+
+## 📖 Glossary
+
+| Term | Plain meaning |
+|---|---|
+| Claim Ledger | A record of important claims, numbers, sources, and dates |
+| Source Pack | The set of materials available to a run |
+| Quality Gate | A check that must pass before a stage or delivery can proceed |
+| Reader Preference | Human-approved guidance such as “lead with business impact” |
+| Improvement Ledger | The record of approved feedback |
+| Orchestrator / 司乐师 | The runtime role that coordinates stages and boundaries |
+| Delivery Bundle | The Markdown / Word files meant for readers |
+| Audit Artifacts | Intermediate records used for review, debugging, and accountability |
+
+---
+
+## 🗂️ Useful docs
+
+First-user path:
+
+- [Getting Started](docs/getting-started.md)
+- [Weekly Loop](docs/weekly-loop.md)
+- [Troubleshooting](docs/troubleshooting.md)
+- [Golden reference workspace](examples/reference-workspaces/industry-weekly-demo/README.md)
+
+Architecture reference and contributor docs:
+
+- [Function Map](docs/features.md)
+- [Golden Path](docs/golden-path.md)
+- [Architecture Status](docs/architecture-status.md)
+- [Naming and compatibility](docs/briefloop-naming.md)
+- [Roadmap](docs/roadmap.md)
+- [Red lines and anti-patterns](docs/red-lines-and-anti-patterns.md)
+- [Product OS reader-quality reference package](docs/reference-runs/v0.11.3-product-os-reader-quality-reference.md)
+- [Minimal comparative evaluation packet](docs/evaluation-results/v0.11.4-minimal-comparative-evaluation/README.md)
+- [Synthetic regression pack](docs/reference-runs/v0.11.1-synthetic-regression-pack.md)
+- [Public solar integration run](docs/reference-runs/v0.7.2-public-solar-integration.zh-CN.md)
+- [Organoid-industry failure study](docs/reference-runs/v0.7.4-organoid-failure-study.md)
+  ([中文](docs/reference-runs/v0.7.4-organoid-failure-study.zh-CN.md))
+
+---
+
+## 🤝 Collaboration
+
+This project needs real scenarios more than it needs more concepts.
+
+You are welcome to participate if you:
+
+- write recurring market, strategy, policy, IR, or executive briefings;
+- want to pilot BriefLoop on a real workflow;
+- research agent evaluation, human-in-the-loop systems, or auditable AI workflows;
+- want to contribute through issues, docs, tests, or example scenarios.
+
+Start with a [good first issue](https://github.com/Stahl-G/briefloop/issues). Please read [red lines and anti-patterns](docs/red-lines-and-anti-patterns.md) before contributing.
+
+For human contact, see [briefloop.ai](https://briefloop.ai) or
+[docs/contact.md](docs/contact.md). Use
+[security@briefloop.ai](mailto:security@briefloop.ai) for private security
+reports.
+
+---
+
+## 📄 License
+
+MIT