Praxis Config Domain Decisions
Use this skill for governed domain decisions in praxis-config-starter. Domain rules, domain knowledge, publications, and materializations are canonical semantic decisions; forms, tables, option sources, actions, UI rules, and runtime artifacts are derived projections.
Source Audit
Inspect the owner before editing:
praxis-config-starter/AGENTS.md
docs/2026-04-federated-domain-catalog-rfc.md
docs/domain-catalog/**
docs/ai/categorical-field-semantics-v1.md
docs/ai/domain-rule-timeline-v*.md
src/main/java/org/praxisplatform/config/controller/DomainRuleController.java
src/main/java/org/praxisplatform/config/controller/DomainKnowledgeChangeSetController.java
src/main/java/org/praxisplatform/config/controller/DomainCatalogController.java
src/main/java/org/praxisplatform/config/controller/DomainFederationController.java
src/main/java/org/praxisplatform/config/service/DomainRuleService.java
src/main/java/org/praxisplatform/config/service/DomainRuleSnapshotService.java
src/main/java/org/praxisplatform/config/controller/DomainRuleSnapshotController.java
src/main/java/org/praxisplatform/config/domain/DomainRuleSnapshot.java
src/main/java/org/praxisplatform/config/domain/DomainRuleSnapshotHead.java
src/main/java/org/praxisplatform/config/domain/DomainRuleSnapshotEvent.java
src/main/java/org/praxisplatform/config/service/DomainKnowledgeChangeSetService.java
src/main/java/org/praxisplatform/config/service/DomainKnowledgeChangeSetValidator.java
src/main/java/org/praxisplatform/config/service/DomainFederationQueryService.java
src/main/java/org/praxisplatform/config/service/DomainFederationRetrievalPolicyService.java
src/main/java/org/praxisplatform/config/service/DomainFederationIngestDryRunService.java
src/main/java/org/praxisplatform/config/service/DomainFederationIngestPersistenceService.java
src/main/java/org/praxisplatform/config/service/DomainFederationReleaseService.java
src/main/java/org/praxisplatform/config/service/RagProjectKnowledgeDerivedIndexService.java
src/main/java/org/praxisplatform/config/ai/authoring/AgenticAuthoringSemanticDecisionPolicy.java
src/main/java/org/praxisplatform/config/ai/authoring/AgenticAuthoringSemanticMaterializationPolicy.java
src/main/java/org/praxisplatform/config/ai/authoring/AgenticAuthoringLlmIntentResolverService.java
src/main/java/org/praxisplatform/config/ai/authoring/AgenticAuthoringIntentResolverService.java
src/main/java/org/praxisplatform/config/ai/authoring/AgenticAuthoringTurnEngine.java
src/main/java/org/praxisplatform/config/ai/authoring/AgenticAuthoringDomainCatalogCandidateEnhancer.java
src/main/java/org/praxisplatform/config/ai/authoring/AgenticAuthoringDomainCatalogHints.java
src/main/java/org/praxisplatform/config/domain/DomainRuleDefinition.java
src/main/java/org/praxisplatform/config/domain/DomainRuleMaterialization.java
src/main/java/org/praxisplatform/config/domain/DomainKnowledgeChangeSet.java
src/main/resources/db/migration/V18__create_domain_knowledge_layer.sql through V26__add_domain_knowledge_evidence_lifecycle.sql
src/main/resources/db/migration/V30__create_domain_rule_snapshot_control_plane.sql
docs/domain-rules/snapshot-control-plane-v1.md
praxis-ui-angular/projects/praxis-core/src/lib/services/domain-rule.service.ts
praxis-ui-angular/projects/praxis-core/src/lib/services/domain-knowledge.service.ts
praxis-ui-angular/projects/praxis-core/src/lib/services/domain-catalog.service.ts
praxis-ui-angular/projects/praxis-core/src/lib/ai/domain-catalog-context-pack.ts
- focused domain rule, domain knowledge, catalog, federation, timeline, and migration tests.
Canonical Boundary
/api/praxis/config/domain-rules/** owns intake, definitions, status transitions, simulations, publications, materializations, timelines, explainability, decisionDiagnostics, immutable snapshot persistence, active RuleSet heads and rollback.
/api/praxis/config/domain-knowledge/change-sets/** owns governed knowledge patch creation, validation, review, apply, timeline, evidence lifecycle, and derived Project Knowledge indexing.
Domain catalog/federation publishes semantic graph context and relationships for AI grounding. It must not be reduced to labels.
Agentic authoring is a routing surface for these decisions, not the owner of the business rule. When the LLM resolver sets requiresGovernedAuthoring=true, the canonical route is changeKind=route_shared_rule_authoring with no visualizationDecision; the turn must not continue as a dashboard, chart, table, form, page preview, or local component apply.
Layer Model
Keep these owners and lifecycles distinct:
- Domain Catalog releases are immutable producer snapshots. Their RAG documents are derived indexes, not the transactional source of truth.
- Domain Federation is a validated, LLM-safe read model over accepted releases. Ingestion creates a
candidate; explicit activation makes it authoritative and supersedes the prior active release.
- Domain Knowledge is a governed, change-set-versioned semantic graph of concepts, aliases, bindings, relationships, and evidence. It does not execute business rules.
- Domain Rule definitions hold reusable decision intent, condition, parameters, evidence refs, owner, steward, and governance independently from any component.
- Materializations project an approved/published definition into target artifacts. Angular, Java validation, option sources, workflow actions, and approval policies consume those projections; they do not become the rule owner.
Domain Rule Workflow
- Resolve tenant, environment,
resourceKey, ruleType, context, evidence, and semantic owner through governed metadata/catalog/tooling before intake.
POST /domain-rules/intake persists a draft definition and returns grounding plus decisionDiagnostics. Do not treat the prompt or assistant text copied into the definition as durable Domain Knowledge evidence.
POST /domain-rules/simulations may use a persisted definition or an ad hoc request. The current simulation detects approved/active overlapping coverage, predicts target materializations, derives required approvals and publication readiness; it does not execute the rule condition against business records or prove business outcomes.
- Review
existingCoverage, predictedMaterializations, requiredApprovals, warnings, explainability, and timeline evidence before publication. Existing approved/active coverage and declared approvals block publication.
To approve a governed definition, the authenticated reviewer needs the official
RULE_DEFINITION_APPROVER role and an actorRef listed in
governance.requiredApprovals or governance.authorizedApprovers; the
reviewer must differ from the server-authenticated author. Preserve the
author/reviewer/publisher separation. Verify the persisted definition
approval against DomainRuleDefinitionFingerprint.sha256 and the actual
derived artifact through their canonical owners; do not normalize a hash's
letter case or change production to satisfy a legacy fixture. Definition
approval and RuleSet snapshot/composition approvals are distinct gates.
POST /domain-rules/publications requires a persisted definition. Only approved or active satisfies the publication approval gate; draft and proposed return approval_required, while terminal/inactive states are blocked. Governed definitions must be created as draft or proposed and pass explicit authorized transitions before publication. Do not relax this lifecycle to repair an outdated smoke fixture.
- Publish or create target materializations and preserve stable key, target identity,
sourceHash, validation result, status, and materialization outcome diagnostics. A stable-key collision with another definition or changed derived source hash must fail instead of silently overwriting a projection.
The current auto-derived publication targets are:
selection_eligibility -> option_source/resource-option-source
- validation-family rules ->
backend_validation/resource-validation
workflow_action_policy -> workflow_action/resource-workflow-action
approval_policy -> approval_policy/resource-action-approval
Other predicted targets, including form guidance, may require an explicit materialization. Never infer that a predicted target was persisted; inspect materializations and publicationDiagnostics.materializationOutcomes.
Preserve Materialization Application History
For persistence/lifecycle changes, read Config's
docs/domain-rules/materialization-application-history.md, migration V63,
DomainRuleMaterialization, and DomainRuleApplicationHistoryPostgresTest.
Use the existing materialization identity and V55 unique applied head; do not
create another head store to compensate for an incomplete reader.
- Preserve
everApplied=true through every apply/revert/supersede path. Legacy
null is inconclusive, never false. New/imported superseded rows cannot claim
false; inconclusive legacy rows retain null. New drafts start false; the migration uses
exact linked application events or applied status/timestamp as positive proof.
- Keep both publication and explicit transition in the Config transaction.
Do not delete/reidentify historical materializations, mutate applied events,
or truncate history to repair a failed publication. Preserve orphan events and
migration guards in retention and restore procedures.
- Leave a new entity's
rowVersion null for Spring Data persist, even with an
assigned UUID. JPA increments once; V63 also advances SQL-only updates without
double-incrementing ORM writes. SQL compare-and-set still needs an expected
version predicate and row-count check. HTTP 409 means reload and reassess,
not blind retry, and does not add client If-Match to materialization commands.
- Run the focused PostgreSQL history test on canonical migrations, plus
DomainRuleServiceTest and DomainRuleConcurrencyResponseTest. Hibernate
create-drop does not prove upgrade/backfill or database guards. Prove candidate
consumption in Quickstart without claiming a local SNAPSHOT is a release.
- For operational admission, use Config's public Java
OperationalPolicyService.resolveOperationalPolicy(target, resolvedPrincipal);
never the UX materialization list. Inspect OperationalPolicyTarget,
OperationalPolicyResolution, the exact repository snapshot query, and
docs/domain-rules/operational-policy-resolution.md in Config before changing it.
- Preserve all four resolution states. NEVER_APPLIED permits continuation only
under a provider's explicit ALLOW_IF_NEVER_APPLIED policy and mandatory lookup.
Withdrawal, unknown history, malformed/mismatched evidence and unavailability
block. A verified ALLOW bypasses only this gate, never authorization or business
invariants. Existence of the target remains the host registry's responsibility.
- New creation/publication/application of approval, workflow and backend-validation
policies must declare BLOCK or ALLOW in the existing definition parameters slot
(approvalPolicy, availabilityPolicy or validationPolicy). Derive and verify the
payload/hash before replacing a head. Keep ALLOW restrictive: no condition,
requirements/groups/blockedWhen, hidden nested action requirements or unsupported
execution parameters, even if false/zero/empty. Publication approvals remain
distinct and mandatory under their governance. Preserve exact persisted numeric
semantics in these producers and the reader; a canonical hash does not repair a
payload narrowed to double.
- Missing
effect in operational policy slots is rejected fail-closed (400 Bad Request / MISSING_OPERATIONAL_POLICY_EFFECT); never infer an implicit BLOCK or permissive fallback. Unverifiable hashes require a governed replacement definition with distinct identity at the same target; never rewrite history. /definitions/{id}/facts (praxis.domain-rule-fact-catalog.v1) supports number-array/array<number> and returns facts: [] for non-fact UI rule families (visual_guidance, form_rule, color_palette) or unhydrated drafts, while governed condition authoring requires a complete factCatalog.
- Keep publish/status transitions/promotion under the Config PostgreSQL transaction
scope mutex, acquired before loading lifecycle inputs. Require READ COMMITTED and
a clean Config persistence context on entry; reject external pending entity
changes before autoflush. Refresh clean preloaded inputs under the lock and
recheck scope. Promotion's inserted version is flushed under the already-held
mutex before its nested transition. Do not implement H2/no-op locking in production.
- The reader captures one exact SQL snapshot with orphan history and binds ordered
identity/revision/status/hash evidence in its fingerprint. Never-applied drafts
and observedAt do not change operational identity. Bounds (4,096 relevant rows,
oversized JSON evidence) fail closed, not truncated into permission. Digests are
not signatures against coherent administrative SQL changes; services remain the
supported writer. Do not promise instantaneous Config-to-domain revocation.
- Add
DomainRuleLifecycleConcurrencyPostgresTest, OperationalPolicyContractTest,
OperationalPolicyServiceTest and DomainRuleChangeWorkspaceServiceTest to the
focal history/service tests when changing this seam. Prove the isolated candidate
in Quickstart with both praxis.palette.proof and praxis.operational.policy.proof
enabled: Config PostgreSQL, authenticated publication/withdrawal/replacement,
Java resolution and exact nested JAR. A test fixture is not proof of migrations,
and this SDK alone does not make a bulk provider READY.
Runtime Snapshot Control Plane
Treat a runtime snapshot as a governed aggregate, not as an opaque DomainRuleMaterialization payload. The public runtime-neutral snapshot record and compiler belong to praxis-rules-engine; Config Starter owns the append-only JPA store, publication transaction, active head, event history, HTTP concurrency and rollback.
- Require source provenance, approved definitions, and at least two distinct approvers before snapshot publication.
- Validate Java bindings with a planning-only exact-coordinate registry. Config Starter must not instantiate or execute host Java implementations.
- Publication persists immutable content and a
PUBLISHED event only. Its response is DomainRuleSnapshotStoredResponse; the host-neutral composition receipt in praxis-config-contracts carries only snapshot key, RuleSet key/version and content hash. Neither receipt establishes selection or readiness.
- Read the actual head before conditional lifecycle operations. Use strong
If-Match for an existing head or explicit If-None-Match: * for verified absence. Publication never manufactures an initial head. Initial activation requires a REQUIRED rollout policy, positive quorum and real host probes; do not substitute OBSERVE_ONLY, allow-all or a synthetic head.
- Keep
snapshotContentHash separate from headEtag: immutable content uses the former; explicit activation/rollback rotates the latter and advances activation revision, including rollback to previously seen content. New PUBLISHED events have no head ETag or activation revision, even when a head already exists. Preserve historical event bytes without granting candidate execution authority.
- Serialize publication, rollout lifecycle, policy and selection changes through the canonical transactional tenant/environment/RuleSet lock, including first creation. Reject dirty external Config persistence contexts before autoflush and refresh clean lifecycle inputs after acquiring the lock. Use the canonical directed refresh with
PESSIMISTIC_WRITE before evaluating CAS; locking a stale cached version through a repository query first can raise an optimistic-lock failure before the intended precondition check. Never clear the caller's persistence context silently. Observational probes use the directed rollout row lock; they do not select authority or require an additional scope lock.
- Separate historical integrity from executable admission. Verify envelope, hash, provenance, composition and approvals before reporting compatibility. Intact older tuples may be read as history and classified
RUNTIME_INCOMPATIBLE; corruption is INVALID. Intact pre-manifest history remains REPUBLICATION_REQUIRED; corrupted pre-manifest history is INVALID, and neither is returned through the immutable detail route or admitted as an executable candidate. Execution-facing findActive/head reads, activation and rollback require the current compiler and catalog; historical detail reads do not.
- Every non-READY version has
UNAVAILABLE action, even if historically selected. READY without a head offers CREATE_ROLLOUT; it does not authorize direct activation. Rollout expected snapshot/head-ETag fields represent absence only as a complete null pair.
- Immutable reads use content validators. Head/status is an operational projection that may change when runtime/catalog changes without rotating the head: return
no-store and re-evaluate rather than answering 304 solely from head ETag.
- Rollback selects a valid compatible prior publication under authorization/CAS and preserves the canonical emergency policy without imposing a new rollout quorum. Do not silently recompile or rewrite a historical 1.4 snapshot to make it 1.5-compatible.
- Keep evaluation out of Config Starter. The consuming host compiles with its real executable registry before reporting candidate admission; only explicit selection can replace its active plan.
Inspect DomainRuleSnapshotVerifier, DomainRuleSnapshotScopeLock, DomainRuleRolloutService, DomainRuleEntityRefresh, snapshot-control-plane-v1.md, staged-activation-readiness-v1.md and the corresponding migration before extending this boundary. Verify the published coordinates contain this separation; source-only G2 changes are not an adopted release.
For control-plane changes, prove publication with unchanged/absent head, initial required-quorum activation, stale conditions, concurrent first publications/activations, dirty and preloaded JPA contexts, approval/provenance failure, historical integrity versus compatibility, same-line rollback/anti-ABA, transaction rollback and cross-scope rejection. Database-dependent proof uses exclusively assigned remote Neon owner/runtime identities; unit mocks do not prove locking or transaction rollback.
Use only canonical status endpoints. Definition transitions allow review paths including deprecated -> active, but rejected and retired are terminal. Materializations may recover from failed, superseded, or reverted only through draft or pending_review; they cannot jump directly back to applied.
Agentic Handoff
- Shared-rule turns must be resolved semantically by
AgenticAuthoringLlmIntentResolverService or governed evidence, then converted by AgenticAuthoringIntentResolverService into a route that carries shared-rule-authoring-required.
AgenticAuthoringTurnEngine should surface the handoff and diagnostics, not fabricate a component preview, dry-run patch, page plan, or applyable artifact. canApply must remain false until a governed decision/materialization contract exists.
- A consultative catalog question such as "which governed data can I use?" remains read-only and uses
artifactKind=api_catalog plus answer_api_catalog_question; it must not be escalated to shared-rule authoring unless the user actually asks to define or change a reusable business decision.
- A local UI request such as formatting, masks, labels, component layout, columns, filters, or badges is not a domain decision unless the semantic intent includes reusable policy, eligibility, approval, compliance, privacy, access, validation, or enforcement.
- When a route is blocked by
shared-rule-authoring-required, the correct next implementation step is to connect the assistant handoff to /domain-rules/intake, simulation, review, and publication. Do not bypass the gap with keyword routing or local preview heuristics.
Domain Knowledge Workflow
- LLM-authored change sets must begin as
proposed, include stable operation ids, reasons, evidence refs, confidence in [0,1], and a target within the request tenant/environment. Raw prompts, transcripts, or chat memory are not canonical evidence.
- Creation is idempotent only when the same change-set key has the same patch hash and author identity. Reusing a key with different semantics must fail.
- Validation, review, and apply are separate operations. Approval requires a valid stored validation result and reviewer; apply requires
approved, rechecks validity, and is idempotent after applied.
- The validator recognizes concept, alias, binding, relationship, visibility, summary, add-evidence, and revert-evidence operation types, but the current apply service executes only
add_evidence and revert_evidence. Treat all other operations as suportado-parcialmente; do not advertise them as operational until an applier and focused proof exist.
- Applying evidence updates the Project Knowledge derived index. Revert deactivates the evidence; an active replacement marks the previous evidence
superseded, otherwise it becomes reverted.
- Timelines and responses expose safe summaries. Do not rehydrate raw patch payloads, prompts, private evidence, or chat transcripts into UI lifecycle events.
- Domain-rule timelines are safe persisted observability projections, not a second source of business truth. Add or interpret timeline events only from persisted domain-rule sources or an explicit command/event ledger; do not backfill missing events from DTO timestamps, simulation ids, AI turn logs, frontend handoff state, quickstart smoke output, prompts, assistant messages, conditions, parameters, or materialized payloads. A blocked/rejected/ad hoc operation without a durable event source is a governance observability gap, not permission to invent a timeline fact.
Grounding Safety
- Domain Catalog v0.2 and Federation provide semantic context, ownership, vocabulary, evidence, relationships, visibility, and retrieval policy. They do not define or execute final business rules.
- Apply
aiUsage.visibility, contract visibility, confidence, tenant/environment scope, release identity, and retrieval policy before returning LLM context. Never bypass deny or deny_for_llm for ordinary authoring.
- Prefer an active persisted federation release; use catalog projection fallback only as declared by the query response. Preserve
sourceMode, release keys, policy report, evidence refs, and redaction decisions.
- The existing
policy_reference option-source prediction contains residual text matching after semantic scope resolution. Do not extend it or use it as primary intent routing; require an explicit canonical ruleType/target contract for new behavior.
Reactive Determination Handoff
When a governed rule materializes as a Reactive Determination, keep Config as
the decision/snapshot owner and publish a typed
DomainRuleReactiveDeterminationSpec with stable definition identity, scope,
form modes, trigger, bindings, provenance, and target coverage. Metadata Starter
compiles the public operation projection; Angular executes only that projection.
Do not emit legacy Form Effect payloads or make the form infer determination
selection from field names. Pair with praxis-reactive-determinations for the
complete snapshot-to-runtime proof.
Decision Rules
- If a request is about a shared business rule, validation, eligibility, compliance, approval, or policy over a resolved resource, route to domain decisions before component preview/apply.
- UI, option sources, backend validation, workflow actions, and approval policies should be materializations of the governed decision when possible.
- Treat
requiresGovernedAuthoring=true, route_shared_rule_authoring, and shared-rule-authoring-required as blocking signals for ordinary UI materialization. They are not warnings that can be ignored by the preview/apply pipeline.
- Preserve
decisionDiagnostics, explainability, publication diagnostics, materialization outcomes, timeline events, statuses, source hashes, and canonical owner fields.
- Do not report
simulation.result=pass as a successful evaluation of business data; it currently describes authoring/coverage diagnostics.
- Status transitions are directional; use the canonical transition endpoints and never mutate status fields or projection records directly.
- Domain Knowledge apply is separate from approval and must validate scope, validation result, lifecycle, and evidence state.
- Project Knowledge used in authoring is derived from governed active evidence, not raw prompts or stale chat history.
- Agentic semantic decision/materialization policies are the boundary that prevents prompts, context hints, or weak candidates from becoming executable domain/materialization decisions. Preserve tests that distinguish consultative API/domain catalog answers, governed exploration, resource-choice clarification, explicit materialization, and dashboard/chart/table classification before allowing preview/apply.
- Treat semantic materialization failures such as
semantic-preview-primary-component-required,
semantic-preview-chart-required, semantic-preview-resource-binding-mismatch,
semantic-preview-axis-schema-verification-required, or
semantic-decision-review-required:* as blocking validation evidence for the current
materialization candidate. They do not authorize retrying with a different local UI artifact,
changing the selected resource, downgrading a governed decision to a component preview, or
bypassing /domain-rules/intake/simulation/review. Re-ground or clarify through the canonical
semantic decision flow instead.
No Keyword Routing
Do not decide domain rule, knowledge, approval, materialization, catalog relationship, or resource policy intent by labels, aliases, regexes, command words, or local fuzzy matching as the primary decision. Use governed LLM/tool resolution, Domain Catalog/Knowledge, semantic decisions, rule definitions, active evidence, declared tools, and canonical context; textual matching may only rank already-scoped candidates.
Aderence Inventory
Before adding domain-rule fields, knowledge patch operations, materialization kinds, statuses, diagnostics, timelines, quick replies, catalog edges, or publication behavior, classify:
ja-suportado-so-ux
ja-suportado-mal-nomeado-ou-mal-materializado
suportado-parcialmente
lacuna-real-de-contrato
Only real gaps justify new decision contracts. Identify which UX/behavior cannot be implemented, canonical source, impacted consumers, derived artifacts, and minimum proof.
Parameter template and values handoff
For parameter authoring inspect DomainRuleParameters, parameter catalog DTOs,
DomainRuleService, DomainRuleChangeWorkspaceService, snapshot composition,
Engine RuleParameterResolver, Core client and the Quickstart composer/sandbox.
definition.parameterTemplate stores the Engine-owned schema; only
parameters.parameterValues stores editable scalar declarations. Other parameters
may be structural metadata and must not become an inferred edit surface.
Project /definitions/{id}/parameters under RULE_DEFINITION_READER and resolved
scope. Expose type/unit/constraints/default/declared/effective/origin; omit absent
values while preserving explicit JSON null. Let Engine validate and derive condition
on creation/save; a caller-supplied condition must agree. Workspace changes preserve
structural metadata, strong If-Match and revision/evidence invalidation.
Bind each snapshot PARAMETERIZE binding to exactly one approved source by
bindingKey/ruleKey, canonical template and values. A digest of a caller-selected
schema is not sufficient without this source linkage. Preserve maker-checker and
publication/activation/rollback gates. Publication stores immutable content without
selecting a head; use the existing sanitized publication receipt and explicit
operator activation/rollout contract, including conditional bootstrap when no head
exists. Candidate versions must consider stored publications, not only the active
head. Parameter templates materialize through governed
RuleSet snapshots; generic create/publication/application adapters reject them because
they do not preserve the complete Engine outcome/required-facts contract. Retirement
of older artifacts remains available. The host sandbox and published composer must
transport values, not just condition. Preserve operational facts; parameters may
scale a fact but must not replace its canonical provider.
Run DomainRuleParametersTest, workspace/controller/service/snapshot tests, then
Core HTTP specs and an actual host A/B proof. Database/HTTP lifecycle proof uses an
exclusively allocated remote Neon branch, TLS and separate migration/control-plane/
runtime identities; synthetic sandbox facts are not operational-fact-provider proof.
Update public OpenAPI, HTTP corpus, Core models and Studio together. Source-candidate
Maven proof remains distinct from published-coordinate adoption.
Validation
Use focused local gates:
- domain rules:
mvn "-Dtest=DomainRuleControllerTest,DomainRuleServiceTest,DomainRuleMigrationConstraintTest" test
- runtime snapshots:
mvn "-Dtest=DomainRuleSnapshotControllerTest,DomainRuleSnapshotServiceTest,DomainRuleSnapshotAutoConfigurationTest" test
- shared-rule authoring handoff and LLM routing:
mvn "-Dtest=AgenticAuthoringLlmIntentResolverServiceTest,AgenticAuthoringIntentResolverServiceTest,AgenticAuthoringTurnEngineTest" test
- agentic semantic decisions and domain catalog grounding:
mvn "-Dtest=AgenticAuthoringSemanticDecisionPolicyTest,AgenticAuthoringDomainCatalogCandidateEnhancerTest,AgenticAuthoringDomainCatalogHintsTest" test
- domain knowledge and derived Project Knowledge indexing:
mvn "-Dtest=DomainKnowledgeChangeSetControllerTest,DomainKnowledgeChangeSetServiceTest,DomainKnowledgeChangeSetValidatorTest,DomainKnowledgeEntityLifecycleTest,DomainKnowledgeProjectionServiceTest,RagProjectKnowledgeDerivedIndexServiceTest" test
- catalog/federation read, policy, ingest, releases, activation, and 360 projection:
mvn "-Dtest=Domain360CatalogControllerTest,Domain360CatalogServiceTest,DomainCatalogControllerTest,DomainCatalogIngestionServiceTest,DomainCatalogPromptContextServiceTest,DomainFederationControllerTest,DomainFederationContractValidatorTest,DomainFederationRetrievalPolicyServiceTest,DomainFederationQueryServiceTest,DomainFederationIngestDryRunServiceTest,DomainFederationIngestPersistenceServiceTest,DomainFederationReleaseServiceTest" test
- Angular consumers:
npm run test:core -- --include=projects/praxis-core/src/lib/services/domain-rule.service.spec.ts --include=projects/praxis-core/src/lib/services/domain-knowledge.service.spec.ts --include=projects/praxis-core/src/lib/services/domain-catalog.service.spec.ts
For public decision/materialization changes, review docs/ai/**, docs/domain-catalog/**, quickstart smokes, Angular core domain services, Page Builder handoff, and public docs/examples.
Companion Skills
praxis-reactive-determinations for governed snapshot, metadata, host, Angular, and HTTP handoff.
Use praxis-core-domain-governance-runtime for Angular clients and cockpit projection of these decisions.
Use praxis-config-agentic-authoring-streaming when turn streams route into shared rule/domain knowledge authoring.
Use praxis-config-api-metadata-grounding when decisions depend on API metadata, Domain Catalog, Project Knowledge, or resource candidates.
Use praxis-api-quickstart-cockpit-http-validation and praxis-api-quickstart-domain-pilots for downstream proof of domain-rule/domain-knowledge materializations in the reference host.
Use praxis-http-examples-contract-surfaces and praxis-http-examples-llm-smoke when governed decision examples or read-only LLM lanes are affected.
Use praxis-metadata-discovery-capabilities when materializations project to backend resource actions, surfaces, capabilities, or option sources.
1---2name: praxis-config-domain-decisions3description: "Use when Codex must implement, audit, or consume praxis-config-starter governed semantic decisions: domain-rule intake, structural simulation, publication and materialization; Domain Knowledge change sets and evidence lifecycle; Domain Catalog or Federation grounding; decision diagnostics, approvals, timelines, and Angular runtime projections."4metadata:5 source: https://skillmd.com/skills/codexrodrigues/praxis-config-domain-decisions6---78# Praxis Config Domain Decisions910Use this skill for governed domain decisions in `praxis-config-starter`. Domain rules, domain knowledge, publications, and materializations are canonical semantic decisions; forms, tables, option sources, actions, UI rules, and runtime artifacts are derived projections.1112## Source Audit1314Inspect the owner before editing:1516- `praxis-config-starter/AGENTS.md`17- `docs/2026-04-federated-domain-catalog-rfc.md`18- `docs/domain-catalog/**`19- `docs/ai/categorical-field-semantics-v1.md`20- `docs/ai/domain-rule-timeline-v*.md`21- `src/main/java/org/praxisplatform/config/controller/DomainRuleController.java`22- `src/main/java/org/praxisplatform/config/controller/DomainKnowledgeChangeSetController.java`23- `src/main/java/org/praxisplatform/config/controller/DomainCatalogController.java`24- `src/main/java/org/praxisplatform/config/controller/DomainFederationController.java`25- `src/main/java/org/praxisplatform/config/service/DomainRuleService.java`26- `src/main/java/org/praxisplatform/config/service/DomainRuleSnapshotService.java`27- `src/main/java/org/praxisplatform/config/controller/DomainRuleSnapshotController.java`28- `src/main/java/org/praxisplatform/config/domain/DomainRuleSnapshot.java`29- `src/main/java/org/praxisplatform/config/domain/DomainRuleSnapshotHead.java`30- `src/main/java/org/praxisplatform/config/domain/DomainRuleSnapshotEvent.java`31- `src/main/java/org/praxisplatform/config/service/DomainKnowledgeChangeSetService.java`32- `src/main/java/org/praxisplatform/config/service/DomainKnowledgeChangeSetValidator.java`33- `src/main/java/org/praxisplatform/config/service/DomainFederationQueryService.java`34- `src/main/java/org/praxisplatform/config/service/DomainFederationRetrievalPolicyService.java`35- `src/main/java/org/praxisplatform/config/service/DomainFederationIngestDryRunService.java`36- `src/main/java/org/praxisplatform/config/service/DomainFederationIngestPersistenceService.java`37- `src/main/java/org/praxisplatform/config/service/DomainFederationReleaseService.java`38- `src/main/java/org/praxisplatform/config/service/RagProjectKnowledgeDerivedIndexService.java`39- `src/main/java/org/praxisplatform/config/ai/authoring/AgenticAuthoringSemanticDecisionPolicy.java`40- `src/main/java/org/praxisplatform/config/ai/authoring/AgenticAuthoringSemanticMaterializationPolicy.java`41- `src/main/java/org/praxisplatform/config/ai/authoring/AgenticAuthoringLlmIntentResolverService.java`42- `src/main/java/org/praxisplatform/config/ai/authoring/AgenticAuthoringIntentResolverService.java`43- `src/main/java/org/praxisplatform/config/ai/authoring/AgenticAuthoringTurnEngine.java`44- `src/main/java/org/praxisplatform/config/ai/authoring/AgenticAuthoringDomainCatalogCandidateEnhancer.java`45- `src/main/java/org/praxisplatform/config/ai/authoring/AgenticAuthoringDomainCatalogHints.java`46- `src/main/java/org/praxisplatform/config/domain/DomainRuleDefinition.java`47- `src/main/java/org/praxisplatform/config/domain/DomainRuleMaterialization.java`48- `src/main/java/org/praxisplatform/config/domain/DomainKnowledgeChangeSet.java`49- `src/main/resources/db/migration/V18__create_domain_knowledge_layer.sql` through `V26__add_domain_knowledge_evidence_lifecycle.sql`50- `src/main/resources/db/migration/V30__create_domain_rule_snapshot_control_plane.sql`51- `docs/domain-rules/snapshot-control-plane-v1.md`52- `praxis-ui-angular/projects/praxis-core/src/lib/services/domain-rule.service.ts`53- `praxis-ui-angular/projects/praxis-core/src/lib/services/domain-knowledge.service.ts`54- `praxis-ui-angular/projects/praxis-core/src/lib/services/domain-catalog.service.ts`55- `praxis-ui-angular/projects/praxis-core/src/lib/ai/domain-catalog-context-pack.ts`56- focused domain rule, domain knowledge, catalog, federation, timeline, and migration tests.5758## Canonical Boundary5960`/api/praxis/config/domain-rules/**` owns intake, definitions, status transitions, simulations, publications, materializations, timelines, explainability, `decisionDiagnostics`, immutable snapshot persistence, active RuleSet heads and rollback.6162`/api/praxis/config/domain-knowledge/change-sets/**` owns governed knowledge patch creation, validation, review, apply, timeline, evidence lifecycle, and derived Project Knowledge indexing.6364Domain catalog/federation publishes semantic graph context and relationships for AI grounding. It must not be reduced to labels.6566Agentic authoring is a routing surface for these decisions, not the owner of the business rule. When the LLM resolver sets `requiresGovernedAuthoring=true`, the canonical route is `changeKind=route_shared_rule_authoring` with no `visualizationDecision`; the turn must not continue as a dashboard, chart, table, form, page preview, or local component apply.6768## Layer Model6970Keep these owners and lifecycles distinct:7172- Domain Catalog releases are immutable producer snapshots. Their RAG documents are derived indexes, not the transactional source of truth.73- Domain Federation is a validated, LLM-safe read model over accepted releases. Ingestion creates a `candidate`; explicit activation makes it authoritative and supersedes the prior active release.74- Domain Knowledge is a governed, change-set-versioned semantic graph of concepts, aliases, bindings, relationships, and evidence. It does not execute business rules.75- Domain Rule definitions hold reusable decision intent, condition, parameters, evidence refs, owner, steward, and governance independently from any component.76- Materializations project an approved/published definition into target artifacts. Angular, Java validation, option sources, workflow actions, and approval policies consume those projections; they do not become the rule owner.7778## Domain Rule Workflow79801. Resolve tenant, environment, `resourceKey`, `ruleType`, context, evidence, and semantic owner through governed metadata/catalog/tooling before intake.812. `POST /domain-rules/intake` persists a `draft` definition and returns grounding plus `decisionDiagnostics`. Do not treat the prompt or assistant text copied into the definition as durable Domain Knowledge evidence.823. `POST /domain-rules/simulations` may use a persisted definition or an ad hoc request. The current simulation detects approved/active overlapping coverage, predicts target materializations, derives required approvals and publication readiness; it does **not** execute the rule condition against business records or prove business outcomes.834. Review `existingCoverage`, `predictedMaterializations`, `requiredApprovals`, warnings, explainability, and timeline evidence before publication. Existing approved/active coverage and declared approvals block publication.84 To approve a governed definition, the authenticated reviewer needs the official85 `RULE_DEFINITION_APPROVER` role **and** an `actorRef` listed in86 `governance.requiredApprovals` or `governance.authorizedApprovers`; the87 reviewer must differ from the server-authenticated author. Preserve the88 author/reviewer/publisher separation. Verify the persisted definition89 approval against `DomainRuleDefinitionFingerprint.sha256` and the actual90 derived artifact through their canonical owners; do not normalize a hash's91 letter case or change production to satisfy a legacy fixture. Definition92 approval and RuleSet snapshot/composition approvals are distinct gates.935. `POST /domain-rules/publications` requires a persisted definition. Only `approved` or `active` satisfies the publication approval gate; `draft` and `proposed` return `approval_required`, while terminal/inactive states are blocked. Governed definitions must be created as `draft` or `proposed` and pass explicit authorized transitions before publication. Do not relax this lifecycle to repair an outdated smoke fixture.946. Publish or create target materializations and preserve stable key, target identity, `sourceHash`, validation result, status, and materialization outcome diagnostics. A stable-key collision with another definition or changed derived source hash must fail instead of silently overwriting a projection.9596The current auto-derived publication targets are:9798- `selection_eligibility` -> `option_source/resource-option-source`99- validation-family rules -> `backend_validation/resource-validation`100- `workflow_action_policy` -> `workflow_action/resource-workflow-action`101- `approval_policy` -> `approval_policy/resource-action-approval`102103Other predicted targets, including form guidance, may require an explicit materialization. Never infer that a predicted target was persisted; inspect `materializations` and `publicationDiagnostics.materializationOutcomes`.104105## Preserve Materialization Application History106107For persistence/lifecycle changes, read Config's108`docs/domain-rules/materialization-application-history.md`, migration V63,109`DomainRuleMaterialization`, and `DomainRuleApplicationHistoryPostgresTest`.110Use the existing materialization identity and V55 unique applied head; do not111create another head store to compensate for an incomplete reader.112113- Preserve `everApplied=true` through every apply/revert/supersede path. Legacy114 null is inconclusive, never false. New/imported superseded rows cannot claim115 false; inconclusive legacy rows retain null. New drafts start false; the migration uses116 exact linked application events or applied status/timestamp as positive proof.117- Keep both publication and explicit transition in the Config transaction.118 Do not delete/reidentify historical materializations, mutate applied events,119 or truncate history to repair a failed publication. Preserve orphan events and120 migration guards in retention and restore procedures.121- Leave a new entity's `rowVersion` null for Spring Data persist, even with an122 assigned UUID. JPA increments once; V63 also advances SQL-only updates without123 double-incrementing ORM writes. SQL compare-and-set still needs an expected124 version predicate and row-count check. HTTP 409 means reload and reassess,125 not blind retry, and does not add client If-Match to materialization commands.126- Run the focused PostgreSQL history test on canonical migrations, plus127 `DomainRuleServiceTest` and `DomainRuleConcurrencyResponseTest`. Hibernate128 create-drop does not prove upgrade/backfill or database guards. Prove candidate129 consumption in Quickstart without claiming a local SNAPSHOT is a release.130- For operational admission, use Config's public Java131 `OperationalPolicyService.resolveOperationalPolicy(target, resolvedPrincipal)`;132 never the UX materialization list. Inspect `OperationalPolicyTarget`,133 `OperationalPolicyResolution`, the exact repository snapshot query, and134 `docs/domain-rules/operational-policy-resolution.md` in Config before changing it.135- Preserve all four resolution states. NEVER_APPLIED permits continuation only136 under a provider's explicit ALLOW_IF_NEVER_APPLIED policy and mandatory lookup.137 Withdrawal, unknown history, malformed/mismatched evidence and unavailability138 block. A verified ALLOW bypasses only this gate, never authorization or business139 invariants. Existence of the target remains the host registry's responsibility.140- New creation/publication/application of approval, workflow and backend-validation141 policies must declare BLOCK or ALLOW in the existing definition parameters slot142 (approvalPolicy, availabilityPolicy or validationPolicy). Derive and verify the143 payload/hash before replacing a head. Keep ALLOW restrictive: no condition,144 requirements/groups/blockedWhen, hidden nested action requirements or unsupported145 execution parameters, even if false/zero/empty. Publication approvals remain146 distinct and mandatory under their governance. Preserve exact persisted numeric147 semantics in these producers and the reader; a canonical hash does not repair a148 payload narrowed to double.149- Missing `effect` in operational policy slots is rejected fail-closed (`400 Bad Request` / `MISSING_OPERATIONAL_POLICY_EFFECT`); never infer an implicit `BLOCK` or permissive fallback. Unverifiable hashes require a governed replacement definition with distinct identity at the same target; never rewrite history. `/definitions/{id}/facts` (`praxis.domain-rule-fact-catalog.v1`) supports `number-array`/`array<number>` and returns `facts: []` for non-fact UI rule families (`visual_guidance`, `form_rule`, `color_palette`) or unhydrated drafts, while governed condition authoring requires a complete `factCatalog`.150- Keep publish/status transitions/promotion under the Config PostgreSQL transaction151 scope mutex, acquired before loading lifecycle inputs. Require READ COMMITTED and152 a clean Config persistence context on entry; reject external pending entity153 changes before autoflush. Refresh clean preloaded inputs under the lock and154 recheck scope. Promotion's inserted version is flushed under the already-held155 mutex before its nested transition. Do not implement H2/no-op locking in production.156- The reader captures one exact SQL snapshot with orphan history and binds ordered157 identity/revision/status/hash evidence in its fingerprint. Never-applied drafts158 and observedAt do not change operational identity. Bounds (4,096 relevant rows,159 oversized JSON evidence) fail closed, not truncated into permission. Digests are160 not signatures against coherent administrative SQL changes; services remain the161 supported writer. Do not promise instantaneous Config-to-domain revocation.162- Add `DomainRuleLifecycleConcurrencyPostgresTest`, `OperationalPolicyContractTest`,163 `OperationalPolicyServiceTest` and `DomainRuleChangeWorkspaceServiceTest` to the164 focal history/service tests when changing this seam. Prove the isolated candidate165 in Quickstart with both `praxis.palette.proof` and `praxis.operational.policy.proof`166 enabled: Config PostgreSQL, authenticated publication/withdrawal/replacement,167 Java resolution and exact nested JAR. A test fixture is not proof of migrations,168 and this SDK alone does not make a bulk provider READY.169170## Runtime Snapshot Control Plane171172Treat a runtime snapshot as a governed aggregate, not as an opaque `DomainRuleMaterialization` payload. The public runtime-neutral snapshot record and compiler belong to `praxis-rules-engine`; Config Starter owns the append-only JPA store, publication transaction, active head, event history, HTTP concurrency and rollback.173174- Require source provenance, approved definitions, and at least two distinct approvers before snapshot publication.175- Validate Java bindings with a planning-only exact-coordinate registry. Config Starter must not instantiate or execute host Java implementations.176- Publication persists immutable content and a `PUBLISHED` event only. Its response is `DomainRuleSnapshotStoredResponse`; the host-neutral composition receipt in `praxis-config-contracts` carries only snapshot key, RuleSet key/version and content hash. Neither receipt establishes selection or readiness.177- Read the actual head before conditional lifecycle operations. Use strong `If-Match` for an existing head or explicit `If-None-Match: *` for verified absence. Publication never manufactures an initial head. Initial activation requires a REQUIRED rollout policy, positive quorum and real host probes; do not substitute OBSERVE_ONLY, allow-all or a synthetic head.178- Keep `snapshotContentHash` separate from `headEtag`: immutable content uses the former; explicit activation/rollback rotates the latter and advances activation revision, including rollback to previously seen content. New `PUBLISHED` events have no head ETag or activation revision, even when a head already exists. Preserve historical event bytes without granting candidate execution authority.179- Serialize publication, rollout lifecycle, policy and selection changes through the canonical transactional tenant/environment/RuleSet lock, including first creation. Reject dirty external Config persistence contexts before autoflush and refresh clean lifecycle inputs after acquiring the lock. Use the canonical directed refresh with `PESSIMISTIC_WRITE` before evaluating CAS; locking a stale cached version through a repository query first can raise an optimistic-lock failure before the intended precondition check. Never clear the caller's persistence context silently. Observational probes use the directed rollout row lock; they do not select authority or require an additional scope lock.180- Separate historical integrity from executable admission. Verify envelope, hash, provenance, composition and approvals before reporting compatibility. Intact older tuples may be read as history and classified `RUNTIME_INCOMPATIBLE`; corruption is `INVALID`. Intact pre-manifest history remains `REPUBLICATION_REQUIRED`; corrupted pre-manifest history is `INVALID`, and neither is returned through the immutable detail route or admitted as an executable candidate. Execution-facing `findActive`/head reads, activation and rollback require the current compiler and catalog; historical detail reads do not.181- Every non-READY version has `UNAVAILABLE` action, even if historically selected. READY without a head offers `CREATE_ROLLOUT`; it does not authorize direct activation. Rollout expected snapshot/head-ETag fields represent absence only as a complete null pair.182- Immutable reads use content validators. Head/status is an operational projection that may change when runtime/catalog changes without rotating the head: return `no-store` and re-evaluate rather than answering 304 solely from head ETag.183- Rollback selects a valid compatible prior publication under authorization/CAS and preserves the canonical emergency policy without imposing a new rollout quorum. Do not silently recompile or rewrite a historical 1.4 snapshot to make it 1.5-compatible.184- Keep evaluation out of Config Starter. The consuming host compiles with its real executable registry before reporting candidate admission; only explicit selection can replace its active plan.185186Inspect `DomainRuleSnapshotVerifier`, `DomainRuleSnapshotScopeLock`, `DomainRuleRolloutService`, `DomainRuleEntityRefresh`, `snapshot-control-plane-v1.md`, `staged-activation-readiness-v1.md` and the corresponding migration before extending this boundary. Verify the published coordinates contain this separation; source-only G2 changes are not an adopted release.187188For control-plane changes, prove publication with unchanged/absent head, initial required-quorum activation, stale conditions, concurrent first publications/activations, dirty and preloaded JPA contexts, approval/provenance failure, historical integrity versus compatibility, same-line rollback/anti-ABA, transaction rollback and cross-scope rejection. Database-dependent proof uses exclusively assigned remote Neon owner/runtime identities; unit mocks do not prove locking or transaction rollback.189190Use only canonical status endpoints. Definition transitions allow review paths including `deprecated -> active`, but `rejected` and `retired` are terminal. Materializations may recover from `failed`, `superseded`, or `reverted` only through `draft` or `pending_review`; they cannot jump directly back to `applied`.191192## Agentic Handoff193194- Shared-rule turns must be resolved semantically by `AgenticAuthoringLlmIntentResolverService` or governed evidence, then converted by `AgenticAuthoringIntentResolverService` into a route that carries `shared-rule-authoring-required`.195- `AgenticAuthoringTurnEngine` should surface the handoff and diagnostics, not fabricate a component preview, dry-run patch, page plan, or applyable artifact. `canApply` must remain false until a governed decision/materialization contract exists.196- A consultative catalog question such as "which governed data can I use?" remains read-only and uses `artifactKind=api_catalog` plus `answer_api_catalog_question`; it must not be escalated to shared-rule authoring unless the user actually asks to define or change a reusable business decision.197- A local UI request such as formatting, masks, labels, component layout, columns, filters, or badges is not a domain decision unless the semantic intent includes reusable policy, eligibility, approval, compliance, privacy, access, validation, or enforcement.198- When a route is blocked by `shared-rule-authoring-required`, the correct next implementation step is to connect the assistant handoff to `/domain-rules/intake`, simulation, review, and publication. Do not bypass the gap with keyword routing or local preview heuristics.199200## Domain Knowledge Workflow201202- LLM-authored change sets must begin as `proposed`, include stable operation ids, reasons, evidence refs, confidence in `[0,1]`, and a target within the request tenant/environment. Raw prompts, transcripts, or chat memory are not canonical evidence.203- Creation is idempotent only when the same change-set key has the same patch hash and author identity. Reusing a key with different semantics must fail.204- Validation, review, and apply are separate operations. Approval requires a valid stored validation result and reviewer; apply requires `approved`, rechecks validity, and is idempotent after `applied`.205- The validator recognizes concept, alias, binding, relationship, visibility, summary, add-evidence, and revert-evidence operation types, but the current apply service executes only `add_evidence` and `revert_evidence`. Treat all other operations as `suportado-parcialmente`; do not advertise them as operational until an applier and focused proof exist.206- Applying evidence updates the Project Knowledge derived index. Revert deactivates the evidence; an active replacement marks the previous evidence `superseded`, otherwise it becomes `reverted`.207- Timelines and responses expose safe summaries. Do not rehydrate raw patch payloads, prompts, private evidence, or chat transcripts into UI lifecycle events.208- Domain-rule timelines are safe persisted observability projections, not a second source of business truth. Add or interpret timeline events only from persisted domain-rule sources or an explicit command/event ledger; do not backfill missing events from DTO timestamps, simulation ids, AI turn logs, frontend handoff state, quickstart smoke output, prompts, assistant messages, conditions, parameters, or materialized payloads. A blocked/rejected/ad hoc operation without a durable event source is a governance observability gap, not permission to invent a timeline fact.209210## Grounding Safety211212- Domain Catalog v0.2 and Federation provide semantic context, ownership, vocabulary, evidence, relationships, visibility, and retrieval policy. They do not define or execute final business rules.213- Apply `aiUsage.visibility`, contract visibility, confidence, tenant/environment scope, release identity, and retrieval policy before returning LLM context. Never bypass `deny` or `deny_for_llm` for ordinary authoring.214- Prefer an active persisted federation release; use catalog projection fallback only as declared by the query response. Preserve `sourceMode`, release keys, policy report, evidence refs, and redaction decisions.215- The existing `policy_reference` option-source prediction contains residual text matching after semantic scope resolution. Do not extend it or use it as primary intent routing; require an explicit canonical `ruleType`/target contract for new behavior.216217## Reactive Determination Handoff218219When a governed rule materializes as a Reactive Determination, keep Config as220the decision/snapshot owner and publish a typed221`DomainRuleReactiveDeterminationSpec` with stable definition identity, scope,222form modes, trigger, bindings, provenance, and target coverage. Metadata Starter223compiles the public operation projection; Angular executes only that projection.224Do not emit legacy Form Effect payloads or make the form infer determination225selection from field names. Pair with `praxis-reactive-determinations` for the226complete snapshot-to-runtime proof.227228## Decision Rules229230- If a request is about a shared business rule, validation, eligibility, compliance, approval, or policy over a resolved resource, route to domain decisions before component preview/apply.231- UI, option sources, backend validation, workflow actions, and approval policies should be materializations of the governed decision when possible.232- Treat `requiresGovernedAuthoring=true`, `route_shared_rule_authoring`, and `shared-rule-authoring-required` as blocking signals for ordinary UI materialization. They are not warnings that can be ignored by the preview/apply pipeline.233- Preserve `decisionDiagnostics`, `explainability`, publication diagnostics, materialization outcomes, timeline events, statuses, source hashes, and canonical owner fields.234- Do not report `simulation.result=pass` as a successful evaluation of business data; it currently describes authoring/coverage diagnostics.235- Status transitions are directional; use the canonical transition endpoints and never mutate status fields or projection records directly.236- Domain Knowledge apply is separate from approval and must validate scope, validation result, lifecycle, and evidence state.237- Project Knowledge used in authoring is derived from governed active evidence, not raw prompts or stale chat history.238- Agentic semantic decision/materialization policies are the boundary that prevents prompts, context hints, or weak candidates from becoming executable domain/materialization decisions. Preserve tests that distinguish consultative API/domain catalog answers, governed exploration, resource-choice clarification, explicit materialization, and dashboard/chart/table classification before allowing preview/apply.239- Treat semantic materialization failures such as `semantic-preview-primary-component-required`,240 `semantic-preview-chart-required`, `semantic-preview-resource-binding-mismatch`,241 `semantic-preview-axis-schema-verification-required`, or242 `semantic-decision-review-required:*` as blocking validation evidence for the current243 materialization candidate. They do not authorize retrying with a different local UI artifact,244 changing the selected resource, downgrading a governed decision to a component preview, or245 bypassing `/domain-rules/intake`/simulation/review. Re-ground or clarify through the canonical246 semantic decision flow instead.247248## No Keyword Routing249250Do not decide domain rule, knowledge, approval, materialization, catalog relationship, or resource policy intent by labels, aliases, regexes, command words, or local fuzzy matching as the primary decision. Use governed LLM/tool resolution, Domain Catalog/Knowledge, semantic decisions, rule definitions, active evidence, declared tools, and canonical context; textual matching may only rank already-scoped candidates.251252## Aderence Inventory253254Before adding domain-rule fields, knowledge patch operations, materialization kinds, statuses, diagnostics, timelines, quick replies, catalog edges, or publication behavior, classify:255256- `ja-suportado-so-ux`257- `ja-suportado-mal-nomeado-ou-mal-materializado`258- `suportado-parcialmente`259- `lacuna-real-de-contrato`260261Only real gaps justify new decision contracts. Identify which UX/behavior cannot be implemented, canonical source, impacted consumers, derived artifacts, and minimum proof.262263## Parameter template and values handoff264265For parameter authoring inspect `DomainRuleParameters`, parameter catalog DTOs,266`DomainRuleService`, `DomainRuleChangeWorkspaceService`, snapshot composition,267Engine `RuleParameterResolver`, Core client and the Quickstart composer/sandbox.268`definition.parameterTemplate` stores the Engine-owned schema; only269`parameters.parameterValues` stores editable scalar declarations. Other parameters270may be structural metadata and must not become an inferred edit surface.271272Project `/definitions/{id}/parameters` under RULE_DEFINITION_READER and resolved273scope. Expose type/unit/constraints/default/declared/effective/origin; omit absent274values while preserving explicit JSON null. Let Engine validate and derive condition275on creation/save; a caller-supplied condition must agree. Workspace changes preserve276structural metadata, strong If-Match and revision/evidence invalidation.277278Bind each snapshot PARAMETERIZE binding to exactly one approved source by279bindingKey/ruleKey, canonical template and values. A digest of a caller-selected280schema is not sufficient without this source linkage. Preserve maker-checker and281publication/activation/rollback gates. Publication stores immutable content without282selecting a head; use the existing sanitized publication receipt and explicit283operator activation/rollout contract, including conditional bootstrap when no head284exists. Candidate versions must consider stored publications, not only the active285head. Parameter templates materialize through governed286RuleSet snapshots; generic create/publication/application adapters reject them because287they do not preserve the complete Engine outcome/required-facts contract. Retirement288of older artifacts remains available. The host sandbox and published composer must289transport values, not just condition. Preserve operational facts; parameters may290scale a fact but must not replace its canonical provider.291292Run `DomainRuleParametersTest`, workspace/controller/service/snapshot tests, then293Core HTTP specs and an actual host A/B proof. Database/HTTP lifecycle proof uses an294exclusively allocated remote Neon branch, TLS and separate migration/control-plane/295runtime identities; synthetic sandbox facts are not operational-fact-provider proof.296Update public OpenAPI, HTTP corpus, Core models and Studio together. Source-candidate297Maven proof remains distinct from published-coordinate adoption.298299## Validation300301Use focused local gates:302303- domain rules: `mvn "-Dtest=DomainRuleControllerTest,DomainRuleServiceTest,DomainRuleMigrationConstraintTest" test`304- runtime snapshots: `mvn "-Dtest=DomainRuleSnapshotControllerTest,DomainRuleSnapshotServiceTest,DomainRuleSnapshotAutoConfigurationTest" test`305- shared-rule authoring handoff and LLM routing:306 `mvn "-Dtest=AgenticAuthoringLlmIntentResolverServiceTest,AgenticAuthoringIntentResolverServiceTest,AgenticAuthoringTurnEngineTest" test`307- agentic semantic decisions and domain catalog grounding:308 `mvn "-Dtest=AgenticAuthoringSemanticDecisionPolicyTest,AgenticAuthoringDomainCatalogCandidateEnhancerTest,AgenticAuthoringDomainCatalogHintsTest" test`309- domain knowledge and derived Project Knowledge indexing:310 `mvn "-Dtest=DomainKnowledgeChangeSetControllerTest,DomainKnowledgeChangeSetServiceTest,DomainKnowledgeChangeSetValidatorTest,DomainKnowledgeEntityLifecycleTest,DomainKnowledgeProjectionServiceTest,RagProjectKnowledgeDerivedIndexServiceTest" test`311- catalog/federation read, policy, ingest, releases, activation, and 360 projection:312 `mvn "-Dtest=Domain360CatalogControllerTest,Domain360CatalogServiceTest,DomainCatalogControllerTest,DomainCatalogIngestionServiceTest,DomainCatalogPromptContextServiceTest,DomainFederationControllerTest,DomainFederationContractValidatorTest,DomainFederationRetrievalPolicyServiceTest,DomainFederationQueryServiceTest,DomainFederationIngestDryRunServiceTest,DomainFederationIngestPersistenceServiceTest,DomainFederationReleaseServiceTest" test`313- Angular consumers: `npm run test:core -- --include=projects/praxis-core/src/lib/services/domain-rule.service.spec.ts --include=projects/praxis-core/src/lib/services/domain-knowledge.service.spec.ts --include=projects/praxis-core/src/lib/services/domain-catalog.service.spec.ts`314315For public decision/materialization changes, review `docs/ai/**`, `docs/domain-catalog/**`, quickstart smokes, Angular core domain services, Page Builder handoff, and public docs/examples.316317## Companion Skills318319- `praxis-reactive-determinations` for governed snapshot, metadata, host, Angular, and HTTP handoff.320321- Use `praxis-core-domain-governance-runtime` for Angular clients and cockpit projection of these decisions.322- Use `praxis-config-agentic-authoring-streaming` when turn streams route into shared rule/domain knowledge authoring.323- Use `praxis-config-api-metadata-grounding` when decisions depend on API metadata, Domain Catalog, Project Knowledge, or resource candidates.324- Use `praxis-api-quickstart-cockpit-http-validation` and `praxis-api-quickstart-domain-pilots` for downstream proof of domain-rule/domain-knowledge materializations in the reference host.325- Use `praxis-http-examples-contract-surfaces` and `praxis-http-examples-llm-smoke` when governed decision examples or read-only LLM lanes are affected.326- Use `praxis-metadata-discovery-capabilities` when materializations project to backend resource actions, surfaces, capabilities, or option sources.