onto-mcp 0.3.1 → 0.3.2

package/.onto/domains/software-engineering/concepts.md

@@ -1,6 +1,6 @@
 ---
-version: 3
-last_updated: "2026-03-31"
+version: 8
+last_updated: "2026-05-28"
 source: bundled-domain-baseline
 status: established
 ---
@@ -38,7 +38,7 @@ Layer 1 defines what the language/runtime provides. Layer 2 encodes design wisdo
 - [L2] Saga = distributed transactions as a sequence of local transactions with compensating actions. Choreography-based (events) or orchestration-based (coordinator)
 - [L2] Hexagonal (Ports and Adapters) = application logic at center, surrounded by ports (interfaces) and adapters (implementations). Domain independent of infrastructure
 - [L2] Clean Architecture = concentric layers where dependencies point inward. The Dependency Rule: source code dependencies point toward higher-level policies
-- [L2] Layered Architecture = vertical separation (Presentation, Business, Data Access). Each layer depends only on the layer below
+- [L2] Layered Architecture = separation by technical layers such as Presentation, Business/Application, and Data Access. This is distinct from Vertical Slice Architecture, which organizes by feature. Layer direction rules depend on the declared architecture pattern and dependency kind
 - [L2] Microservices = independently deployable services communicating via network. Benefits: independent scaling/deployment. Costs: distributed system complexity
 - [L2] Monolith = single deployable unit. Not inherently bad — simpler deployment, no network latency, easier debugging
 - [L2] Modular Monolith = monolith with enforced module boundaries. Monolith simplicity with microservice-like modularity
@@ -104,6 +104,7 @@ Layer 1 defines what the language/runtime provides. Layer 2 encodes design wisdo
 - [L2] Deprecation = maintaining while announcing future removal. Must specify: what, when removed, and replacement
 - [L2] Semantic Versioning (SemVer) = MAJOR.MINOR.PATCH. MAJOR: breaking. MINOR: backward-compatible features. PATCH: bug fixes. A communication contract — violating it erodes consumer trust
 - [L2] Feature Toggle = enable/disable features at runtime without deployment. Risk: toggle debt from unremoved toggles
+- [L2] Technical Debt = a deliberate shortcut with known future cost, owner, and remediation expectation. It differs from accidental complexity or a defect because the tradeoff is acknowledged and tracked
 - [L2] Trunk-based Development = all developers commit to main with short-lived branches. Requires strong CI and feature toggles
 - [L2] Branch-by-Abstraction = large changes without long-lived branches: introduce abstraction, implement new version behind it, switch, remove old
 
@@ -139,6 +140,10 @@ Layer 1 defines what the language/runtime provides. Layer 2 encodes design wisdo
 - [L3] CSP (Content Security Policy) = HTTP header specifying allowed content sources. Primary defense against XSS
 - [L3] RBAC (Role-Based Access Control) = permissions assigned to roles, users assigned to roles. Simple but coarse-grained
 - [L3] ABAC (Attribute-Based Access Control) = access decisions based on user/resource/environment attributes. More flexible than RBAC, harder to audit
+- [L3] Data Classification = labeling data by sensitivity, regulatory exposure, tenant/user boundary, and handling obligations
+- [L3] Retention Policy = rule defining how long data or artifacts are kept, why they are kept, and when they must be deleted or archived
+- [L3] Deletion/Erasure Path = implemented path that removes or anonymizes data across primary stores, derived stores, indexes, caches, logs, backups, and downstream processors according to the retention/privacy obligation
+- [L3] Data Minimization = collecting, storing, and exposing only the data needed for the declared purpose
 
 ## Testing Terms
 
@@ -162,11 +167,59 @@ Layer 1 defines what the language/runtime provides. Layer 2 encodes design wisdo
 ## DevOps Terms
 
 - [L3] CI/CD = CI: build and test on every commit. CD: automatically deploy verified builds. The pipeline is the automated sequence of these stages
