diff --git a/.gemini/rules/se-deversity-skill3-llm-AnthropicChatModel.md b/.gemini/rules/se-deversity-skill3-llm-AnthropicChatModel.md new file mode 100644 index 0000000..c02b0e8 --- /dev/null +++ b/.gemini/rules/se-deversity-skill3-llm-AnthropicChatModel.md @@ -0,0 +1,7 @@ + +# Rules for AnthropicChatModel + +## Security-Critical Code +- **Rule**: This code is security-critical. Do not weaken security properties. Every change must be explicitly reviewed for security impact. +- **Aspect**: Anthropic API credential handling and hosted-provider network egress + diff --git a/.gemini/rules/se-deversity-skill3-llm-ChatModel.md b/.gemini/rules/se-deversity-skill3-llm-ChatModel.md new file mode 100644 index 0000000..f81bf39 --- /dev/null +++ b/.gemini/rules/se-deversity-skill3-llm-ChatModel.md @@ -0,0 +1,7 @@ + +# Rules for ChatModel + +## Contract-Frozen Signature +- **Constraint**: You may change internal logic, but MUST NOT modify the method name, parameters, return type, or checked exceptions. +- **Reason**: The single seam every model-driven stage binds to — QueryPlanner, Synthesizer, Verifier and the self-correction Reviser all take this one interface, which is what lets one --llm-provider choice apply uniformly. Test fakes implement it directly, so changing the signature breaks every unit test that avoids a live model. + diff --git a/.gemini/rules/se-deversity-skill3-llm-LlmProviderFactory.md b/.gemini/rules/se-deversity-skill3-llm-LlmProviderFactory.md new file mode 100644 index 0000000..ac96870 --- /dev/null +++ b/.gemini/rules/se-deversity-skill3-llm-LlmProviderFactory.md @@ -0,0 +1,7 @@ + +# Rules for LlmProviderFactory + +## Security-Critical Code +- **Rule**: This code is security-critical. Do not weaken security properties. Every change must be explicitly reviewed for security impact. +- **Aspect**: LLM provider credential resolution and model selection + diff --git a/.gemini/rules/se-deversity-skill3-llm-LocalLlmClient.md b/.gemini/rules/se-deversity-skill3-llm-LocalLlmClient.md new file mode 100644 index 0000000..42747e0 --- /dev/null +++ b/.gemini/rules/se-deversity-skill3-llm-LocalLlmClient.md @@ -0,0 +1,11 @@ + +# Rules for LocalLlmClient + +### Rules for field apiKey +- **Rule**: Never log or expose runtime values of this element. +- **Reason**: LLM provider API key — never log, echo, or include in errors/fixtures + +## Security-Critical Code +- **Rule**: This code is security-critical. Do not weaken security properties. Every change must be explicitly reviewed for security impact. +- **Aspect**: outbound LLM-provider credential (Bearer token) handling + diff --git a/.gemini/rules/se-deversity-skill3-llm-NameSanitizer.md b/.gemini/rules/se-deversity-skill3-llm-NameSanitizer.md new file mode 100644 index 0000000..8522e21 --- /dev/null +++ b/.gemini/rules/se-deversity-skill3-llm-NameSanitizer.md @@ -0,0 +1,10 @@ + +# Rules for NameSanitizer + +## Security-Critical Code +- **Rule**: This code is security-critical. Do not weaken security properties. Every change must be explicitly reviewed for security impact. +- **Aspect**: output sanitization: reserved-word stripping must never be weakened + +### Rules for method sanitize +- **Rule**: Must remain a pure function. Forbid state modifications and side effects. + diff --git a/.gemini/rules/se-deversity-skill3-llm-SkillMdPostProcessor.md b/.gemini/rules/se-deversity-skill3-llm-SkillMdPostProcessor.md new file mode 100644 index 0000000..4b43f81 --- /dev/null +++ b/.gemini/rules/se-deversity-skill3-llm-SkillMdPostProcessor.md @@ -0,0 +1,11 @@ + +# Rules for SkillMdPostProcessor + +## Core Functionality +- **Sensitivity**: High +- **Note**: Deterministically guarantees SKILL.md spec compliance; model output is never trusted. Changes risk emitting invalid frontmatter — keep the parsing and frontmatter synthesis covered by SkillMdPostProcessorTest. + +### Rules for method render +- **Rule**: This operation is idempotent. Calling it multiple times must produce the same result as calling it once. +- **Reason**: SelfCorrectionLoop re-runs render() on its own output, so a revised draft passes through repeatedly. Every guarantee here must converge: exactly one frontmatter block and exactly one provenance footer, no matter how many revision rounds ran. + diff --git a/.gemini/rules/se-deversity-skill3-llm-Verifier.md b/.gemini/rules/se-deversity-skill3-llm-Verifier.md new file mode 100644 index 0000000..75b688d --- /dev/null +++ b/.gemini/rules/se-deversity-skill3-llm-Verifier.md @@ -0,0 +1,7 @@ + +# Rules for Verifier + +## Core Functionality +- **Sensitivity**: High +- **Note**: Accuracy gate that re-grounds claims against the sources. Only worthwhile with a capable model — a weak model rewrites rather than grounds. Keep the prompt strict about supported-claims-only and announced-vs-shipped. + diff --git a/.gemini/rules/se-deversity-skill3-model-ContextBundle.md b/.gemini/rules/se-deversity-skill3-model-ContextBundle.md new file mode 100644 index 0000000..7e79714 --- /dev/null +++ b/.gemini/rules/se-deversity-skill3-model-ContextBundle.md @@ -0,0 +1,7 @@ + +# Rules for ContextBundle + +## Immutable Type +- **Rule**: This type is immutable. Never introduce non-final fields, setters, or mutating methods. +- **Note**: Immutable record; the sources list is defensively copied in the compact constructor. + diff --git a/.gemini/rules/se-deversity-skill3-model-RunManifest.md b/.gemini/rules/se-deversity-skill3-model-RunManifest.md new file mode 100644 index 0000000..87a7720 --- /dev/null +++ b/.gemini/rules/se-deversity-skill3-model-RunManifest.md @@ -0,0 +1,6 @@ + +# Rules for RunManifest + +## Schema & Serialization Safety +- **Rule**: Prohibit altering data formats, fields, database columns, or serialization structures without explicit backward-compatible migration paths. + diff --git a/.gemini/rules/se-deversity-skill3-model-Source.md b/.gemini/rules/se-deversity-skill3-model-Source.md new file mode 100644 index 0000000..4c65032 --- /dev/null +++ b/.gemini/rules/se-deversity-skill3-model-Source.md @@ -0,0 +1,10 @@ + +# Rules for Source + +## Architectural Boundary Constraints +- **Layer**: model +- **Prohibited References**: se.deversity.skill3.pipeline, se.deversity.skill3.llm, se.deversity.skill3.cli, se.deversity.skill3.skillspector, se.deversity.skill3.web, se.deversity.skill3.net + +## Domain Model Boundary +- **Purity**: Framework-free DDD Entity. + diff --git a/.gemini/rules/se-deversity-skill3-pipeline-BraveSearchClient.md b/.gemini/rules/se-deversity-skill3-pipeline-BraveSearchClient.md new file mode 100644 index 0000000..644f7a0 --- /dev/null +++ b/.gemini/rules/se-deversity-skill3-pipeline-BraveSearchClient.md @@ -0,0 +1,11 @@ + +# Rules for BraveSearchClient + +### Rules for field apiKey +- **Rule**: Never log or expose runtime values of this element. +- **Reason**: Brave Search subscription token — never log, echo, or include in errors/fixtures + +## Security-Critical Code +- **Rule**: This code is security-critical. Do not weaken security properties. Every change must be explicitly reviewed for security impact. +- **Aspect**: external-API credential handling and the only network egress with a secret token + diff --git a/.gemini/rules/se-deversity-skill3-pipeline-CutoffResolver.md b/.gemini/rules/se-deversity-skill3-pipeline-CutoffResolver.md new file mode 100644 index 0000000..3da91fe --- /dev/null +++ b/.gemini/rules/se-deversity-skill3-pipeline-CutoffResolver.md @@ -0,0 +1,7 @@ + +# Rules for CutoffResolver + +## Context & Focus +- **Focus**: Keep the cutoff TABLE small and sourced from published model documentation +- **Avoid**: hardcoding per-skill logic; the cutoff is always overridable via --cutoff-time + diff --git a/.gemini/rules/se-deversity-skill3-pipeline-DiscoveryProvider.md b/.gemini/rules/se-deversity-skill3-pipeline-DiscoveryProvider.md new file mode 100644 index 0000000..848c3b3 --- /dev/null +++ b/.gemini/rules/se-deversity-skill3-pipeline-DiscoveryProvider.md @@ -0,0 +1,7 @@ + +# Rules for DiscoveryProvider + +## Security-Critical Code +- **Rule**: This code is security-critical. Do not weaken security properties. Every change must be explicitly reviewed for security impact. +- **Aspect**: forwards the Brave subscription token to the search client; must not log it + diff --git a/.gemini/rules/se-deversity-skill3-pipeline-FileCorpus.md b/.gemini/rules/se-deversity-skill3-pipeline-FileCorpus.md new file mode 100644 index 0000000..5f8e294 --- /dev/null +++ b/.gemini/rules/se-deversity-skill3-pipeline-FileCorpus.md @@ -0,0 +1,8 @@ + +# Rules for FileCorpus + +## Load-Bearing Oddity +- **Rule**: This looks removable but is deliberate. Refactor only while the invariant holds. +- **Invariant**: FileCorpus implements BOTH discovery seams — SearchClient and PageFetcher — and LearnCommand injects the same instance into both slots. That is the design, not a layering slip: it is what makes an offline --input-file run take the identical downstream path as a live Brave run, so the two modes cannot diverge. +- **Breaks if changed**: the class is split into two collaborators, or either interface is dropped — offline runs then follow a different path from live ones and stop proving anything about the real pipeline + diff --git a/.gemini/rules/se-deversity-skill3-pipeline-HttpPageFetcher.md b/.gemini/rules/se-deversity-skill3-pipeline-HttpPageFetcher.md new file mode 100644 index 0000000..c980abd --- /dev/null +++ b/.gemini/rules/se-deversity-skill3-pipeline-HttpPageFetcher.md @@ -0,0 +1,7 @@ + +# Rules for HttpPageFetcher + +## Security-Critical Code +- **Rule**: This code is security-critical. Do not weaken security properties. Every change must be explicitly reviewed for security impact. +- **Aspect**: outbound page fetch egress for partly-untrusted URLs; SSRF guard must not be weakened + diff --git a/.gemini/rules/se-deversity-skill3-pipeline-PageFetcher.md b/.gemini/rules/se-deversity-skill3-pipeline-PageFetcher.md new file mode 100644 index 0000000..6502a32 --- /dev/null +++ b/.gemini/rules/se-deversity-skill3-pipeline-PageFetcher.md @@ -0,0 +1,7 @@ + +# Rules for PageFetcher + +## Contract-Frozen Signature +- **Constraint**: You may change internal logic, but MUST NOT modify the method name, parameters, return type, or checked exceptions. +- **Reason**: Fetch seam. Keeping page retrieval behind it is what lets extraction, date parsing and scoring be tested against HTML fixtures with no network, and it is the boundary at which --input-file replaces the network entirely. + diff --git a/.gemini/rules/se-deversity-skill3-pipeline-QueryPlanner.md b/.gemini/rules/se-deversity-skill3-pipeline-QueryPlanner.md new file mode 100644 index 0000000..ee53522 --- /dev/null +++ b/.gemini/rules/se-deversity-skill3-pipeline-QueryPlanner.md @@ -0,0 +1,7 @@ + +# Rules for QueryPlanner + +## Context & Focus +- **Focus**: keep discovery topic-agnostic — the model plans the queries for any topic +- **Avoid**: hardcoding per-topic search terms or a fixed query suffix like " documentation" + diff --git a/.gemini/rules/se-deversity-skill3-pipeline-RetrievalService.md b/.gemini/rules/se-deversity-skill3-pipeline-RetrievalService.md new file mode 100644 index 0000000..5361cbf --- /dev/null +++ b/.gemini/rules/se-deversity-skill3-pipeline-RetrievalService.md @@ -0,0 +1,7 @@ + +# Rules for RetrievalService + +## Thread-Safety Guarantee +- **Strategy**: IMMUTABLE +- **Note**: Collaborators (PageFetcher/HttpClient, DateExtractor, AuthorityScorer) are stateless/immutable; each fetch task builds its own Source and results are merged on the caller thread. Keep it that way — do not share mutable state between fetch tasks. The opt-in `sequential` mode only removes concurrency (fetches run on the caller thread); it cannot weaken the invariant — serial execution is strictly safer than the parallel default it replaces. + diff --git a/.gemini/rules/se-deversity-skill3-pipeline-SearchClient.md b/.gemini/rules/se-deversity-skill3-pipeline-SearchClient.md new file mode 100644 index 0000000..cd0186b --- /dev/null +++ b/.gemini/rules/se-deversity-skill3-pipeline-SearchClient.md @@ -0,0 +1,7 @@ + +# Rules for SearchClient + +## Contract-Frozen Signature +- **Constraint**: You may change internal logic, but MUST NOT modify the method name, parameters, return type, or checked exceptions. +- **Reason**: Discovery seam. BraveSearchClient (live) and FileCorpus (--input-file) both implement it, and isCuratedCorpus() is what tells the pipeline to skip LLM query planning. Removing the default method, or changing what it returns, silently re-enables planning for a corpus that is already the curated result set. + diff --git a/.gemini/rules/se-deversity-skill3-skillspector-InputVetter.md b/.gemini/rules/se-deversity-skill3-skillspector-InputVetter.md new file mode 100644 index 0000000..3859982 --- /dev/null +++ b/.gemini/rules/se-deversity-skill3-skillspector-InputVetter.md @@ -0,0 +1,8 @@ + +# Rules for InputVetter + +## Load-Bearing Oddity +- **Rule**: This looks removable but is deliberate. Refactor only while the invariant holds. +- **Invariant**: A quarantined source is dropped from the set handed to the synthesizer, but its finding is still recorded and still trips the run gate. Redaction runs FIRST and unconditionally, so a secret never reaches the model even when SkillSpector is unavailable — and when it is unavailable nothing is gated, because absence of findings is observed, never asserted. +- **Breaks if changed**: quarantining is treated as resolving the finding, redaction is made conditional on the scanner being present, or a skipped scan is reported as clean + diff --git a/GEMINI.md b/GEMINI.md new file mode 100644 index 0000000..6e49845 --- /dev/null +++ b/GEMINI.md @@ -0,0 +1,62 @@ +# GEMINI.md + +AI guardrails for Google Gemini, generated from source annotations by +[VibeTags](https://github.com/PIsberg/vibetags). The region between the +VIBETAGS-START and VIBETAGS-END markers is regenerated on every compile; +never hand-edit inside it. Per-element detail lives in , +indexed from the block below. + + +# AUTO-GENERATED AI RULES +# Generated by VibeTags | https://github.com/PIsberg/vibetags +# Do not edit manually. + +## 🔒 PII / PRIVACY GUARDRAILS +The following elements handle Personally Identifiable Information (PII). +NEVER include their runtime values in logs, console output, external API calls, +test fixtures, mock data, or code suggestions. + +- `se.deversity.skill3.llm.LocalLlmClient.apiKey`: LLM provider API key — never log, echo, or include in errors/fixtures +- `se.deversity.skill3.pipeline.BraveSearchClient.apiKey`: Brave Search subscription token — never log, echo, or include in errors/fixtures + +## 🧠 CORE FUNCTIONALITY (CHANGE WITH EXTREME CAUTION) +The following elements are well-tested core components. Make changes with extreme caution. + +- `se.deversity.skill3.llm.SkillMdPostProcessor`: Sensitivity: High. Note: Deterministically guarantees SKILL.md spec compliance; model output is never trusted. Changes risk emitting invalid frontmatter — keep the parsing and frontmatter synthesis covered by SkillMdPostProcessorTest. +- `se.deversity.skill3.llm.Verifier`: Sensitivity: High. Note: Accuracy gate that re-grounds claims against the sources. Only worthwhile with a capable model — a weak model rewrites rather than grounds. Keep the prompt strict about supported-claims-only and announced-vs-shipped. + +## 🔐 SECURITY-CRITICAL CODE +The following elements are security-critical. AI must not weaken security properties. Any change must be reviewed for security impact. + +- `se.deversity.skill3.llm.AnthropicChatModel`: Security-critical code [Anthropic API credential handling and hosted-provider network egress]. Do not weaken security properties. Flag any change for security review. +- `se.deversity.skill3.llm.LlmProviderFactory`: Security-critical code [LLM provider credential resolution and model selection]. Do not weaken security properties. Flag any change for security review. +- `se.deversity.skill3.llm.LocalLlmClient`: Security-critical code [outbound LLM-provider credential (Bearer token) handling]. Do not weaken security properties. Flag any change for security review. +- `se.deversity.skill3.llm.NameSanitizer`: Security-critical code [output sanitization: reserved-word stripping must never be weakened]. Do not weaken security properties. Flag any change for security review. +- `se.deversity.skill3.pipeline.BraveSearchClient`: Security-critical code [external-API credential handling and the only network egress with a secret token]. Do not weaken security properties. Flag any change for security review. +- `se.deversity.skill3.pipeline.DiscoveryProvider`: Security-critical code [forwards the Brave subscription token to the search client; must not log it]. Do not weaken security properties. Flag any change for security review. +- `se.deversity.skill3.pipeline.HttpPageFetcher`: Security-critical code [outbound page fetch egress for partly-untrusted URLs; SSRF guard must not be weakened]. Do not weaken security properties. Flag any change for security review. + +## Scoped Rules Index +Detailed per-element guardrails live in scoped rule files that load automatically when you open the matching source file. Consult the referenced file before modifying an element: + +- `se.deversity.skill3.llm.AnthropicChatModel` → `.gemini/rules/se-deversity-skill3-llm-AnthropicChatModel.md` +- `se.deversity.skill3.llm.ChatModel` → `.gemini/rules/se-deversity-skill3-llm-ChatModel.md` +- `se.deversity.skill3.llm.LlmProviderFactory` → `.gemini/rules/se-deversity-skill3-llm-LlmProviderFactory.md` +- `se.deversity.skill3.llm.LocalLlmClient` → `.gemini/rules/se-deversity-skill3-llm-LocalLlmClient.md` +- `se.deversity.skill3.llm.NameSanitizer` → `.gemini/rules/se-deversity-skill3-llm-NameSanitizer.md` +- `se.deversity.skill3.llm.SkillMdPostProcessor` → `.gemini/rules/se-deversity-skill3-llm-SkillMdPostProcessor.md` +- `se.deversity.skill3.llm.Verifier` → `.gemini/rules/se-deversity-skill3-llm-Verifier.md` +- `se.deversity.skill3.model.ContextBundle` → `.gemini/rules/se-deversity-skill3-model-ContextBundle.md` +- `se.deversity.skill3.model.RunManifest` → `.gemini/rules/se-deversity-skill3-model-RunManifest.md` +- `se.deversity.skill3.model.Source` → `.gemini/rules/se-deversity-skill3-model-Source.md` +- `se.deversity.skill3.pipeline.BraveSearchClient` → `.gemini/rules/se-deversity-skill3-pipeline-BraveSearchClient.md` +- `se.deversity.skill3.pipeline.CutoffResolver` → `.gemini/rules/se-deversity-skill3-pipeline-CutoffResolver.md` +- `se.deversity.skill3.pipeline.DiscoveryProvider` → `.gemini/rules/se-deversity-skill3-pipeline-DiscoveryProvider.md` +- `se.deversity.skill3.pipeline.FileCorpus` → `.gemini/rules/se-deversity-skill3-pipeline-FileCorpus.md` +- `se.deversity.skill3.pipeline.HttpPageFetcher` → `.gemini/rules/se-deversity-skill3-pipeline-HttpPageFetcher.md` +- `se.deversity.skill3.pipeline.PageFetcher` → `.gemini/rules/se-deversity-skill3-pipeline-PageFetcher.md` +- `se.deversity.skill3.pipeline.QueryPlanner` → `.gemini/rules/se-deversity-skill3-pipeline-QueryPlanner.md` +- `se.deversity.skill3.pipeline.RetrievalService` → `.gemini/rules/se-deversity-skill3-pipeline-RetrievalService.md` +- `se.deversity.skill3.pipeline.SearchClient` → `.gemini/rules/se-deversity-skill3-pipeline-SearchClient.md` +- `se.deversity.skill3.skillspector.InputVetter` → `.gemini/rules/se-deversity-skill3-skillspector-InputVetter.md` + diff --git a/build.gradle b/build.gradle index 40f8a89..dcb05ab 100644 --- a/build.gradle +++ b/build.gradle @@ -12,7 +12,7 @@ plugins { group = 'se.deversity' version = '0.1.0' -ext.vibetagsVersion = '1.0.0-RC8' +ext.vibetagsVersion = '1.0.0-RC10' // code-karta renders the diagrams under docs/diagrams straight from this source tree. ext.codekartaVersion = '0.2.0'