briar-cli 1.1.43__tar.gz → 1.1.45__tar.gz

{briar_cli-1.1.43 → briar_cli-1.1.45}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: briar-cli
-Version: 1.1.43
+Version: 1.1.45
 Summary: Terminal client for the Briar agent-orchestration API.
 Project-URL: Homepage, https://usebriar.com
 Project-URL: Source, https://github.com/iklobato/briar
@@ -176,6 +176,25 @@ briar extract --company acme \
 `code-scanning`, `repo-governance`, `test-discipline`, `release-cadence`,
 `todo-density`. See [`agents/extract.md`](agents/extract.md).
 
+#### Feed the knowledge to Claude Code — on demand
+
+```bash
+# Merge a knowledge index into CLAUDE.md; full detail lands in
+# .briar/knowledge/<company>.md for the agent to read when relevant.
+briar extract --company acme --include defect-hotspots --include ci-health \
+    --risk-repo acme-co/acme-app --cihealth-repo acme-co/acme-app \
+    --merge-claude-md
+```
+
+`--merge-claude-md` writes the full bundle to `.briar/knowledge/<company>.md`
+and splices a short, marker-bounded index — section titles plus a pointer to
+that file — into `CLAUDE.md` (override with `--claude-md-path`). Because
+`CLAUDE.md` is auto-loaded into every Claude Code session but the detail file
+is not, the knowledge stays available **on demand** without paying a
+per-session context cost: the agent reads the detail file only when a task
+touches one of the listed topics. Re-runs replace just briar's block, leaving
+your hand-written `CLAUDE.md` untouched.
+
 ### `briar runbook serve` — scheduled extraction, in-process
 
 Describe every company + task in one YAML and let `briar` run the schedule forever — no cron, no external job runner.

{briar_cli-1.1.43 → briar_cli-1.1.45}/README.md

@@ -84,6 +84,25 @@ briar extract --company acme \
 `code-scanning`, `repo-governance`, `test-discipline`, `release-cadence`,
 `todo-density`. See [`agents/extract.md`](agents/extract.md).
 
+#### Feed the knowledge to Claude Code — on demand
+
+```bash
+# Merge a knowledge index into CLAUDE.md; full detail lands in
+# .briar/knowledge/<company>.md for the agent to read when relevant.
+briar extract --company acme --include defect-hotspots --include ci-health \
+    --risk-repo acme-co/acme-app --cihealth-repo acme-co/acme-app \
+    --merge-claude-md
+```
+
+`--merge-claude-md` writes the full bundle to `.briar/knowledge/<company>.md`
+and splices a short, marker-bounded index — section titles plus a pointer to
+that file — into `CLAUDE.md` (override with `--claude-md-path`). Because
+`CLAUDE.md` is auto-loaded into every Claude Code session but the detail file
+is not, the knowledge stays available **on demand** without paying a
+per-session context cost: the agent reads the detail file only when a task
+touches one of the listed topics. Re-runs replace just briar's block, leaving
+your hand-written `CLAUDE.md` untouched.
+
 ### `briar runbook serve` — scheduled extraction, in-process
 
 Describe every company + task in one YAML and let `briar` run the schedule forever — no cron, no external job runner.

{briar_cli-1.1.43 → briar_cli-1.1.45}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "briar-cli"
-version = "1.1.43"
+version = "1.1.45"
 description = "Terminal client for the Briar agent-orchestration API."
 readme = "README.md"
 requires-python = ">=3.10"

{briar_cli-1.1.43 → briar_cli-1.1.45}/src/briar/commands/extract.py