-- [L3] Artifact = versioned, immutable build output (JAR, Docker image, npm package). Never modified — only replaced
+- [L3] Build Artifact = versioned, immutable build output (JAR, Docker image, npm package). Never modified — only replaced
+- [L3] SBOM = Software Bill of Materials. Machine-readable inventory of components and dependency versions included in a build or release
+- [L3] Artifact Attestation = signed or otherwise verifiable statement about how a build/release artifact was produced, by whom/what, from which inputs, and with which verification results
+- [L3] Release Artifact Traceability = ability to trace a deployed artifact back to source revision, build pipeline, dependency set, verification results, approval gate, and deployment environment
 - [L3] Blue-Green Deployment = two identical environments, switch traffic between them. Instant rollback. Cost: double infrastructure
 - [L3] Canary Deployment = route small traffic percentage to new version, increase gradually if healthy
 - [L3] Rolling Deployment = replace instances one at a time. Both versions coexist during rollout
 
+## LLM-Native Engineering Terms
+
+Domain-local definitions in this section own software-engineering usage. Onto/productization core concepts are marked as **domain projections**: the canonical seat remains in `.onto/authority/`, `.onto/principles/`, or `.onto/processes/`, while this file records how the software-engineering domain uses the concept during review.
+
+- [L3] LLM-Native Development = software development where LLMs, agents, prompt/context contracts, retrieval, model providers, semantic evaluation, or AI-assisted workflows materially affect product behavior or engineering workflow. It is now a sub-area of software engineering, not a separate review domain
+- [L3] Behavior-Affecting Artifact = any artifact whose change can alter software behavior, engineering workflow, review outcome, trust status, or release decision. Includes code, config, schemas, prompts, context assembly rules, tool schemas, retrieval policies, eval rubrics, model routes, and generated authority artifacts
+- [L3] Model Provider = an external or local system that serves model inference. Provider identity, API contract, auth mode, rate limits, pricing, and model version are runtime dependencies
+- [L3] Model Version = a specific model release used for inference. Version aliases such as `latest` reduce reproducibility; pinned versions make behavior changes diagnosable
+- [L3] Model Route = the runtime decision that selects a model/provider/profile for a task. A model route must expose the selected provider/model facts, capability requirements, fallback policy, and diagnostic behavior
+- [L3] Prompt Template = a versioned instruction artifact with placeholders filled at runtime. A prompt template change is a behavior change, comparable to code or configuration changes
+- [L3] Context Assembly = the runtime or agent process that selects and orders the information sent to the model. Context assembly owns token budget, provenance, relevance, and omission behavior
+- [L3] LLM Boundary (domain projection) = software-engineering use of the LLM/runtime interface principles in `.onto/principles/llm-runtime-interface-principles.md` and `.onto/principles/llm-native-development-guideline.md`. In this domain, reviews ask which semantic interpretation or judgment is delegated to the LLM and which runtime-owned gates must receive its output
+- [L3] Runtime Boundary (domain projection) = software-engineering use of runtime-owned deterministic authority: binding, validation, state transition, persistence, audit, cost/security gates, idempotency, and authority artifact assembly. The canonical boundary principles live in `.onto/principles/llm-runtime-interface-principles.md`
+- [L3] Middleware Boundary (domain projection) = software-engineering use of middleware-owned transport/adaptation responsibilities: envelope conversion, routing plumbing, auth/context propagation, retry envelopes, and observability plumbing. Middleware must remain a bounded adapter, not a second semantic or policy authority
+- [L3] Ownership Non-Interference (domain projection) = software-engineering review rule derived from the LLM/runtime interface principles: boundary crossings must declare owner, input/output, enforcement profile, artifact or trust status, and diagnostic behavior
+- [L3] Retrieved Context = external material selected for model input by search, RAG, graph traversal, or direct file selection. It must carry provenance when used as evidence
+- [L3] Prompt Injection Boundary = the boundary that treats external content, user text, retrieved text, tool output, and webpages as data rather than instruction authority. Prompt instructions are not a security boundary
+- [L3] RAG Permission Boundary = the requirement that retrieval preserve access control, tenancy, source validation, poisoning checks, provenance, and auditability before content influences model context
+- [L3] Embedding Index Compatibility = the rule that vectors produced by different embedding models, dimensions, preprocessing, or chunking policies are not interchangeable without a declared migration or dual-index strategy
+- [L3] Output Zero-Trust = the rule that LLM output is untrusted until runtime validates it for shape, policy, authorization, provenance, and the specific downstream sink
+- [L3] Sink Validation = validation/encoding/authorization performed for the concrete place where output will be used: shell, SQL, HTML, file path, email, API call, artifact write, or user-facing decision
+- [L3] LLM Agent = an LLM-powered system that observes state, chooses actions, invokes tools, and updates progress toward a goal. It differs from a simple prompt-response call by having an action loop
+- [L3] Agent Functionality = what an agent is technically able to do through tools and runtime capabilities
+- [L3] Agent Permission = what an agent is authorized to do for the current user, tenant, scope, and operation
+- [L3] Agent Autonomy = what an agent may do without human approval. Functionality, permission, and autonomy are separate axes
+- [L3] Tool Schema = the machine-readable contract that tells an agent how to call a tool. It must include name, description, parameter schema, required fields, and result semantics sufficient for agent selection
+- [L3] MCP Tool Boundary = the protocol boundary where an MCP server exposes tools/resources/prompts and a host or agent invokes them. The model requests a tool call; runtime code executes and validates it
+- [L3] Semantic Evaluation = evaluation of usefulness, faithfulness, specificity, actionability, calibration, or other qualities that cannot be proven by deterministic tests alone
+- [L3] Evaluation Baseline = a recorded set of expected examples, rubrics, scores, or comparative outputs used to detect semantic regression and production drift
+- [L3] Production Drift = behavior or quality movement after release caused by data changes, provider/model changes, prompt/context changes, corpus changes, traffic shifts, or external environment changes
+- [L3] Fail-Loud = a diagnostic posture where contract failures stop or surface with explicit failure location, cause, and artifact refs. In LLM-native development, fail-loud reduces exploration cost by making the failing prompt/context/model/tool/schema boundary visible
+- [L3] Fail-Close = a gate posture where contract-missing or unsafe output is blocked from becoming trusted output. Fail-close is a safety gate; fail-loud is the diagnostic visibility expected when the gate closes
+- [L3] Silent Degradation = a fallback, repair, default, or graceful-degradation path that hides the original failure or omits visible loss markers. Silent degradation is usually more costly in LLM-native development because it forces later investigators to rediscover the hidden failure
+- [L3] Graceful Degradation = an intentional product behavior that serves a reduced result when full behavior is unavailable. It is acceptable only when the loss is explicit, logged, and compatible with the user's task
+- [L3] Artifact Truth (domain projection) = software-engineering use of the productization principle that durable artifacts, not transient responses, own process truth. Canonical review artifact seats are defined by `.onto/principles/productization-charter.md` and `.onto/processes/review/record-contract.md`
+- [L3] Provenance = the recorded source, builder/agent, input set, transformation path, verification state, and time/version facts needed to explain why a software artifact, generated artifact, release artifact, or claim should be trusted
+- [L3] Generated Artifact = an artifact authored or transformed by an LLM, agent, generator, build step, or automation. It needs provenance when it affects authority, release, security, or user decisions
+- [L3] AI Supply Chain = the dependency chain for AI behavior: model/provider, dataset/corpus, embedding model/index, prompt framework, tool runtime, eval judge, safety layer, and generated artifacts
+- [L3] AI Governance = accountable management of AI behavior through owner assignment, risk treatment, approval gates, transparency, audit evidence, incident response, and continuous improvement
+- [L3] AI Risk Owner = the accountable role or team that accepts, mitigates, transfers, or rejects material risk introduced by AI behavior
+- [L3] Human Approval Gate = a runtime or process gate requiring human authorization before high-impact AI output, tool execution, release, or user-visible action becomes authoritative
+- [L3] Red-Team/Eval Loop = the feedback loop that turns adversarial findings, incidents, semantic eval results, and production drift into updated prompts, policies, tests, controls, and release gates
+- [L3] AI Incident Disclosure = the operator/user/internal communication path used when AI behavior materially fails, exposes data, misleads users, causes unsafe action, or breaks a trust claim
+- [L3] Context-Isolated Reasoning Unit (domain projection) = software-engineering use of the review/lens execution property defined in `.onto/processes/review/lens-prompt-contract.md`: the reasoning unit receives contracted input, does not share main-context state, and returns contracted output when independent judgment or disagreement preservation matters
+
 ## Document Design Terms
 
 - [L3] Contract Document = specification with 1:1 code correspondence. Violation is a defect
