docs: CEG corrected docs pack — AGENT_BOOTSTRAP, INVARIANTS, EXECUTION_FLOWS + 7 more#96
docs: CEG corrected docs pack — AGENT_BOOTSTRAP, INVARIANTS, EXECUTION_FLOWS + 7 more#96cryptoxdog wants to merge 10 commits into
Conversation
|
❌ PR Too Large 📋 Best Practices for Large Changes
🚫 This PR is blocked from merging until size limits are met. |
📝 WalkthroughWalkthroughThis PR introduces a comprehensive AI agent governance and onboarding framework by adding 10 new documentation files that establish architectural contracts, runtime execution flows, configuration specifications, feature flag discipline, CI decision models, and troubleshooting guidance for the repository. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~35 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
|
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 9196ca6f59
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
|
|
||
| ## HTTP Request Flow | ||
|
|
||
| **Correct Entry Point**: `POST /v1/{tenant}/{action}` |
There was a problem hiding this comment.
This document marks POST /v1/{tenant}/{action} as the canonical entrypoint, but the runtime still exposes POST /v1/execute (see chassis/app.py route registration and auth tests using /v1/execute). Because this file is intended as execution-source guidance, agents and reviewers will generate or validate integrations against a non-existent path, causing avoidable API/test failures.
Useful? React with 👍 / 👎.
| | Variable | Type | Purpose | Failure Mode | | ||
| |----------|------|---------|--------------| | ||
| | NEO4J_URI | str | Neo4j connection URI | Startup fails, cannot connect to graph | | ||
| | NEO4J_USER | str | Neo4j username | Startup fails, authentication error | |
There was a problem hiding this comment.
The contract lists NEO4J_USER, but settings and templates use neo4j_username/NEO4J_USERNAME (engine/config/settings.py and .env.template). Following this guidance means custom usernames are never loaded from env, which can lead to authentication failures that are hard to diagnose because the app silently falls back to the default username.
Useful? React with 👍 / 👎.
| All contracts are enforced via: | ||
| - `tools/contract_scanner.py` — banned pattern detection | ||
| - `tools/verify_contracts.py` — contract file existence and wiring validation |
There was a problem hiding this comment.
This section says contract enforcement is handled by tools/contract_scanner.py and tools/verify_contracts.py for the full 24-contract set, but the current tooling still encodes/verifies only 20 (scanner docstring and REQUIRED_CONTRACTS list). That mismatch overstates automated protection and can cause reviewers to skip manual checks under the assumption CI enforces all C-001..C-024 rules.
Useful? React with 👍 / 👎.
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 7
🧹 Nitpick comments (2)
EXECUTION_FLOWS.md (1)
129-129: Consider: LanguageTool suggests capitalizing "GitHub" in path references.While
.github/is the correct directory name (lowercase), the static analysis tool flags this for consistency. This is a minor documentation style consideration and can be safely ignored if the lowercase form is intentional for path accuracy.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@EXECUTION_FLOWS.md` at line 129, The doc currently references the repository directory as ".github/" which is correct for filesystem paths but LanguageTool flags capitalization; update EXECUTION_FLOWS.md so that platform mentions use "GitHub" (capitalized) while keeping literal path references (e.g., ".github/") exactly lowercase; ensure any mention of the workflow file name ".github/workflows/ci.yml" preserves the lowercase path but elsewhere use "GitHub" when referring to the platform or UI.INVARIANTS.md (1)
158-158: Add language identifier to fenced code block.The fenced code block starting at line 158 lacks a language identifier. While the content is clear, adding a language tag improves rendering and syntax highlighting.
📝 Suggested fix
- **Enforcement**: CODEOWNERS + PR review +```text **C-016: File Structure Fixed** - `engine/handlers.py` → ONLY chassis bridge (`register_all`)🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@INVARIANTS.md` at line 158, The fenced code block in INVARIANTS.md (the snippet containing "C-016: File Structure Fixed" and the list with `engine/handlers.py` → ONLY chassis bridge (`register_all`)) is missing a language identifier; update the opening fence from ``` to ```text (or another appropriate language) so the block is rendered with proper syntax highlighting.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@CI_WHITELIST_REGISTER.md`:
- Around line 21-35: Update the CI Pipeline Decision Model to include the
required five merge-blocking status checks by replacing the current
"Merge-Blocking Gates: validate, lint, test (3 jobs)" and the Phase list so that
pre-commit (ruff+mypy+contract_scanner) is included as Phase X and marked
BLOCKING, add CI audit (20 contracts) as a BLOCKING phase, and add LLM review as
a BLOCKING phase; ensure the Phase list and the "Merge-Blocking Gates" summary
explicitly list: pre-commit, CI lint, CI tests, CI audit, LLM review as
merge-blocking and leave security, sbom, scorecard as ADVISORY.
In `@CONFIG_ENV_CONTRACT.md`:
- Around line 38-58: The docs section must be updated to match
engine/config/settings.py and ENV-001 naming: mark Neo4j vars as optional (they
have defaults in settings via neo4j_uri, neo4j_username, neo4j_password), rename
NEO4J_USER to NEO4J_USERNAME, change MAX_RESULTS default to 25, remove the
nonexistent L9_DEFAULT_TENANT entry, and apply the L9_ prefix per convention to
infra vars (use L9_NEO4J_URI, L9_REDIS_URL, L9_MAX_RESULTS, L9_LOG_LEVEL) so the
table names, types, and defaults mirror the actual settings and .env.template
keys.
In `@DEPENDENCY_SURFACE.md`:
- Around line 107-116: The table has a contradiction: the "engine/packet/" row
currently includes `httpx` in its Forbidden Imports while the "Special case"
note and later row state `httpx` is allowed only in `engine/packet/`; update the
table so the "engine/packet/" Allowed Imports column includes `httpx` (remove it
from the Forbidden Imports for that row) and ensure the "Special case" line
references the same rule, keeping `httpx` allowed only in `engine/packet/` to
make the policy consistent (edit the "engine/packet/" row and the "Special case"
sentence to match).
In `@EXECUTION_FLOWS.md`:
- Around line 21-30: Update the "Correct Entry Point" in EXECUTION_FLOWS.md to
show the real HTTP route: replace `POST /v1/{tenant}/{action}` with `POST
/v1/execute` and note that `tenant`, `action`, and `trace_id` are passed as
function parameters rather than path segments (adjust the sequence diagram call
from Client->>Chassis: POST /v1/{tenant}/{action} to Client->>Chassis: POST
/v1/execute and annotate the parameters accordingly).
In `@FEATURE_FLAGS.md`:
- Around line 165-173: The current grep in FEATURE_FLAGS.md uses the regex
"^\s+[a-z_]+: bool = Field" which misses Settings boolean flags declared as
direct defaults; update the audit command to match the actual Settings
declarations in engine/config/settings.py by using a regex that captures both
styles (e.g. patterns like "flag_name: bool = True|False" and the Field(...)
form) so the extraction picks up flags declared as "flag: bool = True/False" as
well as "flag: bool = Field(...)" and then sort/compare as before; refer to the
Settings class and the existing grep pattern string to locate and replace the
broken command.
In `@INVARIANTS.md`:
- Line 304: The summary line "docs/contracts/ (20 individual contract files)" is
inconsistent with the document's defined contracts C-001 through C-024; update
INVARIANTS.md to reconcile this by either changing the count to "24 individual
contract files" or adding a brief clarifying sentence that maps C-021–C-024 to
their actual locations or explains which contract files contain multiple
contracts (e.g., list the filenames or state that C-021–C-024 are combined into
X files); make the edit near the existing "Detailed specs" entry and reference
contract IDs C-021, C-022, C-023, and C-024 so readers can find the discrepancy
resolved.
In `@TROUBLESHOOTING.md`:
- Around line 177-201: Update the troubleshooting example to match the actual
runtime behavior of engine/boot.py::_assert_default_weight_sum: replace the
incorrect AssertionError with ValueError and fix the numeric example so the
summed weights actually exceed 1.0 (e.g., change the displayed sum from 0.95 to
a value >1.0 like 1.05 or adjust the listed weights accordingly) and update the
explanatory text to reflect that the default weights exceed the ceiling.
Reference the function name _assert_default_weight_sum and the settings
variables (w_structural, w_geo, w_reinforcement, w_freshness, w_new_dimension)
when making the correction.
---
Nitpick comments:
In `@EXECUTION_FLOWS.md`:
- Line 129: The doc currently references the repository directory as ".github/"
which is correct for filesystem paths but LanguageTool flags capitalization;
update EXECUTION_FLOWS.md so that platform mentions use "GitHub" (capitalized)
while keeping literal path references (e.g., ".github/") exactly lowercase;
ensure any mention of the workflow file name ".github/workflows/ci.yml"
preserves the lowercase path but elsewhere use "GitHub" when referring to the
platform or UI.
In `@INVARIANTS.md`:
- Line 158: The fenced code block in INVARIANTS.md (the snippet containing
"C-016: File Structure Fixed" and the list with `engine/handlers.py` → ONLY
chassis bridge (`register_all`)) is missing a language identifier; update the
opening fence from ``` to ```text (or another appropriate language) so the block
is rendered with proper syntax highlighting.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: f37c30ba-e255-47b6-ac28-20a641a9a827
📒 Files selected for processing (10)
AGENT_BOOTSTRAP.mdAI_AGENT_REVIEW_CHECKLIST.mdCI_WHITELIST_REGISTER.mdCONFIG_ENV_CONTRACT.mdDEPENDENCY_SURFACE.mdEXECUTION_FLOWS.mdFEATURE_FLAGS.mdFILE_INDEX_FOR_AGENTS.mdINVARIANTS.mdTROUBLESHOOTING.md
| ## CI Pipeline Decision Model | ||
|
|
||
| ``` | ||
| Phase 1: Validation → BLOCKING | ||
| Phase 2: Lint & Type Check → BLOCKING | ||
| Phase 3: Test Suite → BLOCKING | ||
| Phase 4: Security Scanning → ADVISORY (non-blocking) | ||
| Phase 5: SBOM Generation → ADVISORY | ||
| Phase 6: OpenSSF Scorecard → ADVISORY | ||
| Phase 7: CI Gate (Fan-In) → BLOCKING (checks Phases 1-3) | ||
| ``` | ||
|
|
||
| **Merge-Blocking Gates**: validate, lint, test (3 jobs) | ||
| **Non-Blocking Jobs**: security, sbom, scorecard (3 jobs) | ||
|
|
There was a problem hiding this comment.
The CI gate model is incomplete relative to required status checks.
This section marks only 3 jobs as merge-blocking, but repository policy requires 5 status checks (including pre-commit, CI audit, and LLM review). Agents following this doc could approve merges prematurely.
Based on learnings: CI pipeline requires all 5 status checks: pre-commit (ruff+mypy+contract_scanner), CI lint (repo-wide), CI tests (unit+integration+compliance+perf), CI audit (20 contracts), LLM review.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@CI_WHITELIST_REGISTER.md` around lines 21 - 35, Update the CI Pipeline
Decision Model to include the required five merge-blocking status checks by
replacing the current "Merge-Blocking Gates: validate, lint, test (3 jobs)" and
the Phase list so that pre-commit (ruff+mypy+contract_scanner) is included as
Phase X and marked BLOCKING, add CI audit (20 contracts) as a BLOCKING phase,
and add LLM review as a BLOCKING phase; ensure the Phase list and the
"Merge-Blocking Gates" summary explicitly list: pre-commit, CI lint, CI tests,
CI audit, LLM review as merge-blocking and leave security, sbom, scorecard as
ADVISORY.
| ## Required Environment Variables (No Defaults) | ||
|
|
||
| | Variable | Type | Purpose | Failure Mode | | ||
| |----------|------|---------|--------------| | ||
| | NEO4J_URI | str | Neo4j connection URI | Startup fails, cannot connect to graph | | ||
| | NEO4J_USER | str | Neo4j username | Startup fails, authentication error | | ||
| | NEO4J_PASSWORD | str | Neo4j password | Startup fails, authentication error | | ||
|
|
||
| **Startup Behavior**: If any required var is missing → Settings initialization raises ValidationError → app fails to start | ||
|
|
||
| --- | ||
|
|
||
| ## Optional Environment Variables (Have Defaults) | ||
|
|
||
| | Variable | Type | Default | Purpose | | ||
| |----------|------|---------|---------| | ||
| | L9_DEFAULT_TENANT | str | "default" | Fallback tenant for 5-level resolution | | ||
| | L9_LOG_LEVEL | str | "INFO" | Structlog log level (DEBUG, INFO, WARN, ERROR) | | ||
| | REDIS_URL | str | "redis://localhost:6379/0" | Redis connection string | | ||
| | MAX_RESULTS | int | 100 | Maximum match results returned per query | | ||
|
|
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "== Settings fields related to Neo4j / logging / max_results / L9 =="
rg -n "neo4j_|log_level|max_results|l9_default_tenant|l9_" engine/config/settings.py -C 2
echo
echo "== Env template entries =="
rg -n "NEO4J_|REDIS_|L9_|MAX_RESULTS|LOG_LEVEL" .env.template -C 1
echo
echo "== Check for NEO4J_USER vs NEO4J_USERNAME usage in repo =="
rg -n "NEO4J_USER(NAME)?"Repository: cryptoxdog/Cognitive.Engine.Graphs
Length of output: 4466
Correct environment variable names and defaults to match engine/config/settings.py.
The documented required/optional env contract contradicts the actual settings:
- Neo4j variables claim "no defaults" but
engine/config/settings.pylines 42–44 define defaults forneo4j_uri,neo4j_username,neo4j_password. - Uses
NEO4J_USERbut the actual environment variable isNEO4J_USERNAME(see.env.templateline 20,engine/graph/driver.pyline 46). MAX_RESULTSdefault is 25 (settings.py line 75), not 100 as documented.L9_DEFAULT_TENANTnot found in settings or.env.template; likely undocumented or removed.- L9_ prefixing violations: Infra variables
NEO4J_URI,REDIS_URL,MAX_RESULTS, andLOG_LEVELlack the required L9_ prefix per ENV-001 convention.
Update this section from the actual settings definitions to prevent deployment misconfiguration.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@CONFIG_ENV_CONTRACT.md` around lines 38 - 58, The docs section must be
updated to match engine/config/settings.py and ENV-001 naming: mark Neo4j vars
as optional (they have defaults in settings via neo4j_uri, neo4j_username,
neo4j_password), rename NEO4J_USER to NEO4J_USERNAME, change MAX_RESULTS default
to 25, remove the nonexistent L9_DEFAULT_TENANT entry, and apply the L9_ prefix
per convention to infra vars (use L9_NEO4J_URI, L9_REDIS_URL, L9_MAX_RESULTS,
L9_LOG_LEVEL) so the table names, types, and defaults mirror the actual settings
and .env.template keys.
| | Subsystem | Allowed Imports | Forbidden Imports | | ||
| |-----------|----------------|-------------------| | ||
| | engine/ | neo4j, pydantic, structlog, redis, numpy | fastapi, starlette, uvicorn, httpx (in most modules) | | ||
| | engine/handlers.py ONLY | chassis.router | All others | | ||
| | engine/packet/ | All above + chassis contracts | httpx | | ||
| | chassis/ | fastapi, starlette, uvicorn, all engine/ | None (chassis can import anything) | | ||
| | tests/ | All packages | None | | ||
|
|
||
| **Special case**: `httpx` allowed ONLY in `engine/packet/` for delegation protocol (Contract C-008). | ||
| Forbidden elsewhere in engine/ (Contract C-008 enforcement via scanner DEL-001, DEL-002). |
There was a problem hiding this comment.
Resolve the httpx policy contradiction in the import-boundary table.
At Line 111, engine/packet/ lists httpx as forbidden, but Line 115 says httpx is allowed only in engine/packet/. These cannot both be true.
Suggested doc fix
-| engine/packet/ | All above + chassis contracts | httpx |
+| engine/packet/ | All above + chassis contracts + httpx | None |📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| | Subsystem | Allowed Imports | Forbidden Imports | | |
| |-----------|----------------|-------------------| | |
| | engine/ | neo4j, pydantic, structlog, redis, numpy | fastapi, starlette, uvicorn, httpx (in most modules) | | |
| | engine/handlers.py ONLY | chassis.router | All others | | |
| | engine/packet/ | All above + chassis contracts | httpx | | |
| | chassis/ | fastapi, starlette, uvicorn, all engine/ | None (chassis can import anything) | | |
| | tests/ | All packages | None | | |
| **Special case**: `httpx` allowed ONLY in `engine/packet/` for delegation protocol (Contract C-008). | |
| Forbidden elsewhere in engine/ (Contract C-008 enforcement via scanner DEL-001, DEL-002). | |
| | Subsystem | Allowed Imports | Forbidden Imports | | |
| |-----------|----------------|-------------------| | |
| | engine/ | neo4j, pydantic, structlog, redis, numpy | fastapi, starlette, uvicorn, httpx (in most modules) | | |
| | engine/handlers.py ONLY | chassis.router | All others | | |
| | engine/packet/ | All above + chassis contracts + httpx | None | | |
| | chassis/ | fastapi, starlette, uvicorn, all engine/ | None (chassis can import anything) | | |
| | tests/ | All packages | None | | |
| **Special case**: `httpx` allowed ONLY in `engine/packet/` for delegation protocol (Contract C-008). | |
| Forbidden elsewhere in engine/ (Contract C-008 enforcement via scanner DEL-001, DEL-002). |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@DEPENDENCY_SURFACE.md` around lines 107 - 116, The table has a contradiction:
the "engine/packet/" row currently includes `httpx` in its Forbidden Imports
while the "Special case" note and later row state `httpx` is allowed only in
`engine/packet/`; update the table so the "engine/packet/" Allowed Imports
column includes `httpx` (remove it from the Forbidden Imports for that row) and
ensure the "Special case" line references the same rule, keeping `httpx` allowed
only in `engine/packet/` to make the policy consistent (edit the
"engine/packet/" row and the "Special case" sentence to match).
| **Correct Entry Point**: `POST /v1/{tenant}/{action}` | ||
|
|
||
| ```mermaid | ||
| sequenceDiagram | ||
| participant Client | ||
| participant Chassis | ||
| participant Engine | ||
| participant Neo4j | ||
|
|
||
| Client->>Chassis: POST /v1/{tenant}/{action} |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Description: Find the actual HTTP route definition in chassis code
# Search for route decorators and path definitions
rg -n -A 3 -B 3 '@app\.(post|get|put|delete)' --glob 'chassis/**/*.py'
# Also search for router path definitions
rg -n -A 3 -B 3 'router\.(post|get|put|delete)' --glob 'chassis/**/*.py'
# Look for FastAPI/Starlette route definitions
rg -n -A 3 -B 3 'APIRouter|Route\(' --glob 'chassis/**/*.py'Repository: cryptoxdog/Cognitive.Engine.Graphs
Length of output: 1148
Update the HTTP entry point in EXECUTION_FLOWS.md to match the actual implementation.
The documentation states the entry point is POST /v1/{tenant}/{action}, but the actual HTTP route is POST /v1/execute with tenant, action, and trace_id passed as function parameters rather than path segments. Update line 21 to reflect the correct route.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@EXECUTION_FLOWS.md` around lines 21 - 30, Update the "Correct Entry Point" in
EXECUTION_FLOWS.md to show the real HTTP route: replace `POST
/v1/{tenant}/{action}` with `POST /v1/execute` and note that `tenant`, `action`,
and `trace_id` are passed as function parameters rather than path segments
(adjust the sequence diagram call from Client->>Chassis: POST
/v1/{tenant}/{action} to Client->>Chassis: POST /v1/execute and annotate the
parameters accordingly).
| Run this command to verify all flags in settings.py are documented here: | ||
|
|
||
| ```bash | ||
| # Extract flag names from settings.py | ||
| grep -E "^\s+[a-z_]+: bool = Field" engine/config/settings.py | awk '{print $1}' | sort | ||
|
|
||
| # Compare to this document | ||
| # Any mismatch = documentation drift | ||
| ``` |
There was a problem hiding this comment.
Fix the flag-audit command; it does not match actual Settings declarations.
At Line 169, grep -E "^\s+[a-z_]+: bool = Field" won’t find most boolean flags because engine/config/settings.py uses direct defaults (flag: bool = True/False). This makes the drift check unreliable.
Suggested doc fix
- grep -E "^\s+[a-z_]+: bool = Field" engine/config/settings.py | awk '{print $1}' | sort
+ grep -E "^[[:space:]]+[a-z_]+:[[:space:]]+bool[[:space:]]*=" engine/config/settings.py \
+ | sed -E 's/^[[:space:]]*([a-z_]+):.*/\1/' | sort🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@FEATURE_FLAGS.md` around lines 165 - 173, The current grep in
FEATURE_FLAGS.md uses the regex "^\s+[a-z_]+: bool = Field" which misses
Settings boolean flags declared as direct defaults; update the audit command to
match the actual Settings declarations in engine/config/settings.py by using a
regex that captures both styles (e.g. patterns like "flag_name: bool =
True|False" and the Field(...) form) so the extraction picks up flags declared
as "flag: bool = True/False" as well as "flag: bool = Field(...)" and then
sort/compare as before; refer to the Settings class and the existing grep
pattern string to locate and replace the broken command.
| ## Related Documents | ||
|
|
||
| - **Source**: .claude/rules/contracts.md (C-001 to C-024 tabular reference) | ||
| - **Detailed specs**: docs/contracts/ (20 individual contract files) |
There was a problem hiding this comment.
Resolve contract count discrepancy.
Line 304 states "docs/contracts/ (20 individual contract files)" but this document defines 24 contracts (C-001 to C-024). Known Unknowns section (line 285) acknowledges "some contract files may be missing," but the 4-file gap should be clarified.
Are C-021 to C-024 documented elsewhere, or do 4 contracts share files?
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@INVARIANTS.md` at line 304, The summary line "docs/contracts/ (20 individual
contract files)" is inconsistent with the document's defined contracts C-001
through C-024; update INVARIANTS.md to reconcile this by either changing the
count to "24 individual contract files" or adding a brief clarifying sentence
that maps C-021–C-024 to their actual locations or explains which contract files
contain multiple contracts (e.g., list the filenames or state that C-021–C-024
are combined into X files); make the edit near the existing "Detailed specs"
entry and reference contract IDs C-021, C-022, C-023, and C-024 so readers can
find the discrepancy resolved.
| ``` | ||
| AssertionError: Default scoring weights sum to 0.95, exceeds ceiling of 1.0 | ||
| File: engine/boot.py::_assert_default_weight_sum | ||
| ``` | ||
|
|
||
| ### Diagnosis | ||
| This violates **Contract C-022** (Scoring Weight Ceiling). You added a new weight without reducing existing ones. | ||
|
|
||
| ### Resolution | ||
| ```python | ||
| # In engine/config/settings.py | ||
| # Before (sum = 0.95): | ||
| w_structural = 0.30 | ||
| w_geo = 0.25 | ||
| w_reinforcement = 0.20 | ||
| w_freshness = 0.10 | ||
| w_new_dimension = 0.10 # ❌ causes sum = 0.95 | ||
|
|
||
| # After (sum = 0.95 → 0.90): | ||
| w_structural = 0.28 # reduced | ||
| w_geo = 0.23 # reduced | ||
| w_reinforcement = 0.19 # reduced | ||
| w_freshness = 0.10 # unchanged | ||
| w_new_dimension = 0.10 # new | ||
| ``` |
There was a problem hiding this comment.
Correct the startup error example and exception type in this section.
Line 178 says 0.95 exceeds 1.0 (it doesn’t), and Line 178/179 uses AssertionError while engine/boot.py::_assert_default_weight_sum() raises ValueError. This makes the troubleshooting path inaccurate.
🧰 Tools
🪛 markdownlint-cli2 (0.22.0)
[warning] 177-177: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@TROUBLESHOOTING.md` around lines 177 - 201, Update the troubleshooting
example to match the actual runtime behavior of
engine/boot.py::_assert_default_weight_sum: replace the incorrect AssertionError
with ValueError and fix the numeric example so the summed weights actually
exceed 1.0 (e.g., change the displayed sum from 0.95 to a value >1.0 like 1.05
or adjust the listed weights accordingly) and update the explanatory text to
reflect that the default weights exceed the ceiling. Reference the function name
_assert_default_weight_sum and the settings variables (w_structural, w_geo,
w_reinforcement, w_freshness, w_new_dimension) when making the correction.
1 participant
CEG Corrected Documentation Pack
10 new governance + reference docs.
AGENT_BOOTSTRAP.mdAI_AGENT_REVIEW_CHECKLIST.mdCI_WHITELIST_REGISTER.mdCONFIG_ENV_CONTRACT.mdDEPENDENCY_SURFACE.mdEXECUTION_FLOWS.mdFEATURE_FLAGS.mdFILE_INDEX_FOR_AGENTS.mdINVARIANTS.mdTROUBLESHOOTING.mdIgorBot · 2026-04-02
Summary by CodeRabbit