@@ -4,6 +4,7 @@ result to a local markdown file."""
 from __future__ import annotations
 
 import argparse
+from datetime import datetime, timezone
 from pathlib import Path
 from typing import List
 
@@ -11,9 +12,22 @@ from briar.commands.base import Command
 from briar.errors import CliError
 from briar.extract import EXTRACTORS
 from briar.extract.base import ExtractedSection
+from briar.extract.claude_md import ClaudeMdMerger
 from briar.extract.composer import render_json, render_markdown
 from briar.storage import KNOWLEDGE_STORE_NAMES, make_store
 
+_CLAUDE_MD_DETAIL_ROOT = Path(".briar/knowledge")
+
+
+def _company_slug(company: str) -> str:
+    """Filesystem-safe stem for the detail file. Non-alphanumeric runs
+    collapse to a single dash so ``Acme Inc.`` and ``acme-inc`` don't
+    fight over the same path."""
+    slug = "".join(char if char.isalnum() else "-" for char in company.lower())
+    while "--" in slug:
+        slug = slug.replace("--", "-")
+    return slug.strip("-") or "knowledge"
+
 
 class CommandExtract(Command):
     name = "extract"
@@ -41,6 +55,16 @@ class CommandExtract(Command):
         parser.add_argument("--blob-name", default="", help="Storage blob name (default: knowledge:<company>)")
         parser.add_argument("--root", default="./knowledge", help="Local file root (only used when --storage=file)")
         parser.add_argument("--out-json", default="", help="Parallel JSON output path (empty = skip)")
+        parser.add_argument(
+            "--merge-claude-md",
+            action="store_true",
+            help="Also merge a knowledge index into CLAUDE.md so Claude Code " "sessions can read the full detail on demand",
+        )
+        parser.add_argument(
+            "--claude-md-path",
+            default="./CLAUDE.md",
+            help="CLAUDE.md to merge the knowledge index into (only used with --merge-claude-md)",
+        )
         for ext in EXTRACTORS.values():
             ext.add_arguments(parser)
 
@@ -76,4 +100,31 @@ class CommandExtract(Command):
             json_path.write_text(render_json(company=args.company, sections=sections))
             print(f"wrote {json_path}")
 
+        if args.merge_claude_md:
+            self._merge_claude_md(args, sections)
+
         return 0
+
+    def _merge_claude_md(self, args: argparse.Namespace, sections: List[ExtractedSection]) -> None:
+        """Write the full bundle to a local detail file and splice a
+        short pointer index into CLAUDE.md.
+
+        The detail file is always written to the local filesystem (under
+        the cwd) regardless of ``--storage``: the on-demand reference in
+        CLAUDE.md only resolves for a session running from the project
+        root, so a postgres-backed run still needs the local copy here."""
+        detail_path = _CLAUDE_MD_DETAIL_ROOT / f"{_company_slug(args.company)}.md"
+        detail_path.parent.mkdir(parents=True, exist_ok=True)
+        detail_path.write_text(render_markdown(company=args.company, sections=sections))
+
+        block = ClaudeMdMerger.index_block(
+            company=args.company,
+            detail_path=detail_path.as_posix(),
+            sections=sections,
+            when=datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%MZ"),
+        )
+        claude_md = Path(args.claude_md_path)
+        existing = claude_md.read_text() if claude_md.exists() else ""
+        claude_md.parent.mkdir(parents=True, exist_ok=True)
+        claude_md.write_text(ClaudeMdMerger.merge(existing=existing, block=block))
+        print(f"merged knowledge index into {claude_md} (detail: {detail_path})")

briar_cli-1.1.45/src/briar/extract/claude_md.py

@@ -0,0 +1,78 @@
+"""Merge an extracted knowledge bundle into a project's ``CLAUDE.md`` so
+Claude Code sessions can load the detail ON DEMAND.
+
+``CLAUDE.md`` is auto-loaded into *every* session, so anything placed
+there is a permanent per-session context cost. We therefore keep only a
+short index in ``CLAUDE.md`` — the section titles plus a pointer to the
+full detail file — and let the agent ``Read`` that file when a task
+actually needs it. The index lives inside a managed marker block so a
+re-run replaces just Briar's block and never disturbs hand-written
+content around it.
+
+Pure string composition only — no filesystem access. The command at the
+edge owns reading/writing the files and stamps the timestamp, which
+keeps this module trivially testable."""
+
+from __future__ import annotations
+
+from typing import List
+
+from briar.extract.base import ExtractedSection
+
+BEGIN_MARKER = "<!-- BEGIN briar-knowledge -->"
+END_MARKER = "<!-- END briar-knowledge -->"
+
+
+class ClaudeMdMerger:
+    """Render and splice Briar's managed knowledge-index block."""
+
+    @classmethod
+    def index_block(
+        cls,
+        *,
+        company: str,
+        detail_path: str,
+        sections: List[ExtractedSection],
+        when: str,
+    ) -> str:
+        """The short block that lives inside ``CLAUDE.md``: a pointer to
+        the full detail file plus the list of topics it covers, so a
+        session knows when reading it is worthwhile.
+
+        Follows Claude Code's CLAUDE.md conventions: a plain imperative
+        instruction and bullet topics (not italic prose), kept lean
+        because CLAUDE.md is auto-loaded into every session. The
+        provenance line is a block-level HTML comment — Claude Code
+        strips those before injecting the file into context, so it costs
+        zero tokens yet stays visible to humans reading the file on
+        disk."""
+        lines: List[str] = [
+            BEGIN_MARKER,
+            (f"<!-- extracted {when}; managed by `briar extract --merge-claude-md` — " "edits between these markers are overwritten on re-run -->"),
+            f"## Project knowledge — {company} (Briar)",
+            "",
+            f"Read `{detail_path}` when a task touches any of these topics:",
+            "",
+        ]
+        lines.extend(f"- {section.title}" for section in sections)
+        lines.append(END_MARKER)
+        return "\n".join(lines)
+
+    @classmethod
+    def merge(cls, *, existing: str, block: str) -> str:
+        """Return ``CLAUDE.md`` content with Briar's block inserted or
+        replaced. Everything outside the markers is preserved verbatim.
+
+        A well-formed existing block (both markers, in order) is replaced
+        in place. Otherwise the block is appended, separated from prior
+        content by a blank line. A stray/malformed marker pair is treated
+        as absent rather than guessed at — we never delete content we
+        can't bound."""
+        start = existing.find(BEGIN_MARKER)
+        end = existing.find(END_MARKER)
+        if start != -1 and end > start:
+            end += len(END_MARKER)
+            return existing[:start] + block + existing[end:]
+        if existing.strip():
+            return f"{existing.rstrip()}\n\n{block}\n"
+        return f"{block}\n"