@@ -192,11 +245,20 @@ Layer 1 defines what the language/runtime provides. Layer 2 encodes design wisdo
 ## Homonyms Requiring Attention
 
 - "service": service class (business logic) != microservice (deployment unit) != domain service (DDD, stateless operation) != OS service (daemon)
+- "domain": review/domain-document namespace != business or problem domain != DDD bounded-context domain != Clean Architecture domain/entities layer != ontology property domain
+- "artifact": build artifact (deployable/package output) != authority artifact (truth-bearing record/contract) != generated artifact (authored/transformed by automation) != provenance record (trust evidence) != documentation artifact
 - "model": domain model (business object) != ML/LLM model != MVC model != data model (DB schema)
+- "model version": package/library version != LLM model version != database schema version
+- "agent": LLM agent != software agent (generic autonomous program) != user agent (browser HTTP header)
+- "tool": MCP tool (agent-invocable function) != development tool (IDE/linter) != CLI tool
+- "prompt": system prompt != user prompt != prompt template != MCP prompt primitive
+- "token": authentication token / API key != LLM token (subword unit)
 - "controller": MVC controller != hardware controller != Kubernetes controller (reconciliation loop)
 - "context": execution context (runtime) != Bounded Context (DDD) != React Context != context window (LLM)
+- "memory": process memory (RAM) != agent memory != persistence store != conversation history
+- "alignment": model behavior alignment != UI text alignment != ontology alignment
 - "migration": DB migration (schema change) != system migration (infrastructure move) != data migration (format transform)
