Repository navigation
feat(OMN-9600): refresh omnibase_infra documentation - #1396
Merged
Merged
Conversation
📝 WalkthroughWalkthroughUpdates many documentation files (deletions, metadata/ticket-reference removals, governance edits), adjusts runtime docs/README and operational guides, adds a deploy-evidence contract Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Poem
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Comment |
jonahgabriel
changed the title
jonahgabriel
force-pushed
the
jonah/omn-9600-omnibase-infra-docs-refresh
branch
from
April 24, 2026 17:38
b7f7f5f to
bd44659
Compare
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@CLAUDE.md`:
- Around line 276-278: The defaults for persistent state are anchored to the
user home but should be workspace-local; update the constructors of
AgentRegistry and LocalStubProjectTracker so their default paths do not use
Path.home(), e.g., change the default for AgentRegistry (currently Path.home() /
".onex_state") and for LocalStubProjectTracker (currently Path.home() /
".onex_state" / "local-tracker") to resolve under a workspace-local root (such
as a provided workspace root or a relative ".onex_state" path) so that when
state_dir/state_root is not passed the components place state under the
workspace ".onex_state" directory instead of ~/.onex/.
In `@docs/validation/README.md`:
- Around line 122-133: Update the "What it checks" list in the Markdown Link
Validator section to mention external link validation: state that
scripts/validation/validate_markdown_links.py also verifies external link
targets are reachable via HTTP HEAD requests (e.g., "External link targets are
reachable via HTTP HEAD requests") so readers know the validator checks both
local file resolution and remote HTTP reachability.
🪄 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: defaults
Review profile: CHILL
Plan: Pro
Run ID: d61d3552-0b91-4ac2-a03d-c9161e1a2e0e
📒 Files selected for processing (26)
CLAUDE.mdREADME.mddocs/architecture/HANDLER_CLASSIFICATION_3_2A_CIRCUIT_BREAKER_RETRY.mddocs/architecture/HANDLER_CLASSIFICATION_3_3_LLM_HTTP_TRANSPORT.mddocs/architecture/HANDLER_CLASSIFICATION_POC_3_1.mddocs/architecture/HANDLER_CLASSIFICATION_POC_3_2B.mddocs/architecture/HANDLER_CLASSIFICATION_RULES.mddocs/architecture/HANDLER_PROTOCOL_DRIVEN_ARCHITECTURE.mddocs/architecture/README.mddocs/guides/INFISICAL_SECRETS_GUIDE.mddocs/handoff/2026-02-23-omn-2287-phase2-review.mddocs/index.mddocs/investigations/2026-04-21-registration-shared-topic-consumer-collapse.mddocs/investigations/OMN-3988-non-node-dirs-under-nodes.mddocs/operations/CI_BASELINE_OMNIBASE_INFRA.mddocs/operations/INFISICAL_SEED_VERIFICATION_OMN3898.mddocs/operations/README.mddocs/patterns/headless_decomposition.mddocs/plugins/PLUGIN_DETERMINISM.mddocs/plugins/README.mddocs/plugins/json_normalizer_optimization.mddocs/standards/STANDARD_DOC_LAYOUT.mddocs/validation/EVENT_BUS_COVERAGE_REPORT.mddocs/validation/README.mddocs/validation/circular_import_validator_improvements.mddocs/verification/omn-5656-e2e-error-triage-verification.md
💤 Files with no reviewable changes (15)
- docs/patterns/headless_decomposition.md
- docs/operations/CI_BASELINE_OMNIBASE_INFRA.md
- docs/plugins/json_normalizer_optimization.md
- docs/validation/circular_import_validator_improvements.md
- docs/architecture/HANDLER_CLASSIFICATION_POC_3_1.md
- docs/architecture/HANDLER_CLASSIFICATION_RULES.md
- docs/architecture/HANDLER_CLASSIFICATION_POC_3_2B.md
- docs/operations/INFISICAL_SEED_VERIFICATION_OMN3898.md
- docs/verification/omn-5656-e2e-error-triage-verification.md
- docs/architecture/HANDLER_CLASSIFICATION_3_2A_CIRCUIT_BREAKER_RETRY.md
- docs/validation/EVENT_BUS_COVERAGE_REPORT.md
- docs/investigations/2026-04-21-registration-shared-topic-consumer-collapse.md
- docs/architecture/HANDLER_CLASSIFICATION_3_3_LLM_HTTP_TRANSPORT.md
- docs/handoff/2026-02-23-omn-2287-phase2-review.md
- docs/investigations/OMN-3988-non-node-dirs-under-nodes.md
jonahgabriel
force-pushed
the
jonah/omn-9600-omnibase-infra-docs-refresh
branch
from
April 24, 2026 17:47
bd44659 to
6f76ca1
Compare
jonahgabriel
changed the title
…ernal link check
- AgentRegistry and LocalStubProjectTracker now default to Path(".onex_state")
instead of Path.home() / ".onex_state" — workspace-local per CLAUDE.md guidance
- docs/validation/README.md: add external HTTP HEAD link check to validator docs
…, receipt-gate, and integration coverage gates - contracts/OMN-9600.yaml: per-repo deploy-gate carrier with dod_evidence containing 'docker exec' check_value - tests/integration/test_omn_9600_path_defaults.py: 4 integration tests proving workspace-local .onex_state defaults are in place and Path.home() was removed
![github-advanced-security[bot]](https://avatars.githubusercontent.com/in/57789?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
Note
Due to the large number of review comments, Critical, Major severity comments were prioritized as inline comments.
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (3)
docs/patterns/secret_resolver.md (1)
664-687:⚠️ Potential issue | 🟡 MinorAllowlist examples are now ambiguous to copy/paste.
On Line 664 and Lines 675/680/681/682/687, removing ticket IDs left blank reason prefixes (for example
# POSTGRES_HOST). This makes the documented format unclear and easy to misuse.Proposed doc fix
-# : Centralized secret resolution +# migration: Centralized secret resolution ... -src/omnibase_infra/runtime/service_kernel.py:630 # POSTGRES_HOST +src/omnibase_infra/runtime/service_kernel.py:630 # migration POSTGRES_HOST🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/patterns/secret_resolver.md` around lines 664 - 687, The allowlist entries have had their ticket IDs removed leaving blank reason prefixes like "# POSTGRES_HOST" which makes the format ambiguous; update the entries in docs/patterns/secret_resolver.md so each line follows the documented "filepath:line_number # ticket reason" format by adding either the missing ticket IDs or a clear reason text for examples (e.g., replace "# POSTGRES_HOST" with "# TICKET-XXXXX POSTGRES_HOST" or "# example: POSTGRES_HOST"), and ensure the shown examples around the Event Bus and Runtime/Nodes sections (files model_kafka_event_bus_config.py, service_kernel.py, plugin.py) clearly demonstrate a copy/paste-ready allowlist entry.docs/decisions/adr-any-type-pydantic-workaround.md (1)
950-954:⚠️ Potential issue | 🟡 MinorReferences section has malformed bullet labels.
Line 950–954 contains empty/invalid labels (
- : ...,- **: ...), which should be cleaned up to plain neutral text labels after ID redaction.✏️ Proposed fix pattern
-- - : Refactor RegistrationReducer to be fully declarative +- - **Related Work**: Refactor RegistrationReducer to be fully declarative🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/decisions/adr-any-type-pydantic-workaround.md` around lines 950 - 954, The References section contains malformed bullet labels like "- : ..." and "- **: ..." that appeared after ID redaction; update those entries to use plain neutral labels (e.g., replace the empty/invalid label prefix with a normal bullet "- " or plain sentence) so the lines read "- Refactor RegistrationReducer to be fully declarative", "- Migration tracking issue for Any type cleanup", "- Pre-existing test failures and integration test coverage", and "** Migration completion - Any to JsonType (2026-01-08)**" (or convert the last to a normal bullet) to remove the stray colon/asterisk tokens and restore consistent bullet formatting in adr-any-type-pydantic-workaround.md.docs/architecture/EVENT_STREAMING_TOPICS.md (1)
982-982:⚠️ Potential issue | 🟡 MinorDelete the empty “Related Tickets” section header.
Line 982 leaves a section title with no content. Remove it to avoid a dead-end section.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/architecture/EVENT_STREAMING_TOPICS.md` at line 982, Remove the empty "Related Tickets" section header from the document — locate the heading string "## Related Tickets" in EVENT_STREAMING_TOPICS.md (the header shown in the diff) and delete that line so there is no dead-end section left in the file.
🟡 Minor comments (22)
docs/decisions/adr-error-context-factory-pattern.md-7-7 (1)
7-7:⚠️ Potential issue | 🟡 MinorFix dangling placeholders introduced by ticket-reference removal.
Line 7 and Line 525 now contain incomplete prose (
**Follow-up Tickets**: ...andonce is implemented), which makes the ADR ambiguous. Replace with ticket-neutral wording (e.g., “Follow-up Items” and explicit validator name).📝 Proposed doc wording fix
-**Follow-up Tickets**: (validator), (migration) +**Follow-up Items**: validator implementation, migration rollout -**Note**: These grep commands are for quick manual verification only. They may produce false positives (e.g., comments, string literals, docstrings) and miss complex patterns (e.g., multiline expressions, indirect variable assignment). Use the AST-based validator for authoritative enforcement once is implemented. +**Note**: These grep commands are for quick manual verification only. They may produce false positives (e.g., comments, string literals, docstrings) and miss complex patterns (e.g., multiline expressions, indirect variable assignment). Use the AST-based `correlation_patterns` validator for authoritative enforcement once implemented.Also applies to: 525-525
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/decisions/adr-error-context-factory-pattern.md` at line 7, Replace the dangling ticket placeholders by changing the header "**Follow-up Tickets**: (validator), (migration)" to a ticket-neutral heading (e.g., "**Follow-up Items**:") and enumerate concrete items, and replace the incomplete reference "once is implemented" with an explicit validator name (e.g., "once the <ValidatorName> validator is implemented") so the ADR contains complete, unambiguous prose; update the two occurrences referenced (the heading near the top and the sentence at the bottom) accordingly.docs/standards/TOPIC_TAXONOMY.md-5-5 (1)
5-5:⚠️ Potential issue | 🟡 MinorFix orphaned sentence fragments left by reference removal.
Line 5, Line 27, and Line 87 have missing tokens (e.g., “introduced in ,”, “ changed…”, “as of ”), which makes the doc read as incomplete. Please replace removed identifiers with neutral phrasing (date/version/general wording) so the narrative remains grammatically complete.
Suggested doc-only patch
-Kafka topic naming convention for `omnibase_infra`. Covers the realm-agnostic suffix format introduced in , the topic name construction pattern, and all defined topic suffix constants. +Kafka topic naming convention for `omnibase_infra`. Covers the realm-agnostic suffix format, the topic name construction pattern, and all defined topic suffix constants. ... - changed the topic format from an environment-prefixed scheme (e.g., `dev.archon-intelligence.intelligence.code-analysis-requested.v1`) to the current realm-agnostic scheme (`onex.<kind>.<producer>.<event-name>.v<version>`). The new format does not encode environment or deployment context in the suffix itself — that is the caller's responsibility. +A prior platform update changed the topic format from an environment-prefixed scheme (e.g., `dev.archon-intelligence.intelligence.code-analysis-requested.v1`) to the current realm-agnostic scheme (`onex.<kind>.<producer>.<event-name>.v<version>`). The new format does not encode environment or deployment context in the suffix itself — that is the caller's responsibility. ... -**E2E tests use suffixes directly** (no prefix) when interacting with the local Docker infrastructure. The topic `onex.evt.platform.node-introspection.v1` is used as-is. Note that as of the runtime kernel no longer reads `ONEX_INPUT_TOPIC` / `ONEX_OUTPUT_TOPIC` — topics are derived from each node's `contract.yaml` `event_bus` declaration and setting those env vars raises `ProtocolConfigurationError` at bootstrap. +**E2E tests use suffixes directly** (no prefix) when interacting with the local Docker infrastructure. The topic `onex.evt.platform.node-introspection.v1` is used as-is. Note that in current runtime behavior, the runtime kernel no longer reads `ONEX_INPUT_TOPIC` / `ONEX_OUTPUT_TOPIC` — topics are derived from each node's `contract.yaml` `event_bus` declaration and setting those env vars raises `ProtocolConfigurationError` at bootstrap.Also applies to: 27-27, 87-87
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/standards/TOPIC_TAXONOMY.md` at line 5, The document contains orphaned sentence fragments where references were removed (e.g., the phrases "introduced in ,", " changed…", and "as of ") which break sentence flow; update TOPIC_TAXONOMY.md by replacing those fragments with neutral, complete phrasing such as "introduced in a recent change", "was changed", or "as of the latest update" (or another concise date/version neutral wording) so the sentences at the locations containing "introduced in ,", " changed…", and "as of " read grammatically complete without external identifiers.docs/patterns/retry_backoff_compensation_strategy.md-45-45 (1)
45-45:⚠️ Potential issue | 🟡 MinorRemove or replace the blank citation placeholder
Line 45 leaves an unresolved reference (
(see )), which reads as broken documentation. Please either remove the parenthetical or replace it with a concrete internal doc link/reference.✏️ Suggested doc fix
-- The `retries` field was intentionally removed from effect result models (see ) +- The `retries` field was intentionally removed from effect result models.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/patterns/retry_backoff_compensation_strategy.md` at line 45, The sentence containing "The `retries` field was intentionally removed from effect result models (see )" has a broken citation; either remove the empty parenthetical or replace it with a valid internal doc link/reference. Edit the sentence in the retry_backoff_compensation_strategy.md content that mentions the `retries` field and either delete " (see )" entirely or substitute a concrete reference/URL to the relevant internal doc that explains the removal.docs/decisions/adr-projector-composite-key-upsert-workaround.md-204-204 (1)
204-204:⚠️ Potential issue | 🟡 MinorFix empty reference label on Line 204.
The entry currently has a blank prefix (
- : ...), which reads as a malformed reference. Replace it with a neutral label (non-ticket) to keep the docs clean while still meeting the “no ticket IDs” objective.🛠️ Proposed fix
-- : Convert ProjectorRegistration to declarative contract +- Backlog item: Convert ProjectorRegistration to declarative contract🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/decisions/adr-projector-composite-key-upsert-workaround.md` at line 204, Replace the malformed blank reference prefix in the markdown entry "- : Convert ProjectorRegistration to declarative contract" by adding a neutral non-ticket label (e.g., "Note", "Misc", or "Info") so the line becomes "Note: Convert ProjectorRegistration to declarative contract"; edit the line containing "ProjectorRegistration" to only change the prefix and avoid inserting any ticket IDs or extra markup.docs/patterns/secret_resolver.md-693-693 (1)
693-693:⚠️ Potential issue | 🟡 MinorConvention text contradicts the new no-ticket policy.
Line 693 still says to include a ticket reference, but the PR explicitly removes ticket-number references from public docs. Please update this rule to require a non-ticket rationale instead.
Proposed doc fix
-- Include ticket reference (e.g., ``) and variable name as the reason +- Include a short rationale label and variable name as the reason (no ticket IDs in public docs)🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/patterns/secret_resolver.md` at line 693, Update the rule that currently reads "Include ticket reference (e.g., ``) and variable name as the reason" so it no longer asks for ticket numbers; instead require a non-ticket rationale plus the variable name as the reason (e.g., a brief description like "security cleanup" or "rotate expired key" and the env var name). Locate the exact phrase in the docs (the sentence beginning "Include ticket reference (e.g.," in secret_resolver.md) and replace it with wording that forbids ticket-number references and instructs contributors to supply a concise, non-ticket rationale plus the variable name.docs/guides/MCP_INTEGRATION_GUIDE.md-102-102 (1)
102-102:⚠️ Potential issue | 🟡 MinorFix incomplete sentence after ticket reference removal.
The sentence ends with "is planned under )." which is grammatically incomplete and unclear. The dangling closing parenthesis suggests incomplete removal of a ticket reference.
📝 Proposed fix to complete the sentence
-`ONEXToMCPAdapter` converts ONEX node metadata into `MCPToolDefinition` structs. Registration is currently manual (automatic discovery from contract `mcp_enabled: true` is planned under ). +`ONEXToMCPAdapter` converts ONEX node metadata into `MCPToolDefinition` structs. Registration is currently manual (automatic discovery from contract `mcp_enabled: true` is planned for a future release).🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/guides/MCP_INTEGRATION_GUIDE.md` at line 102, The sentence describing ONEXToMCPAdapter's role ends with a dangling fragment "is planned under )." — revise the sentence to be complete and clear by removing the stray parenthesis and finishing the thought; for example, state that automatic discovery based on the contract flag mcp_enabled: true is planned (or specify the planned mechanism), so the line mentioning ONEXToMCPAdapter, MCPToolDefinition, and the mcp_enabled flag reads as a complete sentence without stray punctuation.docs/architecture/SNAPSHOT_PUBLISHING.md-781-783 (1)
781-783:⚠️ Potential issue | 🟡 MinorFix malformed markdown syntax from ticket ID removal.
The removal of ticket identifiers left empty bold markers (
** **) which produces invalid markdown. The static analysis tool correctly flagged this as MD037 (spaces inside emphasis markers).✨ Proposed fix to remove empty bold markers
-- ** (F2)**: Snapshot Publishing (this feature) -- ** (F1)**: Implement Registration Projection Schema -- ** (F0)**: Define Projector Execution Model +- **(F2)**: Snapshot Publishing (this feature) +- **(F1)**: Implement Registration Projection Schema +- **(F0)**: Define Projector Execution ModelAlternatively, if the feature levels don't require emphasis, consider:
-- ** (F2)**: Snapshot Publishing (this feature) -- ** (F1)**: Implement Registration Projection Schema -- ** (F0)**: Define Projector Execution Model +- (F2): Snapshot Publishing (this feature) +- (F1): Implement Registration Projection Schema +- (F0): Define Projector Execution Model🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/architecture/SNAPSHOT_PUBLISHING.md` around lines 781 - 783, The three list lines contain empty bold markers around the ticket labels (e.g., "** (F2)**: Snapshot Publishing (this feature)", "** (F1)**: Implement Registration Projection Schema", "** (F0)**: Define Projector Execution Model") which triggers MD037; remove the empty emphasis or replace it with valid emphasis around the label itself. Locate these list entries in SNAPSHOT_PUBLISHING.md and either change "** (F2)**:" to "(F2):" (and similarly for F1/F0) or make the label bold correctly like "**F2**: Snapshot Publishing" so there are no spaces inside emphasis markers.docs/decisions/adr-two-handler-systems.md-12-18 (1)
12-18:⚠️ Potential issue | 🟡 MinorRedaction left broken sentences in Context.
Line 12 (
During research) and Line 17 (caused to be planned) are missing subject text. Please rewrite these as neutral phrases (e.g., “During internal research…” / “caused this work to be planned…”).🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/decisions/adr-two-handler-systems.md` around lines 12 - 18, The two sentences in the ADR context are missing subjects: replace "During research (2026-02-06)" with a neutral phrase like "During internal research (2026-02-06)" and replace "caused to be planned" with a neutral phrase like "caused this work to be planned" so the paragraph reads clearly and neutrally; update the occurrences in the ADR content (the phrases "During research (2026-02-06)" and "caused to be planned") accordingly.docs/decisions/adr-two-handler-systems.md-227-228 (1)
227-228:⚠️ Potential issue | 🟡 MinorRemove empty reference bullets.
Line 227 and Line 228 are currently
- : ..., which renders as malformed references. Either provide a non-sensitive label or remove the bullets.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/decisions/adr-two-handler-systems.md` around lines 227 - 228, Remove or fix the two malformed reference bullets that read "- : Research that discovered this architectural gap" and "- : Parent epic with architecture findings" by either deleting those empty/reference-only list items or replacing the colon placeholders with a valid, non-sensitive label (e.g., "- Research: ..." or "- Parent epic: ...") so they render correctly; update the markdown in the ADR document accordingly.docs/decisions/adr-004-performance-baseline-thresholds.md-24-24 (1)
24-24:⚠️ Potential issue | 🟡 MinorRedacted wording leaves incomplete traceability statements.
Line 24 and Line 109 have missing nouns after redaction, which makes the ADR read as unfinished. Please replace with neutral non-ID phrasing (e.g., “original requirements” and “linked to internal tracking and calibration date”).
Also applies to: 109-109
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/decisions/adr-004-performance-baseline-thresholds.md` at line 24, Replace the two redacted/unfinished noun phrases in the ADR with neutral, complete wording: change the fragment "The original requirements" to "The original requirements" (or "original requirements") and change the other redacted phrase to "linked to internal tracking and calibration date" (or similar neutral wording) so both occurrences read as complete, traceable statements and maintain consistent phrasing across the document (ensure the same replacement is applied at both locations mentioned).docs/decisions/adr-002-enum-message-category-node-output-separation.md-338-338 (1)
338-338:⚠️ Potential issue | 🟡 MinorClean up the redacted ticket line formatting.
Line 338 currently leaves a dangling placeholder (
**Ticket**: - ...). Keep the description, but remove empty punctuation to avoid broken prose in published docs.✏️ Proposed fix
-- **Ticket**: - Resolve EnumMessageCategory drift between core and infra +- **Ticket**: Resolve EnumMessageCategory drift between core and infra🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/decisions/adr-002-enum-message-category-node-output-separation.md` at line 338, Edit the ADR text containing the dangling ticket placeholder by locating the line that reads "**Ticket**: - Resolve EnumMessageCategory drift between core and infra" and remove the stray hyphen/extra punctuation so it becomes a clean sentence (e.g., "**Ticket**: Resolve EnumMessageCategory drift between core and infra") or entirely remove the empty ticket field if not needed; update the surrounding prose to ensure no leftover stray punctuation remains.docs/decisions/adr-canonical-publish-interface-policy.md-269-270 (1)
269-270:⚠️ Potential issue | 🟡 MinorReferences contain redaction artifacts.
Line 269 and Line 270 use empty ticket placeholders (
: - ...), which read as broken metadata.✏️ Proposed fix
-- **Parent Ticket**: - Publish Interface Consolidation -- **This Ticket**: - Write ADR for Canonical Publish Interface Policy +- **Parent Ticket**: Publish Interface Consolidation +- **This Ticket**: Write ADR for Canonical Publish Interface Policy🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/decisions/adr-canonical-publish-interface-policy.md` around lines 269 - 270, The metadata lines labeled "Parent Ticket" and "This Ticket" contain empty placeholders and should be fixed; update the "**Parent Ticket**: - Publish Interface Consolidation" and "**This Ticket**: - Write ADR for Canonical Publish Interface Policy" entries to include the actual ticket identifiers or URLs (e.g., JIRA/issue IDs) or remove the placeholder entries entirely so the front-matter reads as valid metadata without empty fields; ensure the labels remain exactly "Parent Ticket" and "This Ticket" to match the ADR convention.docs/architecture/MESSAGE_DISPATCH_ENGINE.md-472-472 (1)
472-472:⚠️ Potential issue | 🟡 MinorFix incomplete strict-mode provenance text.
Line 472 ends with
per ), which is incomplete after ticket cleanup. Please remove that fragment or replace it with a concrete date/version reference.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/architecture/MESSAGE_DISPATCH_ENGINE.md` at line 472, The provenance text contains a dangling fragment "per )" in the line that reads "Status: ENABLED (INFRA_PATTERNS_STRICT = True per )"; update the MESSAGE_DISPATCH_ENGINE.md entry so that the parenthetical is either removed or completed with a concrete reference (e.g., a date or version) — edit the line containing INFRA_PATTERNS_STRICT and replace "per )" with a meaningful provenance like "(INFRA_PATTERNS_STRICT = True as of YYYY-MM-DD)" or simply remove the trailing "per )".docs/patterns/security_patterns.md-630-631 (1)
630-631:⚠️ Potential issue | 🟡 MinorClean up dangling migration provenance text.
Line 630 has
migrated from HashiCorp Vault in ), which is incomplete. Remove the parenthetical or replace it with a concrete date/version.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/patterns/security_patterns.md` around lines 630 - 631, Remove the dangling parenthetical "migrated from HashiCorp Vault in )" in the docs/patterns/security_patterns.md text and either delete the entire parenthetical or replace it with a concrete migration date/version (e.g., "migrated from HashiCorp Vault in 2024") so the sentence reads cleanly; look for the exact snippet "migrated from HashiCorp Vault in )" to locate the spot.docs/runbooks/apply-migrations.md-294-295 (1)
294-295:⚠️ Potential issue | 🟡 MinorFix incomplete sentence after ticket-reference removal.
Line 294 currently says
This tool (added in ) ..., which is grammatically incomplete. Please remove the parenthetical or replace it with a date/release marker.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/runbooks/apply-migrations.md` around lines 294 - 295, Edit the incomplete sentence "This tool (added in ) ensures no migrations are missing from either the filesystem or the database." and remove the empty parenthetical or replace it with a concrete marker (e.g., a date or release name) so the sentence reads grammatically correct—either "This tool ensures no migrations are missing from either the filesystem or the database." or "This tool (added in vX.Y or YYYY-MM) ensures no migrations are missing from either the filesystem or the database."docs/operations/DATABASE_INDEX_MONITORING_RUNBOOK.md-12-12 (1)
12-12:⚠️ Potential issue | 🟡 MinorRemove the empty metadata placeholder.
Line 12 leaves
**Related Ticket**:blank, which reads as unfinished metadata. Either remove this line entirely or replace it with a non-ticket label (e.g., “Related Context”).🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/operations/DATABASE_INDEX_MONITORING_RUNBOOK.md` at line 12, The file contains an empty metadata placeholder "**Related Ticket**:" on the documented runbook; remove that line or replace it with a meaningful label like "**Related Context**" and accompanying text so the metadata is not left blank—update the string "**Related Ticket**:" in the document accordingly.docs/validation/README.md-127-131 (1)
127-131:⚠️ Potential issue | 🟡 MinorClarify that external-link checks are configuration-dependent.
Line 130 currently reads as unconditional behavior, but validator behavior is configurable (and often skipped by default). Reword to indicate external HEAD validation runs when enabled in markdown-link-check settings / flags.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/validation/README.md` around lines 127 - 131, Update the third bullet in the "What it checks" list to clarify that external HEAD validation is conditional: change the line that currently states "External link targets are reachable via HTTP HEAD requests" to indicate this check runs only when enabled via markdown-link-check settings or CLI flags (or other validator configuration), e.g., mention "when enabled in markdown-link-check settings/flags" and keep the rest of the bullet structure intact so readers know the check is configuration-dependent.docs/patterns/security_patterns.md-1284-1285 (1)
1284-1285:⚠️ Potential issue | 🟡 MinorReplace the empty “As of” timestamp.
Line 1284 uses
As of ,and leaves the statement unfinished. Use a specific date (e.g.,As of 2026-04-24) or remove the phrase.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/patterns/security_patterns.md` around lines 1284 - 1285, Update the incomplete "As of ," phrase in the sentence that begins "As of , ONEX uses structured error models..." by replacing the empty timestamp with a concrete date (e.g., "As of 2026-04-24") or by removing the "As of" clause entirely so the sentence reads clearly; locate the string "As of ," in docs/patterns/security_patterns.md and make the change to the sentence starting "As of , ONEX uses structured error models for security validation failures."docs/architecture/EVENT_STREAMING_TOPICS.md-781-782 (1)
781-782:⚠️ Potential issue | 🟡 MinorRemove unfinished “implemented in )” placeholders.
Lines 781, 866, and 889 still contain incomplete parentheticals after ticket cleanup. Please replace with concrete release/date text or remove the parenthetical entirely.
Also applies to: 865-866, 889-890
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/architecture/EVENT_STREAMING_TOPICS.md` around lines 781 - 782, Search the doc for the unfinished parenthetical text "implemented in )" (e.g., in the sentence "Topic naming validation is available via contract-driven topic configuration (implemented in ).") and either remove the empty parenthesis or replace it with the concrete release/ticket/date text you intend to reference; also fix other similar incomplete parentheticals elsewhere in the document by replacing or removing them so no "(implemented in )" or equivalent empty placeholders remain.docs/architecture/CONFIG_DISCOVERY.md-7-7 (1)
7-7:⚠️ Potential issue | 🟡 MinorFix the incomplete attribution sentence.
Line 7 currently renders as broken text (
Introduced in (version 0.10.0).). Please remove the empty slot and keep a complete sentence.Suggested fix
-Introduced in (version 0.10.0). +Introduced in version 0.10.0.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/architecture/CONFIG_DISCOVERY.md` at line 7, The sentence "Introduced in (version 0.10.0)." is incomplete; remove the empty slot and rewrite it as a complete sentence (for example "Introduced in version 0.10.0.") so the line no longer renders broken text—update the text that currently reads 'Introduced in (version 0.10.0).' to a single coherent sentence.docs/runbooks/emergency-runtime-refresh.md-71-73 (1)
71-73:⚠️ Potential issue | 🟡 MinorFix dangling sentence after ticket-reference removal.
Line 72 currently ends with
report a regression against ., which is incomplete and ambiguous in an incident runbook.Suggested fix
-actually passed and report a regression against . +actually passed and report a regression through the internal runtime-refresh incident path.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/runbooks/emergency-runtime-refresh.md` around lines 71 - 73, The sentence ending with "report a regression against ." is incomplete; update the runbook line that mentions `--no-deps` to either reinsert the intended ticket/owner identifier or rephrase the instruction to be complete (e.g., "verify `--no-deps` was actually passed and, if not, file a regression ticket and notify the on-call team"). Locate the phrase "`--no-deps`" and the fragment "report a regression against ." and replace it with a complete actionable statement including the ticket reference or explicit next step.docs/architecture/HANDLER_PROTOCOL_DRIVEN_ARCHITECTURE.md-155-155 (1)
155-155:⚠️ Potential issue | 🟡 MinorClarify the enum package location with concrete import paths.
Lines 155 and 171 refer to "shared enum package imported by infra," which is vague. Specify the actual package path and import format:
EnumHandlerType:from omnibase_infra.enums import EnumHandlerType(defined insrc/omnibase_infra/enums/enum_handler_type.py)EnumHandlerTypeCategory:from omnibase_infra.enums import EnumHandlerTypeCategory(defined insrc/omnibase_infra/enums/enum_handler_type_category.py)This helps developers locate and import the enums correctly.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/architecture/HANDLER_PROTOCOL_DRIVEN_ARCHITECTURE.md` at line 155, Update the vague "shared enum package imported by infra" references to explicit import paths: replace mentions of EnumHandlerType with the import "from omnibase_infra.enums import EnumHandlerType" (enum defined in src/omnibase_infra/enums/enum_handler_type.py) and replace EnumHandlerTypeCategory with "from omnibase_infra.enums import EnumHandlerTypeCategory" (defined in src/omnibase_infra/enums/enum_handler_type_category.py), ensuring both concrete import examples appear where lines currently reference the shared enum package.
🧹 Nitpick comments (3)
docs/architecture/LLM_INFRASTRUCTURE.md (1)
7-7: Replace placeholder-stripped attribution with readable text (or remove it).After removing ticket IDs, this line is now semantically broken due to empty placeholders. Please rewrite it in neutral form or delete it.
✏️ Proposed doc fix
-Introduced across (transport), (inference handler), (embedding node), (token usage), (security layer). +Introduced across the transport layer, inference handler, embedding node, token usage, and security layer.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/architecture/LLM_INFRASTRUCTURE.md` at line 7, The sentence "Introduced across (transport), (inference handler), (embedding node), (token usage), (security layer)." contains empty placeholders after ticket removal—either replace the empty placeholders with readable component names or remove the entire sentence; update the text so it reads neutrally (for example: "Introduced across transport, inference handler, embedding node, token usage, and security layer.") or delete the line if it adds no value; ensure the edited phrase (the sentence starting "Introduced across") is the only change so surrounding content/formatting remains intact.docs/operations/THREAD_POOL_TUNING_RUNBOOK.md (1)
11-11: Fix incomplete migration note text at Line 11.The phrase
in .is malformed and leaves the migration reference unclear. Replace it with a complete neutral phrasing (without ticket IDs), e.g. “migrated from HashiCorp Vault (hvac) to Infisical.”✏️ Proposed doc fix
-> **Note**: The secret management backend migrated from HashiCorp Vault (hvac) to Infisical in . The Infisical SDK is async-native and does **not** require thread pool wrapping. The thread pool configuration documented below applies to legacy synchronous adapters only. +> **Note**: The secret management backend migrated from HashiCorp Vault (hvac) to Infisical. The Infisical SDK is async-native and does **not** require thread pool wrapping. The thread pool configuration documented below applies to legacy synchronous adapters only.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/operations/THREAD_POOL_TUNING_RUNBOOK.md` at line 11, Replace the malformed fragment "migrated from HashiCorp Vault (hvac) to Infisical in ." with a neutral, complete phrase such as "migrated from HashiCorp Vault (hvac) to Infisical." so the sentence reads: "The secret management backend migrated from HashiCorp Vault (hvac) to Infisical. The Infisical SDK is async-native and does not require thread pool wrapping..." — update the sentence containing the exact phrase "migrated from HashiCorp Vault (hvac) to Infisical in ." accordingly.docs/standards/STANDARD_DOC_LAYOUT.md (1)
119-121: Optional wording polish for consistency.Consider expanding “POC writeups” to “proof-of-concept writeups” for formal style consistency in standards docs.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/standards/STANDARD_DOC_LAYOUT.md` around lines 119 - 121, Replace the informal abbreviation "POC writeups" with the full phrase "proof-of-concept writeups" (optionally keeping "(POC writeups)" after it on first use for clarity) in the sentence that currently reads "Historical plans, stale analyses, point-in-time verification reports, and old POC writeups are removed from the primary docs tree." Ensure the wording is updated consistently in the same section where "If historical material contains current guidance, promote the current guidance" appears.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/decisions/adr-006-message-dispatch-engine-canonical-routing.md`:
- Around line 88-89: The ADR contains incomplete ticket-range placeholders
("through ." and "through") that break sentence meaning; update the two
occurrences (the phrase near `payload_schema_version`) and the block covering
lines 106–109 to use neutral wording such as "tracked internally" or "tracked
internally within the project" so sentences are complete and unambiguous,
keeping original sentence structure and tense and ensuring punctuation is
correct after replacement.
In `@README.md`:
- Around line 90-93: The README's REDUCER description incorrectly states that
REDUCER "emits intents"; update the table entry for REDUCER to match the
archetype contract (NodeArchetype.REDUCER) by describing it as
projection-focused/state-projection only (no intent emission) and align the
wording with the enum's definition to avoid architectural drift.
In `@tests/integration/test_omn_9600_path_defaults.py`:
- Around line 32-55: Replace the source-text inspection with a runtime check: in
test_local_stub_project_tracker_default_is_workspace_local instantiate
LocalStubProjectTracker (via __new__ + calling __init__ or just calling the
constructor) inside an isolated tmp_path working directory (use tmp_path and
chdir or monkeypatch.chdir) and assert the instance's _state_root is inside the
tmp_path workspace and ends with ".onex_state" and does not resolve to
Path.home(); reference LocalStubProjectTracker.__init__ and the _state_root
attribute to locate where to change the test.
---
Outside diff comments:
In `@docs/architecture/EVENT_STREAMING_TOPICS.md`:
- Line 982: Remove the empty "Related Tickets" section header from the document
— locate the heading string "## Related Tickets" in EVENT_STREAMING_TOPICS.md
(the header shown in the diff) and delete that line so there is no dead-end
section left in the file.
In `@docs/decisions/adr-any-type-pydantic-workaround.md`:
- Around line 950-954: The References section contains malformed bullet labels
like "- : ..." and "- **: ..." that appeared after ID redaction; update those
entries to use plain neutral labels (e.g., replace the empty/invalid label
prefix with a normal bullet "- " or plain sentence) so the lines read "-
Refactor RegistrationReducer to be fully declarative", "- Migration tracking
issue for Any type cleanup", "- Pre-existing test failures and integration test
coverage", and "** Migration completion - Any to JsonType (2026-01-08)**" (or
convert the last to a normal bullet) to remove the stray colon/asterisk tokens
and restore consistent bullet formatting in adr-any-type-pydantic-workaround.md.
In `@docs/patterns/secret_resolver.md`:
- Around line 664-687: The allowlist entries have had their ticket IDs removed
leaving blank reason prefixes like "# POSTGRES_HOST" which makes the format
ambiguous; update the entries in docs/patterns/secret_resolver.md so each line
follows the documented "filepath:line_number # ticket reason" format by adding
either the missing ticket IDs or a clear reason text for examples (e.g., replace
"# POSTGRES_HOST" with "# TICKET-XXXXX POSTGRES_HOST" or "# example:
POSTGRES_HOST"), and ensure the shown examples around the Event Bus and
Runtime/Nodes sections (files model_kafka_event_bus_config.py,
service_kernel.py, plugin.py) clearly demonstrate a copy/paste-ready allowlist
entry.
---
Minor comments:
In `@docs/architecture/CONFIG_DISCOVERY.md`:
- Line 7: The sentence "Introduced in (version 0.10.0)." is incomplete; remove
the empty slot and rewrite it as a complete sentence (for example "Introduced in
version 0.10.0.") so the line no longer renders broken text—update the text that
currently reads 'Introduced in (version 0.10.0).' to a single coherent
sentence.
In `@docs/architecture/EVENT_STREAMING_TOPICS.md`:
- Around line 781-782: Search the doc for the unfinished parenthetical text
"implemented in )" (e.g., in the sentence "Topic naming validation is available
via contract-driven topic configuration (implemented in ).") and either remove
the empty parenthesis or replace it with the concrete release/ticket/date text
you intend to reference; also fix other similar incomplete parentheticals
elsewhere in the document by replacing or removing them so no "(implemented in
)" or equivalent empty placeholders remain.
In `@docs/architecture/HANDLER_PROTOCOL_DRIVEN_ARCHITECTURE.md`:
- Line 155: Update the vague "shared enum package imported by infra" references
to explicit import paths: replace mentions of EnumHandlerType with the import
"from omnibase_infra.enums import EnumHandlerType" (enum defined in
src/omnibase_infra/enums/enum_handler_type.py) and replace
EnumHandlerTypeCategory with "from omnibase_infra.enums import
EnumHandlerTypeCategory" (defined in
src/omnibase_infra/enums/enum_handler_type_category.py), ensuring both concrete
import examples appear where lines currently reference the shared enum package.
In `@docs/architecture/MESSAGE_DISPATCH_ENGINE.md`:
- Line 472: The provenance text contains a dangling fragment "per )" in the line
that reads "Status: ENABLED (INFRA_PATTERNS_STRICT = True per )"; update the
MESSAGE_DISPATCH_ENGINE.md entry so that the parenthetical is either removed or
completed with a concrete reference (e.g., a date or version) — edit the line
containing INFRA_PATTERNS_STRICT and replace "per )" with a meaningful
provenance like "(INFRA_PATTERNS_STRICT = True as of YYYY-MM-DD)" or simply
remove the trailing "per )".
In `@docs/architecture/SNAPSHOT_PUBLISHING.md`:
- Around line 781-783: The three list lines contain empty bold markers around
the ticket labels (e.g., "** (F2)**: Snapshot Publishing (this feature)", "**
(F1)**: Implement Registration Projection Schema", "** (F0)**: Define Projector
Execution Model") which triggers MD037; remove the empty emphasis or replace it
with valid emphasis around the label itself. Locate these list entries in
SNAPSHOT_PUBLISHING.md and either change "** (F2)**:" to "(F2):" (and similarly
for F1/F0) or make the label bold correctly like "**F2**: Snapshot Publishing"
so there are no spaces inside emphasis markers.
In `@docs/decisions/adr-002-enum-message-category-node-output-separation.md`:
- Line 338: Edit the ADR text containing the dangling ticket placeholder by
locating the line that reads "**Ticket**: - Resolve EnumMessageCategory drift
between core and infra" and remove the stray hyphen/extra punctuation so it
becomes a clean sentence (e.g., "**Ticket**: Resolve EnumMessageCategory drift
between core and infra") or entirely remove the empty ticket field if not
needed; update the surrounding prose to ensure no leftover stray punctuation
remains.
In `@docs/decisions/adr-004-performance-baseline-thresholds.md`:
- Line 24: Replace the two redacted/unfinished noun phrases in the ADR with
neutral, complete wording: change the fragment "The original requirements" to
"The original requirements" (or "original requirements") and change the other
redacted phrase to "linked to internal tracking and calibration date" (or
similar neutral wording) so both occurrences read as complete, traceable
statements and maintain consistent phrasing across the document (ensure the same
replacement is applied at both locations mentioned).
In `@docs/decisions/adr-canonical-publish-interface-policy.md`:
- Around line 269-270: The metadata lines labeled "Parent Ticket" and "This
Ticket" contain empty placeholders and should be fixed; update the "**Parent
Ticket**: - Publish Interface Consolidation" and "**This Ticket**: - Write ADR
for Canonical Publish Interface Policy" entries to include the actual ticket
identifiers or URLs (e.g., JIRA/issue IDs) or remove the placeholder entries
entirely so the front-matter reads as valid metadata without empty fields;
ensure the labels remain exactly "Parent Ticket" and "This Ticket" to match the
ADR convention.
In `@docs/decisions/adr-error-context-factory-pattern.md`:
- Line 7: Replace the dangling ticket placeholders by changing the header
"**Follow-up Tickets**: (validator), (migration)" to a ticket-neutral heading
(e.g., "**Follow-up Items**:") and enumerate concrete items, and replace the
incomplete reference "once is implemented" with an explicit validator name
(e.g., "once the <ValidatorName> validator is implemented") so the ADR contains
complete, unambiguous prose; update the two occurrences referenced (the heading
near the top and the sentence at the bottom) accordingly.
In `@docs/decisions/adr-projector-composite-key-upsert-workaround.md`:
- Line 204: Replace the malformed blank reference prefix in the markdown entry
"- : Convert ProjectorRegistration to declarative contract" by adding a neutral
non-ticket label (e.g., "Note", "Misc", or "Info") so the line becomes "Note:
Convert ProjectorRegistration to declarative contract"; edit the line containing
"ProjectorRegistration" to only change the prefix and avoid inserting any ticket
IDs or extra markup.
In `@docs/decisions/adr-two-handler-systems.md`:
- Around line 12-18: The two sentences in the ADR context are missing subjects:
replace "During research (2026-02-06)" with a neutral phrase like "During
internal research (2026-02-06)" and replace "caused to be planned" with a
neutral phrase like "caused this work to be planned" so the paragraph reads
clearly and neutrally; update the occurrences in the ADR content (the phrases
"During research (2026-02-06)" and "caused to be planned") accordingly.
- Around line 227-228: Remove or fix the two malformed reference bullets that
read "- : Research that discovered this architectural gap" and "- : Parent epic
with architecture findings" by either deleting those empty/reference-only list
items or replacing the colon placeholders with a valid, non-sensitive label
(e.g., "- Research: ..." or "- Parent epic: ...") so they render correctly;
update the markdown in the ADR document accordingly.
In `@docs/guides/MCP_INTEGRATION_GUIDE.md`:
- Line 102: The sentence describing ONEXToMCPAdapter's role ends with a dangling
fragment "is planned under )." — revise the sentence to be complete and clear by
removing the stray parenthesis and finishing the thought; for example, state
that automatic discovery based on the contract flag mcp_enabled: true is planned
(or specify the planned mechanism), so the line mentioning ONEXToMCPAdapter,
MCPToolDefinition, and the mcp_enabled flag reads as a complete sentence without
stray punctuation.
In `@docs/operations/DATABASE_INDEX_MONITORING_RUNBOOK.md`:
- Line 12: The file contains an empty metadata placeholder "**Related Ticket**:"
on the documented runbook; remove that line or replace it with a meaningful
label like "**Related Context**" and accompanying text so the metadata is not
left blank—update the string "**Related Ticket**:" in the document accordingly.
In `@docs/patterns/retry_backoff_compensation_strategy.md`:
- Line 45: The sentence containing "The `retries` field was intentionally
removed from effect result models (see )" has a broken citation; either remove
the empty parenthetical or replace it with a valid internal doc link/reference.
Edit the sentence in the retry_backoff_compensation_strategy.md content that
mentions the `retries` field and either delete " (see )" entirely or substitute
a concrete reference/URL to the relevant internal doc that explains the removal.
In `@docs/patterns/secret_resolver.md`:
- Line 693: Update the rule that currently reads "Include ticket reference
(e.g., ``) and variable name as the reason" so it no longer asks for ticket
numbers; instead require a non-ticket rationale plus the variable name as the
reason (e.g., a brief description like "security cleanup" or "rotate expired
key" and the env var name). Locate the exact phrase in the docs (the sentence
beginning "Include ticket reference (e.g.," in secret_resolver.md) and replace
it with wording that forbids ticket-number references and instructs contributors
to supply a concise, non-ticket rationale plus the variable name.
In `@docs/patterns/security_patterns.md`:
- Around line 630-631: Remove the dangling parenthetical "migrated from
HashiCorp Vault in )" in the docs/patterns/security_patterns.md text and either
delete the entire parenthetical or replace it with a concrete migration
date/version (e.g., "migrated from HashiCorp Vault in 2024") so the sentence
reads cleanly; look for the exact snippet "migrated from HashiCorp Vault in )"
to locate the spot.
- Around line 1284-1285: Update the incomplete "As of ," phrase in the sentence
that begins "As of , ONEX uses structured error models..." by replacing the
empty timestamp with a concrete date (e.g., "As of 2026-04-24") or by removing
the "As of" clause entirely so the sentence reads clearly; locate the string "As
of ," in docs/patterns/security_patterns.md and make the change to the sentence
starting "As of , ONEX uses structured error models for security validation
failures."
In `@docs/runbooks/apply-migrations.md`:
- Around line 294-295: Edit the incomplete sentence "This tool (added in )
ensures no migrations are missing from either the filesystem or the database."
and remove the empty parenthetical or replace it with a concrete marker (e.g., a
date or release name) so the sentence reads grammatically correct—either "This
tool ensures no migrations are missing from either the filesystem or the
database." or "This tool (added in vX.Y or YYYY-MM) ensures no migrations are
missing from either the filesystem or the database."
In `@docs/runbooks/emergency-runtime-refresh.md`:
- Around line 71-73: The sentence ending with "report a regression against ." is
incomplete; update the runbook line that mentions `--no-deps` to either reinsert
the intended ticket/owner identifier or rephrase the instruction to be complete
(e.g., "verify `--no-deps` was actually passed and, if not, file a regression
ticket and notify the on-call team"). Locate the phrase "`--no-deps`" and the
fragment "report a regression against ." and replace it with a complete
actionable statement including the ticket reference or explicit next step.
In `@docs/standards/TOPIC_TAXONOMY.md`:
- Line 5: The document contains orphaned sentence fragments where references
were removed (e.g., the phrases "introduced in ,", " changed…", and "as of ")
which break sentence flow; update TOPIC_TAXONOMY.md by replacing those fragments
with neutral, complete phrasing such as "introduced in a recent change", "was
changed", or "as of the latest update" (or another concise date/version neutral
wording) so the sentences at the locations containing "introduced in ,", "
changed…", and "as of " read grammatically complete without external
identifiers.
In `@docs/validation/README.md`:
- Around line 127-131: Update the third bullet in the "What it checks" list to
clarify that external HEAD validation is conditional: change the line that
currently states "External link targets are reachable via HTTP HEAD requests" to
indicate this check runs only when enabled via markdown-link-check settings or
CLI flags (or other validator configuration), e.g., mention "when enabled in
markdown-link-check settings/flags" and keep the rest of the bullet structure
intact so readers know the check is configuration-dependent.
---
Nitpick comments:
In `@docs/architecture/LLM_INFRASTRUCTURE.md`:
- Line 7: The sentence "Introduced across (transport), (inference handler),
(embedding node), (token usage), (security layer)." contains empty
placeholders after ticket removal—either replace the empty placeholders with
readable component names or remove the entire sentence; update the text so it
reads neutrally (for example: "Introduced across transport, inference handler,
embedding node, token usage, and security layer.") or delete the line if it adds
no value; ensure the edited phrase (the sentence starting "Introduced across")
is the only change so surrounding content/formatting remains intact.
In `@docs/operations/THREAD_POOL_TUNING_RUNBOOK.md`:
- Line 11: Replace the malformed fragment "migrated from HashiCorp Vault (hvac)
to Infisical in ." with a neutral, complete phrase such as "migrated from
HashiCorp Vault (hvac) to Infisical." so the sentence reads: "The secret
management backend migrated from HashiCorp Vault (hvac) to Infisical. The
Infisical SDK is async-native and does not require thread pool wrapping..." —
update the sentence containing the exact phrase "migrated from HashiCorp Vault
(hvac) to Infisical in ." accordingly.
In `@docs/standards/STANDARD_DOC_LAYOUT.md`:
- Around line 119-121: Replace the informal abbreviation "POC writeups" with the
full phrase "proof-of-concept writeups" (optionally keeping "(POC writeups)"
after it on first use for clarity) in the sentence that currently reads
"Historical plans, stale analyses, point-in-time verification reports, and old
POC writeups are removed from the primary docs tree." Ensure the wording is
updated consistently in the same section where "If historical material contains
current guidance, promote the current guidance" appears.
🪄 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: defaults
Review profile: CHILL
Plan: Pro
Run ID: a8b63b5f-7595-4d81-ba5e-45fb98eec342
📒 Files selected for processing (85)
CLAUDE.mdREADME.mdcontracts/OMN-9600.yamldocs/architecture/CONFIG_DISCOVERY.mddocs/architecture/EVENT_BUS_INTEGRATION_GUIDE.mddocs/architecture/EVENT_STREAMING_TOPICS.mddocs/architecture/HANDLER_CLASSIFICATION_3_2A_CIRCUIT_BREAKER_RETRY.mddocs/architecture/HANDLER_CLASSIFICATION_3_3_LLM_HTTP_TRANSPORT.mddocs/architecture/HANDLER_CLASSIFICATION_POC_3_1.mddocs/architecture/HANDLER_CLASSIFICATION_POC_3_2B.mddocs/architecture/HANDLER_CLASSIFICATION_RULES.mddocs/architecture/HANDLER_PROTOCOL_DRIVEN_ARCHITECTURE.mddocs/architecture/LLM_INFRASTRUCTURE.mddocs/architecture/MCP_SERVICE_ARCHITECTURE.mddocs/architecture/MESSAGE_DISPATCH_ENGINE.mddocs/architecture/README.mddocs/architecture/REGISTRATION_WORKFLOW.mddocs/architecture/SNAPSHOT_PUBLISHING.mddocs/architecture/TOPIC_CATALOG_ARCHITECTURE.mddocs/decisions/adr-001-graceful-shutdown-drain-period.mddocs/decisions/adr-002-enum-message-category-node-output-separation.mddocs/decisions/adr-003-remove-handler-health-checks.mddocs/decisions/adr-004-performance-baseline-thresholds.mddocs/decisions/adr-005-denormalize-capability-fields-in-registration-projections.mddocs/decisions/adr-006-message-dispatch-engine-canonical-routing.mddocs/decisions/adr-007-vault-to-infisical-migration.mddocs/decisions/adr-008-realm-agnostic-topics.mddocs/decisions/adr-009-llm-cost-tracking-spi.mddocs/decisions/adr-any-type-pydantic-workaround.mddocs/decisions/adr-canonical-publish-interface-policy.mddocs/decisions/adr-consumer-group-naming.mddocs/decisions/adr-custom-bool-result-models.mddocs/decisions/adr-enum-message-category-vs-node-output-type.mddocs/decisions/adr-error-context-factory-pattern.mddocs/decisions/adr-handler-contract-schema-evolution.mddocs/decisions/adr-handler-plugin-loader-security.mddocs/decisions/adr-handler-type-vs-handler-category.mddocs/decisions/adr-kafka-required-infrastructure.mddocs/decisions/adr-projector-composite-key-upsert-workaround.mddocs/decisions/adr-protocol-design-guidelines.mddocs/decisions/adr-soft-validation-env-parsing.mddocs/decisions/adr-two-handler-systems.mddocs/event-bus/schema-handshake.mddocs/guides/INFISICAL_SECRETS_GUIDE.mddocs/guides/MCP_INTEGRATION_GUIDE.mddocs/handoff/2026-02-23-omn-2287-phase2-review.mddocs/index.mddocs/investigations/2026-04-21-registration-shared-topic-consumer-collapse.mddocs/investigations/OMN-3988-non-node-dirs-under-nodes.mddocs/migration/MIGRATION_WIRE_DEFAULT_HANDLERS.mddocs/operations/CI_BASELINE_OMNIBASE_INFRA.mddocs/operations/DATABASE_INDEX_MONITORING_RUNBOOK.mddocs/operations/DLQ_REPLAY_RUNBOOK.mddocs/operations/INFISICAL_SEED_VERIFICATION_OMN3898.mddocs/operations/README.mddocs/operations/THREAD_POOL_TUNING_RUNBOOK.mddocs/patterns/ENVIRONMENT_TOPICS.mddocs/patterns/db_url_contract.mddocs/patterns/effect_boundary_testing.mddocs/patterns/headless_decomposition.mddocs/patterns/mixin_dependencies.mddocs/patterns/operation_bindings.mddocs/patterns/policy_registry_trust_model.mddocs/patterns/retry_backoff_compensation_strategy.mddocs/patterns/secret_resolver.mddocs/patterns/security_patterns.mddocs/plugins/PLUGIN_DETERMINISM.mddocs/plugins/README.mddocs/plugins/json_normalizer_optimization.mddocs/runbooks/apply-migrations.mddocs/runbooks/emergency-runtime-refresh.mddocs/standards/ONEX_TERMINOLOGY.mddocs/standards/STANDARD_DOC_LAYOUT.mddocs/standards/TOPIC_TAXONOMY.mddocs/testing/INTEGRATION_TESTING.mddocs/validation/EVENT_BUS_COVERAGE_REPORT.mddocs/validation/README.mddocs/validation/circular_import_validator_improvements.mddocs/validation/framework_integration.mddocs/validation/troubleshooting.mddocs/validation/validator_reference.mddocs/verification/omn-5656-e2e-error-triage-verification.mdsrc/omnibase_infra/adapters/project_tracker/local_stub_project_tracker.pysrc/omnibase_infra/services/agent_registry/registry.pytests/integration/test_omn_9600_path_defaults.py
💤 Files with no reviewable changes (29)
- docs/decisions/adr-protocol-design-guidelines.md
- docs/decisions/adr-enum-message-category-vs-node-output-type.md
- docs/decisions/adr-handler-type-vs-handler-category.md
- docs/decisions/adr-kafka-required-infrastructure.md
- docs/decisions/adr-custom-bool-result-models.md
- docs/decisions/adr-handler-plugin-loader-security.md
- docs/architecture/EVENT_BUS_INTEGRATION_GUIDE.md
- docs/decisions/adr-handler-contract-schema-evolution.md
- docs/migration/MIGRATION_WIRE_DEFAULT_HANDLERS.md
- docs/decisions/adr-005-denormalize-capability-fields-in-registration-projections.md
- docs/decisions/adr-001-graceful-shutdown-drain-period.md
- docs/decisions/adr-soft-validation-env-parsing.md
- docs/decisions/adr-consumer-group-naming.md
- docs/patterns/headless_decomposition.md
- docs/operations/DLQ_REPLAY_RUNBOOK.md
- docs/architecture/HANDLER_CLASSIFICATION_RULES.md
- docs/operations/CI_BASELINE_OMNIBASE_INFRA.md
- docs/operations/INFISICAL_SEED_VERIFICATION_OMN3898.md
- docs/handoff/2026-02-23-omn-2287-phase2-review.md
- docs/architecture/HANDLER_CLASSIFICATION_POC_3_2B.md
- docs/validation/EVENT_BUS_COVERAGE_REPORT.md
- docs/validation/circular_import_validator_improvements.md
- docs/investigations/OMN-3988-non-node-dirs-under-nodes.md
- docs/plugins/json_normalizer_optimization.md
- docs/investigations/2026-04-21-registration-shared-topic-consumer-collapse.md
- docs/architecture/HANDLER_CLASSIFICATION_3_2A_CIRCUIT_BREAKER_RETRY.md
- docs/architecture/HANDLER_CLASSIFICATION_POC_3_1.md
- docs/architecture/HANDLER_CLASSIFICATION_3_3_LLM_HTTP_TRANSPORT.md
- docs/verification/omn-5656-e2e-error-triage-verification.md
✅ Files skipped from review due to trivial changes (21)
- docs/patterns/ENVIRONMENT_TOPICS.md
- docs/patterns/operation_bindings.md
- docs/event-bus/schema-handshake.md
- docs/patterns/mixin_dependencies.md
- docs/patterns/db_url_contract.md
- docs/plugins/README.md
- docs/patterns/policy_registry_trust_model.md
- docs/validation/troubleshooting.md
- docs/standards/ONEX_TERMINOLOGY.md
- docs/testing/INTEGRATION_TESTING.md
- docs/validation/framework_integration.md
- docs/decisions/adr-008-realm-agnostic-topics.md
- docs/architecture/TOPIC_CATALOG_ARCHITECTURE.md
- docs/decisions/adr-003-remove-handler-health-checks.md
- docs/decisions/adr-009-llm-cost-tracking-spi.md
- docs/patterns/effect_boundary_testing.md
- docs/operations/README.md
- docs/architecture/MCP_SERVICE_ARCHITECTURE.md
- docs/decisions/adr-007-vault-to-infisical-migration.md
- docs/architecture/REGISTRATION_WORKFLOW.md
- docs/validation/validator_reference.md
🚧 Files skipped from review as they are similar to previous changes (2)
- docs/plugins/PLUGIN_DETERMINISM.md
- CLAUDE.md
jonahgabriel
disabled auto-merge
April 24, 2026 22:01
jonahgabriel
enabled auto-merge
April 24, 2026 22:02
jonahgabriel
added this pull request to the merge queue
Apr 24, 2026
jonahgabriel
added a commit
that referenced
this pull request
Jul 8, 2026
…dev SHA The 43 workflow callers pinned the occ-preflight reusable (and its core-ref input) to 7975803283 — a commit on the omnibase_core OMN-14104 PR branch (#1396, 'ci: use dev for OCC preflight compat checkout'). That PR squash-merged to omnibase_core dev (8a47e092), deleting the branch and ORPHANING 7975803283. GitHub Actions can no longer resolve the reusable at an unreachable SHA, so every caller on this branch hit startup_failure ('workflow file issue', zero jobs) — all 43 workflows red. Re-pin all 86 references (43 uses:@ + 43 core-ref) to 8a47e092002dd1338599fa0733feda469436acbf, the merged commit that last defined occ-preflight.yml on omnibase_core dev (ancestor of dev HEAD, reachable). Input interface is identical (contracts-dir/receipts-dir/core-ref, all optional) — verified against both SHAs. Also rebased onto origin/dev to pick up the 4 missing commits (incl. OMN-14130 core 0.46.5 bump for the grandfather validator).
jonahgabriel
added a commit
that referenced
this pull request
Jul 8, 2026
…dev SHA The 43 workflow callers pinned the occ-preflight reusable (and its core-ref input) to 7975803283 — a commit on the omnibase_core OMN-14104 PR branch (#1396, 'ci: use dev for OCC preflight compat checkout'). That PR squash-merged to omnibase_core dev (8a47e092), deleting the branch and ORPHANING 7975803283. GitHub Actions can no longer resolve the reusable at an unreachable SHA, so every caller on this branch hit startup_failure ('workflow file issue', zero jobs) — all 43 workflows red. Re-pin all 86 references (43 uses:@ + 43 core-ref) to 8a47e092002dd1338599fa0733feda469436acbf, the merged commit that last defined occ-preflight.yml on omnibase_core dev (ancestor of dev HEAD, reachable). Input interface is identical (contracts-dir/receipts-dir/core-ref, all optional) — verified against both SHAs. Also rebased onto origin/dev to pick up the 4 missing commits (incl. OMN-14130 core 0.46.5 bump for the grandfather validator).
11 tasks done
jonahgabriel
added a commit
that referenced
this pull request
Jul 8, 2026
* ci(OMN-14104): gate all PR workflows on OCC preflight * ci(OMN-14104): re-arm OCC preflight after evidence merge * ci(OMN-14104): target core dev for OCC preflight callers * ci(OMN-14104): pin infra OCC preflight reusable workflow * ci(OMN-14104): pin infra OCC preflight to workflow-sha fix * ci(OMN-14104): correct OCC preflight workflow pin * ci(OMN-14104): use working OCC preflight core pin * ci(OMN-14104): pin OCC preflight to dev-validator workflow * ci(OMN-14104): pin OCC preflight to isolated wheel build * ci(OMN-14104): pass explicit OCC preflight core ref * ci(OMN-14104): pin infra OCC preflight to compat-dev core fix * ci(OMN-14104): fail CI Summary explicitly when OCC preflight is red CodeRabbit flagged that gating the required CI Summary aggregate with `if: needs.occ-preflight.result == 'success' && (always())` turns a RED occ-preflight into a SKIPPED CI Summary. A skipped required branch-protection check reports as success, so a failed OCC preflight could be merged. Keep `if: always()` and enforce OCC eligibility as the first step, failing explicitly when preflight did not succeed so the required check stays RED. CI Summary is the single umbrella required gate (OMN-4497, .github/required-checks.yaml), so a red CI Summary blocks the merge even though the runner-heavy fanout is (intentionally) skipped on preflight failure. * ci(OMN-14104): re-trigger CI after transient startup_failure batch The 06:58Z run batch on the prior push hit a transient GitHub Actions startup_failure across all workflows (zero jobs, name==path, no diff cause — untouched workflows failed too). Infra recovered by 07:01Z (sibling branch runs queuing/running normally). startup_failure runs are non-retriable, so this empty commit re-triggers a fresh CI cycle. No code change. * ci(OMN-14104): re-pin occ-preflight reusable to merged omnibase_core dev SHA The 43 workflow callers pinned the occ-preflight reusable (and its core-ref input) to 7975803283 — a commit on the omnibase_core OMN-14104 PR branch (#1396, 'ci: use dev for OCC preflight compat checkout'). That PR squash-merged to omnibase_core dev (8a47e092), deleting the branch and ORPHANING 7975803283. GitHub Actions can no longer resolve the reusable at an unreachable SHA, so every caller on this branch hit startup_failure ('workflow file issue', zero jobs) — all 43 workflows red. Re-pin all 86 references (43 uses:@ + 43 core-ref) to 8a47e092002dd1338599fa0733feda469436acbf, the merged commit that last defined occ-preflight.yml on omnibase_core dev (ancestor of dev HEAD, reachable). Input interface is identical (contracts-dir/receipts-dir/core-ref, all optional) — verified against both SHAs. Also rebased onto origin/dev to pick up the 4 missing commits (incl. OMN-14130 core 0.46.5 bump for the grandfather validator). * ci(OMN-14104): refresh dispatch parity fixture * ci(OMN-14104): restore routed dispatch parity fixture * ci(OMN-14104): refresh parity fixture metadata * ci(OMN-14104): allow reusable occ preflight in webhook tests * ci(OMN-14104): run plugin lifecycle guard in uv env
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Closes OMN-9600.
README.md,CLAUDE.md, anddocs/**/*.md.onex_change_control, not in this repository..onex_statedefaults inAgentRegistryandLocalStubProjectTracker(removesPath.home()anchoring per OMN-9600 CodeRabbit finding).Validation
find docs -type d -empty -printreturned no empty docs directories.rgscan overREADME.md,CLAUDE.md, anddocs/**/*.mdfound no ticket IDs, Linear links, transition-file references, or private workspace links.uv run python scripts/validation/validate_markdown_links.pypassed: 135 files, 980 links checked, 20 skipped.uv run python scripts/validate.py markdown_linkspassed: 135 files, 980 links checked.tests/integration/test_omn_9600_path_defaults.pyall pass, provingPath.home()was removed from both class defaults.Notes
contracts/OMN-9600.yamladded as deploy-gate carrier withdod_evidenceincludingdocker execcheck.Summary by CodeRabbit
New Features
Bug Fixes
.onex_stateDocumentation
Tests