briar_cli-1.1.45/tests/unit/extract/test_claude_md.py

@@ -0,0 +1,153 @@
+"""Tests for the CLAUDE.md knowledge-index merge.
+
+The merger is pure string composition; the command-level test exercises
+the file I/O (detail file written locally, index spliced into CLAUDE.md)
+and the non-destructive marker-block behaviour."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import unittest
+from pathlib import Path
+from tempfile import TemporaryDirectory
+
+from briar.commands.extract import CommandExtract, _company_slug
+from briar.extract.base import ExtractedSection
+from briar.extract.claude_md import BEGIN_MARKER, END_MARKER, ClaudeMdMerger
+
+_SECTIONS = [
+    ExtractedSection(title="CI health", body="pass rate 92%"),
+    ExtractedSection(title="PR hygiene", body="median 84 LOC"),
+]
+
+
+class IndexBlockTests(unittest.TestCase):
+    def _block(self) -> str:
+        return ClaudeMdMerger.index_block(
+            company="Acme",
+            detail_path=".briar/knowledge/acme.md",
+            sections=_SECTIONS,
+            when="2026-06-18T13:00Z",
+        )
+
+    def test_block_is_marker_bounded(self) -> None:
+        block = self._block()
+        self.assertTrue(block.startswith(BEGIN_MARKER))
+        self.assertTrue(block.rstrip().endswith(END_MARKER))
+
+    def test_block_points_at_detail_with_imperative_instruction(self) -> None:
+        block = self._block()
+        self.assertIn("Read `.briar/knowledge/acme.md` when", block)
+        self.assertIn("- CI health", block)
+        self.assertIn("- PR hygiene", block)
+
+    def test_block_uses_plain_bullets_not_italic_prose(self) -> None:
+        # CLAUDE.md convention favours imperative bullets over italic prose.
+        block = self._block()
+        self.assertNotIn("_Extracted", block)
+        self.assertNotIn("on demand_", block)
+
+    def test_timestamp_lives_in_a_stripped_html_comment(self) -> None:
+        # Claude Code strips block-level HTML comments before injecting
+        # CLAUDE.md into context, so provenance costs zero tokens. The
+        # timestamp must therefore sit inside a comment, never bare text.
+        for line in self._block().splitlines():
+            if "2026-06-18T13:00Z" in line:
+                self.assertTrue(line.strip().startswith("<!--"))
+                self.assertTrue(line.strip().endswith("-->"))
+                break
+        else:
+            self.fail("timestamp not present in block")
+
+    def test_block_omits_section_bodies(self) -> None:
+        # Index stays light: titles only, never the detail bodies.
+        block = self._block()
+        self.assertNotIn("pass rate 92%", block)
+
+
+class MergeTests(unittest.TestCase):
+    def setUp(self) -> None:
+        self.block = ClaudeMdMerger.index_block(
+            company="Acme",
+            detail_path=".briar/knowledge/acme.md",
+            sections=_SECTIONS,
+            when="2026-06-18T13:00Z",
+        )
+
+    def test_append_into_existing_preserves_handwritten_content(self) -> None:
+        existing = "# My project\n\nHand-written rules.\n"
+        merged = ClaudeMdMerger.merge(existing=existing, block=self.block)
+        self.assertIn("Hand-written rules.", merged)
+        self.assertIn(BEGIN_MARKER, merged)
+
+    def test_empty_existing_yields_just_the_block(self) -> None:
+        merged = ClaudeMdMerger.merge(existing="", block=self.block)
+        self.assertEqual(merged.strip(), self.block.strip())
+
+    def test_rerun_replaces_block_without_duplicating(self) -> None:
+        first = ClaudeMdMerger.merge(existing="# Top\n", block=self.block)
+        fresh = ClaudeMdMerger.index_block(
+            company="Acme",
+            detail_path=".briar/knowledge/acme.md",
+            sections=[ExtractedSection(title="Stale PRs", body="3 idle")],
+            when="2026-06-19T09:00Z",
+        )
+        second = ClaudeMdMerger.merge(existing=first, block=fresh)
+        self.assertEqual(second.count(BEGIN_MARKER), 1)
+        self.assertEqual(second.count(END_MARKER), 1)
+        self.assertIn("- Stale PRs", second)
+        self.assertNotIn("- CI health", second)
+        self.assertIn("# Top", second)
+
+    def test_malformed_markers_are_not_treated_as_a_block(self) -> None:
+        # END before BEGIN must not delete the content between them.
+        existing = f"keep-a\n{END_MARKER}\nkeep-b\n{BEGIN_MARKER}\nkeep-c\n"
+        merged = ClaudeMdMerger.merge(existing=existing, block=self.block)
+        self.assertIn("keep-a", merged)
+        self.assertIn("keep-b", merged)
+        self.assertIn("keep-c", merged)
+
+
+class CompanySlugTests(unittest.TestCase):
+    def test_spaces_and_punctuation_collapse_to_single_dash(self) -> None:
+        self.assertEqual(_company_slug("Acme Inc."), "acme-inc")
+
+    def test_empty_falls_back(self) -> None:
+        self.assertEqual(_company_slug("!!!"), "knowledge")
+
+
+class MergeCommandIoTests(unittest.TestCase):
+    def setUp(self) -> None:
+        self._prev_cwd = os.getcwd()
+        self._tmp = TemporaryDirectory()
+        os.chdir(self._tmp.name)
+
+    def tearDown(self) -> None:
+        os.chdir(self._prev_cwd)
+        self._tmp.cleanup()
+
+    def _args(self) -> argparse.Namespace:
+        return argparse.Namespace(company="Acme Inc.", claude_md_path="./CLAUDE.md")
+
+    def test_writes_detail_file_and_merges_index(self) -> None:
+        CommandExtract()._merge_claude_md(self._args(), _SECTIONS)
+
+        detail = Path(".briar/knowledge/acme-inc.md")
+        self.assertTrue(detail.exists())
+        self.assertIn("pass rate 92%", detail.read_text())
+
+        claude_md = Path("./CLAUDE.md").read_text()
+        self.assertIn(BEGIN_MARKER, claude_md)
+        self.assertIn(".briar/knowledge/acme-inc.md", claude_md)
+
+    def test_merge_keeps_existing_claude_md(self) -> None:
+        Path("./CLAUDE.md").write_text("# Existing\n\nkeep me\n")
+        CommandExtract()._merge_claude_md(self._args(), _SECTIONS)
+        claude_md = Path("./CLAUDE.md").read_text()
+        self.assertIn("keep me", claude_md)
+        self.assertEqual(claude_md.count(BEGIN_MARKER), 1)
+
+
+if __name__ == "__main__":
+    unittest.main()