-- "validation": input validation (user data) != design validation (architecture review) != schema validation (data vs schema)
+- "validation": input validation (user data) != schema validation (data vs schema) != sink validation (safe use at a downstream sink) != design validation (architecture review) != semantic evaluation (quality judgment)
 - "constraint": data constraint (DB) != design constraint (architecture) != business rule != type constraint (generic bounds)
 - "event": domain event (business) != browser event (click) != system event (OS signal) != CloudEvents (format)
 - "client": HTTP client != client application (frontend) != client (customer) != OAuth client (registered app)

package/.onto/domains/software-engineering/conciseness_rules.md

@@ -1,6 +1,6 @@
 ---
-version: 2
-last_updated: "2026-03-30"
+version: 5
+last_updated: "2026-05-28"
 source: bundled-domain-baseline
 status: established
 ---
@@ -49,6 +49,17 @@ Each rule is tagged with a strength level:
 
 - [MAY-ALLOW] Application-level and infrastructure-level metrics for the same quantity — application metrics (e.g., handler-measured latency, per-endpoint) and infrastructure metrics (e.g., load-balancer-measured latency, per-host) measure the same thing at different granularity and observation points. Retain when the difference matters for diagnosis; consolidate when identical and only one consumer uses them.
 
+### LLM-Native Runtime and Evaluation
+
+- [MUST-ALLOW] Safety policy in both prompt instructions and runtime guardrails — prompt instructions reduce unsafe generation; guardrails block unsafe output. This defense-in-depth duplication is justified when both copies point to the same authority.
+- [MAY-ALLOW] Evaluation criteria in both an eval rubric and a release gate — the rubric defines semantic quality; the gate enforces release policy. Retain only when the gate references the rubric instead of redefining criteria.
+
+### Review Concern Case Overlap
+
+- [MUST-ALLOW] The same case evidence may appear under multiple review concerns when each concern asks a different question. Example: prompt injection can support logic (instruction authority), structure (context assembly seat), dependency (retrieval/source boundary), security (exfiltration), pragmatics (answerable CQ), and axiology (user/operator harm). Domain concern labels are not lens-addition proposals.
+- [MUST-ALLOW] A principle may have separate CQ forms for deterministic correctness, semantic quality, dependency impact, and value tradeoff. Merge only when the questions have the same pass/fail evidence.
+- [MAY-ALLOW] Repeating a short inference path across CQ and case docs is acceptable when it lets a lens use the case without loading a long narrative. Prefer references over copied definitions.
+
 ### Cross-cutting Concerns
 
 - [MAY-ALLOW] Cross-cutting concerns (security, logging, authentication) appearing in multiple modules. Allowed under the separation of concerns (SoC) principle, but copy-paste of identical logic is a removal target.
