shellbrain 0.1.32__tar.gz → 0.1.34__tar.gz

{shellbrain-0.1.32 → shellbrain-0.1.34}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: shellbrain
-Version: 0.1.32
+Version: 0.1.34
 Summary: Repo-scoped Shellbrain CLI with explicit evidence-backed writes.
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown

{shellbrain-0.1.32 → shellbrain-0.1.34}/app/core/policies/episodes/knowledge_building.py

@@ -16,6 +16,7 @@ class KnowledgeBuildPlan:
 
     episode_id: str
     trigger: KnowledgeBuildTrigger
+    baseline_only: bool = False
 
 
 def plan_stable_watermark_builds(
@@ -23,12 +24,18 @@ def plan_stable_watermark_builds(
     snapshots: Iterable[EpisodeBuildSnapshot],
     now: datetime,
     idle_stable_seconds: int,
+    lifecycle_activated_at: datetime | None = None,
 ) -> tuple[KnowledgeBuildPlan, ...]:
     """Return build plans for closed or idle-stable episodes with new events."""
 
     if idle_stable_seconds < 0:
         raise ValueError("idle_stable_seconds must be non-negative")
     stable_before = now - timedelta(seconds=idle_stable_seconds)
+    legacy_baseline_before = (
+        None
+        if lifecycle_activated_at is None
+        else lifecycle_activated_at - timedelta(seconds=idle_stable_seconds)
+    )
     plans: list[KnowledgeBuildPlan] = []
     seen: set[str] = set()
     for snapshot in snapshots:
@@ -46,6 +53,10 @@ def plan_stable_watermark_builds(
             KnowledgeBuildPlan(
                 episode_id=snapshot.episode_id,
                 trigger=KnowledgeBuildTrigger.WATERMARK_STABLE,
+                baseline_only=_should_baseline_legacy_first_build(
+                    snapshot=snapshot,
+                    legacy_baseline_before=legacy_baseline_before,
+                ),
             )
         )
     return tuple(plans)
@@ -69,3 +80,17 @@ def _is_stable_build_candidate(
     if snapshot.status is not EpisodeStatus.ACTIVE:
         return False
     return snapshot.latest_event_at <= stable_before
+
+
+def _should_baseline_legacy_first_build(
+    *,
+    snapshot: EpisodeBuildSnapshot,
+    legacy_baseline_before: datetime | None,
+) -> bool:
+    """Return whether an old first-build episode should be watermarked only."""
+
+    if legacy_baseline_before is None:
+        return False
+    if snapshot.latest_successful_build_watermark is not None:
+        return False
+    return snapshot.latest_event_at <= legacy_baseline_before

{shellbrain-0.1.32 → shellbrain-0.1.34}/app/core/ports/db/knowledge_builder.py

@@ -24,6 +24,12 @@ class IKnowledgeBuildRunsRepo(ABC):
     ) -> int | None:
         """Return the newest successfully processed event watermark."""
 
+    @abstractmethod
+    def ensure_lifecycle_activation_started_at(
+        self, *, repo_id: str, activated_at: datetime
+    ) -> datetime:
+        """Return the repo lifecycle-builder activation time, creating it if absent."""
+
     @abstractmethod
     def list_running_runs(
         self, *, repo_id: str, episode_id: str

{shellbrain-0.1.32 → shellbrain-0.1.34}/app/core/use_cases/knowledge_builder/build_knowledge/execute.py

@@ -116,6 +116,16 @@ def execute_build_knowledge(
                 finished_at=now,
             )
 
+        if request.baseline_only and previous_watermark is None:
+            return _record_baseline_run(
+                request=request,
+                settings=settings,
+                uow=uow,
+                id_generator=id_generator,
+                event_watermark=event_watermark,
+                now=now,
+            )
+
         run_id = id_generator.new_id()
         uow.knowledge_build_runs.add(
             KnowledgeBuildRun(
@@ -261,6 +271,56 @@ def _fresh_running_run(
     return None
 
 
+def _record_baseline_run(
+    *,
+    request: BuildKnowledgeRequest,
+    settings: BuildKnowledgeSettings,
+    uow: IUnitOfWork,
+    id_generator: IIdGenerator,
+    event_watermark: int,
+    now: datetime,
+) -> BuildKnowledgeResult:
+    """Persist a no-provider watermark for history that predates lifecycle builds."""
+
+    run_id = id_generator.new_id()
+    run_summary = (
+        "Baselined legacy episode without invoking build_knowledge; "
+        "future events after this watermark remain eligible."
+    )
+    uow.knowledge_build_runs.add(
+        KnowledgeBuildRun(
+            id=run_id,
+            repo_id=request.repo_id,
+            episode_id=request.episode_id,
+            trigger=request.trigger,
+            status=KnowledgeBuildRunStatus.SKIPPED,
+            event_watermark=event_watermark,
+            previous_event_watermark=None,
+            provider=settings.provider,
+            model=settings.model,
+            reasoning=settings.reasoning,
+            run_summary=run_summary,
+            error_code="legacy_episode_baselined",
+            started_at=now,
+            finished_at=now,
+            created_at=now,
+        )
+    )
+    return BuildKnowledgeResult(
+        status=KnowledgeBuildRunStatus.SKIPPED,
+        run_id=run_id,
+        event_watermark=event_watermark,
+        previous_event_watermark=None,
+        provider=settings.provider,
+        model=settings.model,
+        reasoning=settings.reasoning,
+        write_count=0,
+        skipped_item_count=0,
+        run_summary=run_summary,
+        error_code="legacy_episode_baselined",
+    )
+
+
 def _skipped_result(
     *,
     settings: BuildKnowledgeSettings,

{shellbrain-0.1.32 → shellbrain-0.1.34}/app/core/use_cases/knowledge_builder/build_knowledge/request.py

@@ -18,6 +18,7 @@ class BuildKnowledgeRequest(_StrictModel):
     repo_root: str = Field(min_length=1)
     episode_id: str = Field(min_length=1)
     trigger: KnowledgeBuildTrigger
+    baseline_only: bool = False
 
     @field_validator("repo_id", "repo_root", "episode_id")
     @classmethod

{shellbrain-0.1.32 → shellbrain-0.1.34}/app/infrastructure/db/runtime/models/knowledge_builder.py

@@ -118,6 +118,20 @@ knowledge_build_runs = Table(
     ),
 )
 
+
+knowledge_build_lifecycle = Table(
+    "knowledge_build_lifecycle",
+    metadata,
+    Column("repo_id", String, primary_key=True),
+    Column("activated_at", TIMESTAMP(timezone=True), nullable=False),
+    Column(
+        "created_at",
+        TIMESTAMP(timezone=True),
+        nullable=False,
+        server_default=text("NOW()"),
+    ),
+)
+
 Index(
     "idx_knowledge_build_runs_episode_status_created_at",
     knowledge_build_runs.c.repo_id,

{shellbrain-0.1.32 → shellbrain-0.1.34}/app/infrastructure/db/runtime/repos/relational/knowledge_builder_repo.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 from datetime import datetime, timezone
 
 from sqlalchemy import desc, select, text, update
+from sqlalchemy.dialects.postgresql import insert
 
 from app.core.entities.knowledge_builder import (
     KnowledgeBuildRun,
@@ -12,7 +13,10 @@ from app.core.entities.knowledge_builder import (
     KnowledgeBuildTrigger,
 )
 from app.core.ports.db.knowledge_builder import IKnowledgeBuildRunsRepo
-from app.infrastructure.db.runtime.models.knowledge_builder import knowledge_build_runs
+from app.infrastructure.db.runtime.models.knowledge_builder import (
+    knowledge_build_lifecycle,
+    knowledge_build_runs,
+)
 
 
 class KnowledgeBuildRunsRepo(IKnowledgeBuildRunsRepo):
@@ -67,6 +71,27 @@ class KnowledgeBuildRunsRepo(IKnowledgeBuildRunsRepo):
         )
         return None if row is None else int(row)
 
+    def ensure_lifecycle_activation_started_at(
+        self, *, repo_id: str, activated_at: datetime
+    ) -> datetime:
+        """Return the repo lifecycle-builder activation time, creating it if absent."""
+
+        self._session.execute(
+            insert(knowledge_build_lifecycle)
+            .values(
+                repo_id=repo_id,
+                activated_at=activated_at,
+                created_at=activated_at,
+            )
+            .on_conflict_do_nothing(index_elements=[knowledge_build_lifecycle.c.repo_id])
+        )
+        value = self._session.execute(
+            select(knowledge_build_lifecycle.c.activated_at).where(
+                knowledge_build_lifecycle.c.repo_id == repo_id
+            )
+        ).scalar_one()
+        return value
+
     def list_running_runs(
         self, *, repo_id: str, episode_id: str
     ) -> tuple[KnowledgeBuildRun, ...]:

{shellbrain-0.1.32 → shellbrain-0.1.34}/app/infrastructure/host_apps/inner_agents/prompt.py

@@ -292,10 +292,6 @@ next_checks:
 - one to three concrete checks supported by pack evidence. Do not give generic
   coding advice.
 
-sources:
-- include only pack sources that support the brief. Every non-empty section
-  should have source support when ids are available.
-
 # JUDGMENT
 Do not dump raw retrieval results. Compact does not mean omitting the deciding
 distinction. Preserve details that change what the worker should do:
@@ -309,8 +305,8 @@ guidance.
 
 # OUTPUT
 Return only valid JSON matching `output_contract`. Return a `brief` object only;
-do not include read_trace. Keep each list compact. Use only sources from the
-pack.
+do not include read_trace or sources. Keep each list compact. Shellbrain attaches
+deterministic source provenance after synthesis.
 """
 
 
@@ -909,14 +905,6 @@ def render_build_context_synthesis_prompt(request: InnerAgentRunRequest) -> str:
                 "conflicts": ["string"],
                 "gaps": ["string"],
                 "next_checks": ["string"],
-                "sources": [
-                    {
-                        "kind": "memory|concept|claim|relation|grounding|memory_link|anchor|conflict",
-                        "id": "source id or concept ref from deterministic_graph_pack",
-                        "facet": "memory|claim|relation|grounding|memory_link when applicable",
-                        "used_in": "summary|constraints|known_traps|prior_cases|concept_orientation|anchors|conflicts|gaps|next_checks",
-                    }
-                ],
             }
         },
     }

{shellbrain-0.1.32 → shellbrain-0.1.34}/app/infrastructure/process/episode_sync/poller.py

@@ -272,14 +272,22 @@ def _run_stable_builds_best_effort(
         return
     try:
         with uow_factory() as uow:
+            now = _utc_now()
+            lifecycle_activated_at = (
+                uow.knowledge_build_runs.ensure_lifecycle_activation_started_at(
+                    repo_id=repo_id,
+                    activated_at=now,
+                )
+            )
             snapshots = tuple(uow.episodes.list_build_snapshots(repo_id=repo_id))
     except Exception:
         return
 
     for plan in plan_stable_watermark_builds(
         snapshots=snapshots,
-        now=_utc_now(),
+        now=now,
         idle_stable_seconds=idle_stable_seconds,
+        lifecycle_activated_at=lifecycle_activated_at,
     ):
         _run_build_knowledge_plan_best_effort(
             run_build_knowledge=run_build_knowledge,
@@ -301,12 +309,15 @@ def _run_build_knowledge_plan_best_effort(
     if run_build_knowledge is None or plan is None:
         return
     try:
-        run_build_knowledge(
-            repo_id=repo_id,
-            repo_root=repo_root,
-            episode_id=plan.episode_id,
-            trigger=plan.trigger,
-        )
+        kwargs = {
+            "repo_id": repo_id,
+            "repo_root": repo_root,
+            "episode_id": plan.episode_id,
+            "trigger": plan.trigger,
+        }
+        if plan.baseline_only:
+            kwargs["baseline_only"] = True
+        run_build_knowledge(**kwargs)
     except Exception:
         return
 

{shellbrain-0.1.32 → shellbrain-0.1.34}/app/startup/knowledge_builder.py

@@ -24,6 +24,7 @@ def run_build_knowledge(
     repo_root: Path,
     episode_id: str,
     trigger: KnowledgeBuildTrigger | str,
+    baseline_only: bool = False,
 ) -> dict[str, object]:
     """Wire dependencies and run build_knowledge for one episode."""
 
@@ -32,6 +33,7 @@ def run_build_knowledge(
         repo_root=str(repo_root.resolve()),
         episode_id=episode_id,
         trigger=KnowledgeBuildTrigger(trigger),
+        baseline_only=baseline_only,
     )
     result = execute_build_knowledge(
         request,

shellbrain-0.1.34/migrations/versions/20260520_0028_knowledge_build_lifecycle.py

@@ -0,0 +1,29 @@
+"""Add lifecycle activation state for forward-only knowledge building."""
+
+from alembic import op
+
+
+revision = "20260520_0028"
+down_revision = "20260519_0027"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    """Create per-repo lifecycle activation state."""
+
+    op.execute(
+        """
+        CREATE TABLE IF NOT EXISTS knowledge_build_lifecycle (
+          repo_id TEXT PRIMARY KEY,
+          activated_at TIMESTAMPTZ NOT NULL,
+          created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+        );
+        """
+    )
+
+
+def downgrade() -> None:
+    """Drop per-repo lifecycle activation state."""
+
+    op.execute("DROP TABLE IF EXISTS knowledge_build_lifecycle;")

{shellbrain-0.1.32 → shellbrain-0.1.34}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "shellbrain"
-version = "0.1.32"
+version = "0.1.34"
 description = "Repo-scoped Shellbrain CLI with explicit evidence-backed writes."
 readme = "README.md"
 requires-python = ">=3.11"

{shellbrain-0.1.32 → shellbrain-0.1.34}/shellbrain.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: shellbrain
-Version: 0.1.32
+Version: 0.1.34
 Summary: Repo-scoped Shellbrain CLI with explicit evidence-backed writes.
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown

{shellbrain-0.1.32 → shellbrain-0.1.34}/shellbrain.egg-info/SOURCES.txt

@@ -414,6 +414,7 @@ migrations/versions/20260519_0024_read_retrieval_latency_indexes.py
 migrations/versions/20260519_0025_repair_recall_source_input_section_constraint.py
 migrations/versions/20260519_0026_repair_knowledge_build_trigger_constraint.py
 migrations/versions/20260519_0027_concept_embeddings.py
+migrations/versions/20260520_0028_knowledge_build_lifecycle.py
 migrations/versions/__init__.py
 onboarding_assets/__init__.py
 onboarding_assets/claude/CLAUDE.md