Immutable. This exact content is served forever at /api/v1/blob/8daf20d32076c9ef.
<!-- VIBETAGS-START --> # Skill3 — AI Guardrail Rules > Complete AI guardrail configuration generated from source annotations by VibeTags. This document contains the full set of AI guardrail rules for this project. AI tools with large context windows (such as Windsurf Cascade, Claude 4.6, or Gemini 1.5 Pro) may load this file directly instead of fetching individual documentation pages. ## Locked Files (Do Not Edit) The following files are locked. AI tools MUST NOT propose modifications to them. ## Contextual Rules These files have specific context and focus areas for AI assistance. ### se.deversity.skill3.pipeline.CutoffResolver - **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 ### se.deversity.skill3.pipeline.QueryPlanner - **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" ## PII / Privacy Guardrails Never include runtime values of the following elements in logs, console output, external API calls, test fixtures, or mock data. ### se.deversity.skill3.llm.LocalLlmClient.apiKey - **Reason**: LLM provider API key — never log, echo, or include in errors/fixtures ### se.deversity.skill3.pipeline.BraveSearchClient.apiKey - **Reason**: Brave Search subscription token — never log, echo, or include in errors/fixtures ## 🧠 Core Functionality The following elements are well-tested core functionality. 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. ## 🔐 Contract-Frozen Signatures The following elements have frozen public API signatures. Internal implementation may be changed, but you MUST NOT alter method names, parameter types, parameter order, return types, or checked exceptions. ### se.deversity.skill3.llm.ChatModel - **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. ### se.deversity.skill3.pipeline.PageFetcher - **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. ### se.deversity.skill3.pipeline.SearchClient - **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. ## 🧵 Thread-Safe by Design These elements are explicitly designed to be thread-safe via the named strategy. Preserve the synchronization invariant on every change. ### se.deversity.skill3.pipeline.RetrievalService - **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. ## ❄️ Immutable Types The following types are immutable. Never introduce non-final fields, setters, or mutating methods. ### se.deversity.skill3.model.ContextBundle - Immutable type — never introduce non-final fields, setters, or mutating methods. - **Note**: Immutable record; the sources list is defensively copied in the compact constructor. ## Architectural Boundary Constraints Strict architectural layering must be respected. No illegal references or imports. ### se.deversity.skill3.model.Source - **Belongs to 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 ## Schema & Serialization Safety Schema and serialization compatibility must be strictly preserved. ### se.deversity.skill3.model.RunManifest - Schema and serialization safety. Restrict changing serialization formats, database fields, or API models without a migration path. ## ♻️ Idempotency Guarantees These operations are idempotent — calling multiple times must produce the same result as calling once. ### se.deversity.skill3.llm.SkillMdPostProcessor.render(java.lang.String,se.deversity.skill3.model.ContextBundle,java.time.LocalDate) - Idempotency guaranteed. Multiple invocations must produce the same result as a single invocation. - **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. ## 🔐 Security-Critical Code These elements are security-critical. Do not weaken security properties. Every change requires security review. ### se.deversity.skill3.llm.AnthropicChatModel - Security-critical code (aspect: Anthropic API credential handling and hosted-provider network egress). - Never weaken security properties. Every change requires explicit security review. ### se.deversity.skill3.llm.LlmProviderFactory - Security-critical code (aspect: LLM provider credential resolution and model selection). - Never weaken security properties. Every change requires explicit security review. ### se.deversity.skill3.llm.LocalLlmClient - Security-critical code (aspect: outbound LLM-provider credential (Bearer token) handling). - Never weaken security properties. Every change requires explicit security review. ### se.deversity.skill3.llm.NameSanitizer - Security-critical code (aspect: output sanitization: reserved-word stripping must never be weakened). - Never weaken security properties. Every change requires explicit security review. ### se.deversity.skill3.pipeline.BraveSearchClient - Security-critical code (aspect: external-API credential handling and the only network egress with a secret token). - Never weaken security properties. Every change requires explicit security review. ### se.deversity.skill3.pipeline.DiscoveryProvider - Security-critical code (aspect: forwards the Brave subscription token to the search client; must not log it). - Never weaken security properties. Every change requires explicit security review. ### se.deversity.skill3.pipeline.HttpPageFetcher - Security-critical code (aspect: outbound page fetch egress for partly-untrusted URLs; SSRF guard must not be weakened). - Never weaken security properties. Every change requires explicit security review. ## Deterministic Pure Functions The following elements must remain pure functions without side effects or mutations. ### se.deversity.skill3.llm.NameSanitizer.sanitize(java.lang.String) - **Requirement**: Mathematically pure function. No side effects. ## Framework-Free Domain Entities The following elements are pure Domain Models. Do not import Spring, JPA/Hibernate, Jackson, or other framework packages. ### se.deversity.skill3.model.Source - **Domain Boundary**: Framework-agnostic Domain Entity. ## Load-Bearing Oddities These look wrong, redundant, or over-defensive and are deliberate. Refactoring is allowed only while the stated invariant survives. ### se.deversity.skill3.pipeline.FileCorpus - This code is deliberate, not accidental. - **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 - Edits are allowed as long as the invariant survives. ### se.deversity.skill3.skillspector.InputVetter - This code is deliberate, not accidental. - **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 - Edits are allowed as long as the invariant survives. <!-- VIBETAGS-END -->