@@ -86,6 +97,15 @@ Each rule is tagged with a strength level:
 - [SHOULD-REMOVE] Single-implementation interfaces — an interface with exactly one implementing class, created "for testability" or "future flexibility," that has remained single-implementation for an extended period. The interface adds indirection without providing polymorphism. Remove and depend on the concrete class; re-extract when a genuine second implementation arises (YAGNI principle).
 - [SHOULD-REMOVE] Redundant null checks after type-system verification — when the type system guarantees non-null (e.g., non-optional type in TypeScript strict mode, `@NonNull` in Java), a runtime null check duplicates the guarantee without adding safety. Exception: retain checks at system boundaries (external API responses, deserialized data) where the type system cannot verify the actual value.
 
+### LLM-Native Context Noise
+
+- [MUST-REMOVE] Historical migration notes, deprecated domain split rationale, or old LLM-native domain instructions from active execution context — they inflate model context with non-current behavior. Keep them in development-records or archive paths and link only when needed.
+- [MUST-REMOVE] Duplicate prompt templates in agent instructions and prompt-template files — the agent's behavior diverges when one copy changes. Keep one source of truth and reference it.
+- [MUST-REMOVE] Multiple tools with overlapping descriptions and identical practical capability — agents choose non-deterministically unless routing rules distinguish the tools.
+- [MUST-REMOVE] Hidden fallback descriptions that are not connected to diagnostic artifacts — they make failures look successful and increase investigation cost.
+- [MUST-REMOVE] Multiple active definitions of LLM/runtime/middleware ownership, output trust, RAG permission, agent autonomy, or provenance. Keep the definition in concepts.md and express operational consequences in rules/CQs.
+- [MUST-REMOVE] Case-study prose that does not yield a guideline, CQ seed, PASS, and FAIL criterion. Move historical narrative to archive/development records if it remains useful.
+
 ---
 
 ## 3. Minimum Granularity Criteria

package/.onto/domains/software-engineering/dependency_rules.md

@@ -1,6 +1,6 @@
 ---
-version: 2
-last_updated: "2026-03-30"
+version: 6
+last_updated: "2026-05-28"
 source: bundled-domain-baseline
 status: established
 ---
@@ -25,19 +25,45 @@ The dependency graph of packages/modules must be a Directed Acyclic Graph (DAG).
 When a circular dependency is detected, apply one of the following strategies:
 
 - **Dependency Inversion**: If module A depends on module B and B depends on A, extract an interface from the dependency direction that should be reversed. Module A defines the interface; module B implements it. The dependency direction reverses: B now depends on A's interface, breaking the cycle. Cross-reference: 'Direction Rules' (Dependency Inversion Principle)
