feat(ka): add governed decision capability batch

Author: kherrera6219

CHANGELOG.md

@@ -26,6 +26,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 ### Added
+- **Phase 18 CP18-C governed-decision Batch 03**: restored eight deterministic,
+  read-only capabilities for context selection, intent clarification, knowledge
+  promotion admission, simulation cost/budget admission, cross-instance
+  agreement, reasoning anomaly measurement, and explainability coverage. The
+  authority advances to 148 implementations/65 gaps, the KA suite passes 517
+  tests, and all duplicate, collision, unclassified, and honesty gates pass.
 - **Phase 18 CP18-C restored-analysis Batch 02**: restored eight distinct
   original-design capabilities under their collision-free canonical IDs:
   Pareto optimization, norm emergence detection, cross-modal evidence

HANDOFF.md

@@ -17,7 +17,7 @@
 | Last reviewed | 2026-07-25 |
 | Next-review trigger | Every checkpoint, handoff, blocker, or release-decision change |
 | Requirements and evidence | Active plan, open-work ledger, and `reports/production-readiness/2026/` |
-| Active plan | `PRODUCTION_COMPLETION_PLAN_2026.md` v1.27.0 |
+| Active plan | `PRODUCTION_COMPLETION_PLAN_2026.md` v1.28.0 |
 | Completed phase | Object-store Replacement Control; SeaweedFS selected for rebuilt installed qualification |
 | Current phase | Phase 18 Knowledge Algorithm production completion; CP18-C active |
 | Release verdict | Production/public release: **NO-GO** |
@@ -83,6 +83,12 @@ implementation progress advances to 140 real sources and 73 gaps. The full KA
 suite passes 493 tests, and duplicate collisions, unresolved duplicates,
 unclassified surfaces, and static honesty flags remain zero.
 
+CP18-C Batch 03 passed for eight governed decision-support KAs. They make
+read-only context, intent, promotion, simulation-budget, consensus, anomaly,
+and explainability-coverage decisions without starting work or claiming truth.
+The authority is now 148 implementations/65 gaps and the KA suite is 517
+passed; no duplicate, collision, unclassified, or honesty finding remains.
+
 Baseline evidence:
 `reports/production-readiness/2026/phase-18/baseline-and-plan.md`.
 
@@ -701,9 +707,9 @@ replacement. See
 ## Exact next action
 
 1. Continue Phase 18 CP18-C against the approved 213-capability manifest:
-   Batches 01-02 qualified 11 existing implementations and restored eight
+   Batches 01-03 qualified 11 existing implementations and restored 16
    missing capabilities; qualify the remaining existing implementations and
-   build the 73 explicit gaps in semantic batches
+   build the 65 explicit gaps in semantic batches
    with strict schemas, limits, failure behavior, and authoritative
    effect/service integration.
 2. Preserve canonical IDs and behavior until parity proof permits each

PRODUCTION_COMPLETION_PLAN_2026.md

@@ -4,7 +4,7 @@
 
 | Field | Value |
 |---|---|
-| Document version | v1.27.0 |
+| Document version | v1.28.0 |
 | Plan date | 2026-07-12 |
 | Status | Active production completion program |
 | Product target | Local-first Windows 11 x64 governed LLM middleware with a desktop control, administration, audit, and validation application |
@@ -258,6 +258,15 @@ or static honesty flags. The full KA suite passes 493 tests. The authority gates
 now enforce monotonic implementation progress from the CP18-A/CP18-B baselines
 instead of freezing their old implementation/gap counts.
 
+CP18-C Batch 03 passed on 2026-07-25 for eight governed decision-support
+capabilities covering context selection, intent clarification, knowledge
+promotion admission, simulation cost/budget admission, cross-instance
+agreement, reasoning anomaly measurement, and explainability coverage. All are
+bounded, deterministic, read-only, individually tested, and explicit about
+measurement/inference limitations. The authority advances to 148
+implementations and 65 gaps; the full KA suite passes 517 tests and all
+no-duplicate, collision, honesty, and classification gates remain clean.
+
 ## 1. Purpose
 
 This plan defines the complete program required to finish DataLogicEngine as a
@@ -4008,17 +4017,17 @@ artifact rather than against a known-incomplete subsystem.
   record.
 
 **Checkpoint status 2026-07-25:** CP18-A and CP18-B passed. CP18-C Batches 01
-and 02 also passed: 11 existing implementations were made honest and eight
+through 03 also passed: 11 existing implementations were made honest and 16
 preserved capabilities were restored as distinct production sources. The
-authority now reports 140 implementations and 73 gaps with 493 KA tests passing
+authority now reports 148 implementations and 65 gaps with 517 KA tests passing
 and no duplicate, unclassified, or static-honesty finding. The approved
 capability authority is
 `reports/production-readiness/2026/phase-18/ka-capability-crosswalk.json`.
 `scripts/verify_ka_capability_inventory.py` and
 `scripts/verify_ka_runtime_authority.py` enforce the deduplicated identity and
 single-runtime boundaries. Batch evidence is under
 `reports/production-readiness/2026/phase-18/`, including