-- **Event-based decoupling**: Replace direct calls with events. Module A publishes an event; module B subscribes. Neither module imports the other. The event schema becomes the contract. Appropriate when the interaction is asynchronous or fire-and-forget
+- **Event-based decoupling**: Replace direct calls with events. Module A publishes an event; module B subscribes. Neither module imports the other. The event schema becomes the contract and must follow §Event Schema Contract Dependencies. Appropriate when the interaction is asynchronous or fire-and-forget
 - **Shared kernel**: Extract the shared types/functions that both modules need into a third module. Both A and B depend on the shared module, but not on each other. Appropriate when the cycle is caused by shared type definitions. Cross-reference: 'Package/Module Dependency Patterns' (Shared Kernel pattern)
 - Real example: npm detects circular dependencies at install time and logs a warning. Go prohibits import cycles entirely — the compiler rejects them. Python allows circular imports but they cause `ImportError` at runtime if the cycle involves module-level code execution
 
 ## Direction Rules
 
+Direction rules apply to a specific dependency kind and architecture pattern. Do not use
+one global "upper/lower" vocabulary for every architecture.
+
+### Dependency Direction Vocabulary
+
+- **Source-code dependency**: import, reference, build, type, package, or generated-code edge. This is the edge most architecture rules constrain.
+- **Runtime call/data-flow direction**: request, command, query, event, or data movement at runtime. Runtime flow may move opposite to source-code dependency.
+- **Policy/detail direction**: high-level policy/business rules versus low-level implementation detail. This is the axis governed by DIP and Clean/Hexagonal architecture.
+- **Layer order direction**: presentation/application/service/data-access placement in a conventional layered architecture. This is not the same axis as policy/detail.
+- **Contract dependency**: dependence on a schema, port, interface, message format, or published language. Contract dependency can break direct implementation cycles only when the contract has explicit ownership and compatibility rules.
+
+### Pattern Selection Rule
+
+- If a codebase declares Clean Architecture or Hexagonal Architecture, source-code dependencies must follow the inward/port-oriented rule for that pattern.
+- If a codebase declares conventional Layered Architecture, source-code dependencies may flow from presentation/application layers toward lower service/data-access layers, but business policy should still depend on abstractions for replaceable infrastructure.
+- If no architecture pattern is declared, reviews must first classify the intended pattern before applying direction rules. A reviewer must not mix Clean/Hexagonal and conventional layered direction rules on the same edge without an explicit adapter/port explanation.
+
+### Conventional Layered Architecture Direction
+
+- Presentation/API layer -> application/service layer: allowed.
+- Application/service layer -> data-access layer: allowed only through repository/service contracts when replacement, testing, or policy isolation matters.
+- Data-access/infrastructure layer -> application/business layer: prohibited unless it is a callback, plugin, or dependency-injection registration with an explicit boundary.
+- Runtime data flow from lower layers back to upper layers as returned values or events does not imply source-code dependency in that direction.
+
 ### Dependency Inversion Principle (DIP)
 
 High-level modules must not depend on low-level modules. Both must depend on abstractions. Abstractions must not depend on details. Details must depend on abstractions.
 
-- Upper layer -> lower layer: allowed
-- Lower layer -> upper layer: prohibited (layer inversion)
-- Business logic -> direct dependency on external library: discouraged (abstract via interface)
+- High-level and low-level describe policy/detail roles, not directory height or UI/data-access layer position.
+- Policy/business logic -> concrete infrastructure detail: prohibited unless explicitly accepted as a small/simple-system tradeoff.
+- Policy/business logic -> abstraction/port: allowed.
+- Infrastructure detail -> abstraction/port it implements: allowed.
+- Business logic -> direct dependency on external library: discouraged; abstract via interface/port when replacement, testing, security, or policy isolation matters.
 - Test -> production code: allowed
 - Production code -> test: prohibited
 
@@ -45,6 +71,10 @@ High-level modules must not depend on low-level modules. Both must depend on abs
 
 Source code dependencies must point inward. The innermost layer (Entities/Domain) depends on nothing. The outermost layer (Frameworks/Drivers) depends on everything inward. No inner layer may import, reference, or name anything from an outer layer. Cross-reference: structure_spec.md 'Architectural Patterns' (Clean Architecture)
 
+### Hexagonal Architecture Dependency Rule
+
+Domain/application logic owns or depends on ports. Adapters depend on the ports and implement or call them. Domain/application logic must not depend on concrete adapter implementations. Runtime calls may enter through inbound adapters or leave through outbound adapters, but source-code dependencies remain toward the domain/ports side.
+
 ### Stable Dependencies Principle (SDP)
 
 Depend in the direction of stability. A module should depend only on modules that are more stable (harder to change) than itself. Stability is measured by the ratio of incoming dependencies (afferent coupling) to total dependencies. A module with many dependents and few dependencies is stable — changing it would break many consumers, so it resists change.
@@ -82,7 +112,7 @@ A package should be as abstract as it is stable. Stable packages (many dependent
 
 ### Anti-corruption Layer
 
-- When integrating with an external system whose model does not match the internal domain, create an adapter layer that translates between the two. Internal code depends on the adapter, not on the external model
+- When integrating with an external system whose model does not match the internal domain, create an adapter layer that translates between the two. Policy/domain code depends on an internal port or translated internal model; the adapter depends on the external model and performs translation at the boundary. Runtime flow may cross the adapter, but source-code dependency from policy/domain code to a concrete adapter is prohibited in Clean/Hexagonal designs
 - Real example: Stripe SDK wraps Stripe's REST API with typed objects matching the consumer's language idioms
 
 ### Published Language
@@ -90,6 +120,14 @@ A package should be as abstract as it is stable. Stable packages (many dependent
 - When two systems exchange data, define a shared contract (schema, message format) that both agree to. Neither side's internal model leaks through the contract. Versioned independently
 - Real example: Protocol Buffers `.proto` files — both client and server generate code from the same definition
 
+### Event Schema Contract Dependencies
+
+- Event producer and consumer must depend on a versioned event/message schema or published language, not on each other's implementation details
+- The event schema must have an owner, versioning policy, compatibility rules, and decommissioning path
+- Producers must not shape events around consumer-only implementation needs. Consumers must tolerate compatible additions and ignore unknown fields where the format permits
+- Breaking event schema changes require consumer impact analysis, migration or dual-publish/dual-read window, and stale-subscriber detection
+- Event schema dependencies should be represented as contract dependencies in dependency graphs so event-based decoupling does not hide a semantic cycle
+
 ### Conformist
 
 - When a dependency's model cannot be changed (third-party API, legacy system), the consumer adopts the dependency's model as-is. Simplest pattern but creates tight coupling
@@ -188,6 +226,13 @@ Cross-reference: logic_rules.md 'Type System Logic' (enum/union breaking changes
 - **Supply chain security**: Verify integrity via checksums (go.sum), signatures (Sigstore), and SBOM generation. Real example: `event-stream` npm incident (2018) — malicious dependency added by compromised maintainer
 - **Update strategy**: Dependabot/Renovate create PRs for updates. Auto-merge patches (semver-compatible), manual review for minor/major. Full test suite required on every update PR
 
+### Release Artifact Provenance
+
+- Build and release artifacts must be traceable to source revision, build workflow, dependency inventory, verification result, approval gate, and deployment environment
+- SBOMs and attestations are release dependencies when downstream consumers, operators, compliance, incident response, or security review depend on reconstructing what was shipped
+- Provenance for conventional build/release artifacts is not optional merely because the system also records AI-generated artifact provenance. AI provenance and release provenance answer different trust questions and both must be present when both artifact types affect authority or release
+- A release gate that verifies only package installation or test success is incomplete when the release claim requires signed artifacts, dependency inventory, vulnerability status, or reproducible build evidence
+
 ## Referential Integrity
 
 - A module referenced by import/require must actually exist
@@ -204,11 +249,36 @@ Cross-reference: logic_rules.md 'Type System Logic' (enum/union breaking changes
 ## External Dependency Management
 
 - Production dependencies and development-only dependencies must be distinguished (dependencies vs devDependencies)
-- External API calls must have a fallback path in case of failure. Cross-reference: 'Runtime Dependency Rules' (Circuit Breaker, Timeout and Retry Policies)
+- External API calls must declare failure semantics: retry, timeout, circuit breaker, explicit degraded behavior, or fail-loud/fail-close behavior. A fallback is required only when the product contract promises continued reduced service
 - The license of external dependencies must be compatible with the project license
 - For detecting changes from external-service-based sources, using service-provided metadata (lastModified, etc.) is advantageous for preventing false positives
 - A pattern that concentrates external interface definitions in a single file (like MCP tool definitions) is prone to growing into a God Module. A distributed registration pattern maintains correct dependency directions
 
+### LLM/Agent Dependency Management
+
+- Model provider APIs are external dependencies. Breaking changes include model deprecation, behavior changes between pinned versions, pricing changes, rate-limit changes, auth changes, and response-format changes
+- Model/provider migration requires impact analysis across prompt templates, tool schemas, retrieval policy, evaluation baselines, production dashboards, and cost budgets
+- MCP server schemas are API contracts. New required tool parameters, result-shape changes, removed tools, or changed failure semantics are breaking changes for agents and hosts
+- Embedding model changes require re-indexing stored vectors. Embeddings from different models are not comparable, so partial migration must keep old and new indexes separated until cutover
+- LLM framework upgrades can change default prompts, chunking, routing, retry, or output parsing behavior. Treat framework defaults as behavior-affecting dependencies and verify against the semantic evaluation suite
+- If an LLM dependency is unavailable during a development/review/authority path, the default is fail-loud. A fallback may run only if the contract declares its lost capability, diagnostic artifact, and trust status
+
+### AI Supply Chain and Provenance
+
+- AI supply chain dependencies include model/provider, model version or alias, dataset/corpus, embedding model, embedding index, prompt framework, eval judge, tool runtime, safety layer, generated artifact builder, and generated artifact inputs
+- Generated artifacts that affect authority, release, security, user decisions, or review outcomes must preserve provenance: source refs, builder/agent, input set, transformation path, verification state, and relevant model/provider facts
+- Evaluation datasets, rubrics, AI-as-judge prompts, and judge models are dependencies. Changing any of them can change apparent quality without changing product behavior
+- Retrieval corpora are dependencies, not passive content. Corpus ingestion, source lifecycle, tenant/user permissions, poisoning controls, and deletion/retention rules affect behavior and trust
+- Prompt packages, system instructions, and tool descriptions are behavior dependencies. If they are injected from host configuration, the host route must be treated as a dependency boundary
+- A dependency update that changes LLM behavior must be evaluated with semantic regression evidence or an explicit risk acceptance. Package version success alone is insufficient
+
+### Dependency Direction for AI Boundaries
+
+- Runtime may depend on prompt/context/tool configuration as input artifacts, but prompt text must not become the runtime authority for validation, authorization, persistence, or idempotency
+- Middleware may depend on runtime schemas for transport and envelope conversion, but middleware must not become the source of truth for semantic policy or artifact authority
+- Agents may depend on tool schemas and capability descriptions, but tool implementations must not depend on agent natural-language reasoning for security or data integrity
+- Retrieval output may depend on source corpora and indexes, but authority claims must depend on provenance-bearing refs, not on generated text alone
+
 ## Related Documents
 - concepts.md — term definitions for dependency, source of truth, contract, API versioning, etc.
 - structure_spec.md — layer structure principles, module structure rules, architectural patterns