-`cp18-c-batch-02-restored-analysis.json`.
+`cp18-c-batch-03-governed-decisions.json`.
 CP18-C is active; CP18-C through CP18-H remain open, and the signed rebuild
 remains blocked.
 
@@ -4433,8 +4442,8 @@ exit gate.
 ## 33. Immediate next action
 
 Continue Phase 18 CP18-C against the approved 213-capability manifest. Batches
-01-02 have qualified 11 existing implementations and restored eight gaps;
-qualify the remaining existing implementations and build the 73 explicit gaps
+01-03 have qualified 11 existing implementations and restored 16 gaps; qualify
+the remaining existing implementations and build the 65 explicit gaps
 in validated batches. Replace every placeholder, metadata-only facade, mock/simulated
 operation, weak or unrecorded random default, and false success with bounded
 typed production behavior or an honest prerequisite failure through an

README.md

@@ -67,7 +67,9 @@ administration, audit, observability, and validation application.
 > 493-test KA suite passes, implementation progress is 140/213 with 73 gaps,
 > and the no-duplicate authority remains clean. CP18-C is active for the
 > remaining implementation
-> completion. Phase 18 will finish production implementations and application
+> completion. Batch 03 adds eight governed decision-support KAs, advancing the
+> verified authority to 148 implementations/65 gaps and 517 passing KA tests.
+> Phase 18 will finish production implementations and application
 > wiring, and require one named functional test per canonical KA before rebuild.
 > The completed checkpoint passes 2,192 backend tests with 18 skips, all 422
 > frontend tests, frontend lint/typecheck/production build, the CI Ruff rules,
@@ -154,9 +156,9 @@ Current production-completion focus:
   Python/TypeScript SDK catalogs/clients, and compatibility adapters; 132
   implementation sources have unique canonical owners, the 81 gaps are explicit,
   and duplicate canonical collisions are zero
-- Phase 18 CP18-C Batches 01-02 passed: 11 existing implementations qualified,
-  eight distinct missing capabilities restored, 140 implementations/73 gaps,
-  493 KA tests passing, and zero duplicate or static-honesty findings; CP18-C
+- Phase 18 CP18-C Batches 01-03 passed: 11 existing implementations qualified,
+  16 distinct missing capabilities restored, 148 implementations/65 gaps,
+  517 KA tests passing, and zero duplicate or static-honesty findings; CP18-C
   remains active and the release-candidate rebuild remains paused through CP18-G
 - Production behavior, dynamic application call path, and one individually
   named functional test for every canonical KA

TODO.md

@@ -17,7 +17,7 @@
 | Last reviewed | 2026-07-25 |
 | Next-review trigger | Phase checkpoint, blocker disposition, or release-decision change |
 | Requirements and evidence | Active plan and `reports/production-readiness/2026/` |
-| Active plan | `PRODUCTION_COMPLETION_PLAN_2026.md` v1.27.0 |
+| Active plan | `PRODUCTION_COMPLETION_PLAN_2026.md` v1.28.0 |
 | Completed phase | Object-store Replacement Control; SeaweedFS selected for rebuilt installed qualification |
 | Current phase | Phase 18 Knowledge Algorithm production completion; CP18-C active |
 | Release decision | Production/public release: **NO-GO** |
@@ -66,7 +66,11 @@ catalog-only.
         and individually named semantic tests. The authority advances to 140
         implementations and 73 gaps, and the full KA suite passes 493 tests
         with zero duplicate, collision, unclassified, or static-honesty finding.
-  - [ ] Qualify the remaining existing implementations, build the 73 remaining
+  - [x] Batch 03 restored eight governed decision-support capabilities with
+        strict schemas, read-only decisions, explicit limitations, and named
+        tests. The authority advances to 148 implementations and 65 gaps; 517
+        KA tests pass with all no-duplicate and honesty gates clean.
+  - [ ] Qualify the remaining existing implementations, build the 65 remaining
         implementation gaps, and connect effect proposals to authoritative
         service application/receipt paths.
 - [ ] **CP18-D — dynamic integration:** give every canonical KA a real selector
@@ -740,7 +744,7 @@ Details: `reports/production-readiness/2026/phase-15/deferred-gates.md`.
 | 15 | System qualification and release candidate | **Release-candidate engineering checkpoint complete 2026-07-14; installed/signed exit gates retained** |
 | 16 | Production documentation replacement and professional review dossier | **CP16-F replacement closure complete 2026-07-15; CP16-G exact-artifact binding and signed/manual/external exits retained** |
 | 17 | Documentation consolidation and release lock | **CP17-A through CP17-D complete 2026-07-15; CP17-E retained for clean signed installed walkthrough** |
-| 18 | Knowledge Algorithm production completion and dynamic integration | **Active; CP18-A/CP18-B and CP18-C Batches 01-02 passed 2026-07-25, CP18-C in progress at 140 implementations/73 gaps** |
+| 18 | Knowledge Algorithm production completion and dynamic integration | **Active; CP18-A/CP18-B and CP18-C Batches 01-03 passed 2026-07-25, CP18-C in progress at 148 implementations/65 gaps** |
 | 19 | Production launch and maintenance | Blocked by prior phases |
 
 ## Release blockers retained across phases
@@ -759,8 +763,8 @@ Details: `reports/production-readiness/2026/phase-15/deferred-gates.md`.
 ## Exact next action
 
 Continue Phase 18 CP18-C against the approved 213-capability manifest. Batches
-01-02 qualified 11 existing implementations and restored eight gaps; qualify
-the remaining existing implementations and build the 73 explicit gaps without
+01-03 qualified 11 existing implementations and restored 16 gaps; qualify
+the remaining existing implementations and build the 65 explicit gaps without
 duplicate identities, private runtimes, placeholders, false effects, or
 capability loss. Every batch must add strict contracts, limits, failure
 semantics, authoritative service integration where applicable, and focused

backend/knowledge_algorithms/ka_1072_context_window_optimizer.py

@@ -0,0 +1,131 @@
+"""KA-1072: deterministic context selection under a declared token budget."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+from core.knowledge_algorithm.ka_base import KnowledgeAlgorithm
+
+
+class ContextElement(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    element_id: str = Field(min_length=1, max_length=200)
+    token_count: int = Field(ge=1, le=200_000)
+    relevance: float = Field(ge=0, le=1)
+    priority: float = Field(default=1, ge=0, le=10)
+    required: bool = False
+    content_ref: str | None = Field(default=None, max_length=2_000)
+
+
+class KA1072Input(BaseModel):
+    model_config = ConfigDict(
+        extra="forbid",
+        json_schema_extra={
+            "examples": [
+                {
+                    "context_elements": [
+                        {
+                            "element_id": "policy",
+                            "token_count": 200,
+                            "relevance": 1,
+                            "required": True,
+                        },
+                        {
+                            "element_id": "history",
+                            "token_count": 500,
+                            "relevance": 0.7,
+                        },
+                    ],
+                    "token_budget": 600,
+                }
+            ]
+        },
+    )
+
+    context_elements: list[ContextElement] = Field(
+        min_length=1,
+        max_length=2_000,
+    )
+    token_budget: int = Field(ge=1, le=2_000_000)
+
+    @model_validator(mode="after")
+    def validate_ids(self) -> KA1072Input:
+        ids = [item.element_id for item in self.context_elements]
+        if len(ids) != len(set(ids)):
+            raise ValueError("context element IDs must be unique")
+        return self
+
+
+class KA1072ContextWindowOptimizer(KnowledgeAlgorithm):
+    """Select required then highest utility-density context elements."""
+
+    input_schema = KA1072Input
+
+    def __init__(self, context: dict[str, Any]):
+        super().__init__(context, None, None, None)
+        self.ka_id = "KA-1072"
+
+    def _run_logic(self, input_data: KA1072Input) -> dict[str, Any]:
+        required = sorted(
+            (item for item in input_data.context_elements if item.required),
+            key=lambda item: item.element_id,
+        )
+        required_tokens = sum(item.token_count for item in required)
+        if required_tokens > input_data.token_budget:
+            return {
+                "success": False,
+                "status": "required_context_exceeds_budget",
+                "required_tokens": required_tokens,
+                "token_budget": input_data.token_budget,
+                "required_element_ids": [item.element_id for item in required],
+            }
+        optional = sorted(
+            (item for item in input_data.context_elements if not item.required),
+            key=lambda item: (
+                -((item.relevance * item.priority) / item.token_count),
+                -item.relevance,
+                item.token_count,
+                item.element_id,
+            ),
+        )
+        selected = list(required)
+        remaining = input_data.token_budget - required_tokens
+        excluded: list[dict[str, Any]] = []
+        for item in optional:
+            if item.token_count <= remaining:
+                selected.append(item)
+                remaining -= item.token_count
+            else:
+                excluded.append(
+                    {
+                        "element_id": item.element_id,
+                        "reason": "token_budget",
+                    }
+                )
+        selected_ids = {item.element_id for item in selected}
+        ordered = [
+            item.element_id
+            for item in input_data.context_elements
+            if item.element_id in selected_ids
+        ]
+        return {
+            "success": True,
+            "status": "context_selected",
+            "selected_element_ids": ordered,
+            "selected_token_count": (input_data.token_budget - remaining),
+            "remaining_tokens": remaining,
+            "excluded": excluded,
+            "selection_method": "required_then_utility_density",
+            "deterministic": True,
+            "limitations": (
+                "Utility density is a bounded deterministic heuristic, not a "
+                "proof of globally optimal semantic context."
+            ),
+        }
+
+
+def run(context: dict[str, Any]) -> dict[str, Any]:
+    return KA1072ContextWindowOptimizer(context).run(context)