Repository navigation
docs: comprehensive documentation rewrite with navigation and structure - #405
Conversation
- Add docs/index.md as central navigation hub with "How to Use" guide - Add docs/reference/node-archetypes.md covering all 4 node types - Add docs/reference/contracts.md with complete contract.yaml reference - Consolidate ADRs: create docs/decisions/ with categorized index - Add breadcrumb navigation to 180+ documentation files - Add CLAUDE.md authority notes to key documentation files - Add .markdown-link-check.json for link validation - Update .pre-commit-config.yaml with markdown link validation hook - Add docs/patterns/README.md as patterns section index - Add docs/guides/README.md as guides section index - Fix broken links in consolidated ADR files - Fix validation script to handle external paths and code blocks Aligns with omnibase_infra documentation patterns (PR #172)
📝 WalkthroughWalkthroughAdds markdown link-check configuration and a pre-commit hook plus improvements to the markdown validation script; concurrently applies navigation breadcrumb and other header additions across ~200 documentation files and introduces many ADRs and new reference docs (contracts, node-archetypes, guides, patterns). Changes
Sequence Diagram(s)sequenceDiagram
participant Dev as Developer (git commit)
participant Pre as Pre-commit hook
participant Script as validate_markdown_links.py
participant FS as Repository files
Dev->>Pre: commit / pre-commit triggers
Pre->>Script: run markdown validation (pass_filenames: false)
Script->>FS: read markdown files (excludeFiles applied)
Script->>Script: strip code blocks & extract links
Script->>FS: resolve local file links (validate_file_link)
Script->>Pre: return findings (errors/warnings)
Pre->>Dev: block or allow commit based on result
Estimated code review effort🎯 4 (Complex) | ⏱️ ~60 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. Comment |
PR Review: Documentation RewriteThis is an excellent documentation overhaul that significantly improves navigation and developer experience. The work aligns well with ONEX standards and the omnibase_infra patterns (PR #172). ✅ Strengths
🔍 Issues & RecommendationsCritical: Missing lowercase index.mdIssue: PR description mentions "Add docs/index.md" but only Evidence: # From breadcrumbs:
> **Navigation**: [Home](../index.md) > Decisions > ADR-001
# But file is:
docs/INDEX.md # uppercaseFix Required: Either:
Recommendation: Use lowercase Minor: Pre-commit Hook PlacementIssue: The new Impact: Could add latency to commits when only a few files changed. Recommendation: Consider moving to From CLAUDE.md: # Existing pattern:
- id: validate-doc-links
stages: [pre-push] # Scans all files but only on pushMinor: Breadcrumb ConsistencyGood: Breadcrumbs are consistent within sections. Observation: Some use
Suggestion: ADR DuplicationObservation: ADRs exist in both locations:
Question: Are these intentionally different, or is this consolidation still in progress? The PR description says "Consolidate ADRs" but both directories exist. Recommendation: Document the intended structure in 📊 Metrics
🧪 Test CoverageTest Plan Items (from PR description):
🔐 Security Considerations
🎯 Recommendations Summary
✨ VerdictApprove with one critical fix: The lowercase The new structure significantly improves:
Recommendation: Merge after fixing the index.md casing issue. Reviewed by: Claude Sonnet 4.5 |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 14
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 (11)
docs/architecture/decisions/RISK-009-ci-workflow-modification-risk.md (1)
24-31: Update protected branch names to match actual workflow configurationThe documentation incorrectly states the protected branches are
main/master, but the actual workflow at.github/workflows/test.ymlusesmainanddevelop(lines 5-7, 369-370, 380). Update lines 14, 25, and 31 to referencemain/developinstead.The CODEOWNERS path
/.github/workflows/is correctly specified and verified in the CODEOWNERS file.docs/guides/node-building/07_PATTERNS_CATALOG.md (6)
819-856: ORCHESTRATORprocessshould returnNoneper standards.The orchestrator example returns a dict, but CLAUDE.md states ORCHESTRATOR nodes must return
None. Update the example to returnNoneand move results into side-effects/state if needed. Based on learnings, ...
583-671: Missingimport timein reducer example.
time.time()is used in_execute_transition, buttimeisn’t imported in this block, so the example won’t run as written.💡 Minimal fix
from typing import Dict, Any, List from enum import Enum +import time
1011-1066: Missingimport timein caching mixin example.
time.time()is used in_is_cache_validand_put_to_cachebuttimeisn’t imported in this block.💡 Minimal fix
import hashlib import json +import time
465-564: CircuitBreaker referenced without import in API integration example.
CircuitBreakeris used but not imported in this snippet; readers will hit a NameError. Add the import at the top of the block.💡 Minimal fix
import aiohttp import asyncio +from omnibase_core.utils.circuit_breaker import CircuitBreaker
1365-1389: Async generator return type annotation is misleading.The method is declared to return
Dict[str, Any], but because it usesyield, it's an async generator. Callers will receive an async generator object, not the returned dict. Either remove thereturnstatement and use a sentinel/final item approach, or restructure the API to not useyield(e.g., accumulate results and return the complete dict).
1243-1249: Invalid Python syntax inretry_with_backoffcall: positional argument after keyword arguments.The example code has
input_dataas a positional argument following keyword arguments (correlation_id=...), which violates Python's syntax rules and will raise a SyntaxError. Passinput_dataas a keyword argument instead.💡 Minimal fix
- return await retry_with_backoff( - func=self._actual_process, - config=self.retry_config, - correlation_id=input_data.get("correlation_id"), - input_data - ) + return await retry_with_backoff( + func=self._actual_process, + config=self.retry_config, + correlation_id=input_data.get("correlation_id"), + input_data=input_data + )docs/guides/PRODUCTION_CACHE_TUNING.md (2)
22-35: Unclosed fenced code block.The code block starting at line 23 is missing its closing fence. This affects rendering of the subsequent content.
Suggested fix
Cache memory usage follows this approximate formula:Total Memory (MB) = (max_size × avg_entry_size_kb) / 1024
+```Default Entry Size: ~1KB per cached computation (varies by computation complexity)
</details> --- `40-73`: **Another unclosed code block.** The Python code block starting at line 40 (implied by the import statement) lacks opening and closing fences, and the block starting conceptually continues without proper closure before the next section. <details> <summary>Suggested fix</summary> Add proper code block fences around the Python examples: ```diff ### Example Configurations +```python from omnibase_core.models.configuration.model_compute_cache_config import ModelComputeCacheConfig ... ) +``` ---docs/decisions/ADR-001-protocol-based-di-architecture.md (1)
1-673: Incomplete ADR consolidation: establish canonical location and update references.ADR-001 exists in two locations with intentionally adjusted navigation paths for their respective directories, indicating an incomplete consolidation from
docs/architecture/decisions/(old location) todocs/decisions/(new location). However, this creates a maintenance burden:
- codebase references point only to old location: All references in
TEST_COUNT_CLARIFICATION_SUMMARY.md,TERMINOLOGY_FIXES_CHECKLIST.md, andTERMINOLOGY_AUDIT_REPORT.mdreferencedocs/architecture/decisions/ADR-001- no references to new location: No documentation or code references the new
docs/decisions/path- split maintenance: Both versions are being maintained separately with only navigation path differences, risking future divergence
- no deprecation guidance: The old location lacks any redirect, deprecation notice, or migration guidance pointing users to the canonical location
To complete the consolidation:
- Establish
docs/decisions/as the canonical ADR location (appears to be the intent, given it contains all 9 ADRs vs 6 in the old location)- Either remove the
docs/architecture/decisions/copies or add clear deprecation notices with redirects- Update all codebase references to point to
docs/decisions/instead ofdocs/architecture/decisions/- Document this consolidation in both README files
docs/architecture/MISSING_MIXINS_ANALYSIS.md (1)
27-33: Fix invalid markdown code fence closures.The blocks opened with
python are closed withpython (e.g., Line 27–33). Closing fences must be ``` or the block won’t render correctly. This appears in multiple blocks in this file.✅ Suggested fix
-```python +```
🤖 Fix all issues with AI agents
In `@docs/architecture/decisions/INDEX.md`:
- Around line 1-2: Update the breadcrumb link in the Navigation line by
replacing the lowercase path "../../index.md" with the correct cased
"../../INDEX.md" so the link points to the actual file; locate the breadcrumb
string in docs/architecture/decisions/INDEX.md (the line containing
"**Navigation**: [Home](../../index.md) ...") and change the target to
"../../INDEX.md" while leaving the rest of the breadcrumb (including
"../overview.md") unchanged.
In `@docs/architecture/DECLARATIVE_WORKFLOW_FINDINGS.md`:
- Around line 1-2: The breadcrumb in DECLARATIVE_WORKFLOW_FINDINGS.md points to
a non-existent ../index.md; update the Home link to reference the existing
docs/INDEX.md (replace '../index.md' with '../INDEX.md') or alternatively create
a docs/index.md file; ensure the updated link preserves the existing breadcrumb
structure that also references './overview.md'.
In `@docs/architecture/DICT_STR_ANY_PREVENTION.md`:
- Around line 1-2: Update the breadcrumb "Home" link in the architecture
markdown files: replace any occurrence of "[Home](../index.md)" with
"[Home](../INDEX.md)" in top-level architecture docs (e.g., the breadcrumb line
containing "Navigation: [Home](../index.md) > [Architecture](./overview.md) >
..."), and for nested subdirectory files replace "[Home](../../index.md)" with
"[Home](../../INDEX.md)"; ensure you update all similar breadcrumb strings
across files in the architecture directory so the Home link points to the
correct uppercase INDEX.md.
In `@docs/architecture/EFFECT_TIMEOUT_BEHAVIOR.md`:
- Around line 1-2: The breadcrumb in EFFECT_TIMEOUT_BEHAVIOR.md uses the broken
link string "../index.md"; update that link to the actual repository home page
path (for example the correct relative path to the site root or main docs
landing file) or alternatively add a docs/index.md file if the intent was to
have a docs landing page; locate the breadcrumb line containing "../index.md"
and either replace "../index.md" with the correct path to the home page or
create the missing docs/index.md to restore the link.
In `@docs/architecture/MIXINS_TO_HANDLERS_REFACTOR.md`:
- Around line 1-2: The breadcrumb in MIXINS_TO_HANDLERS_REFACTOR.md references a
nonexistent docs/index.md (Home link); either add a new docs/index.md file or
update the Home link in MIXINS_TO_HANDLERS_REFACTOR.md to point to an existing
document (for example the repo's top-level README or existing docs landing page)
so the breadcrumb resolves correctly; locate the breadcrumb line starting with
"**Navigation**: [Home](../index.md)" and replace the target or create the
missing index file accordingly.
In `@docs/decisions/ADR_BEST_PRACTICES.md`:
- Around line 243-257: Update the ADR reference in the ADR_BEST_PRACTICES.md
example list: replace the mislabeled "ADR-002: Context Mutability Design
Decision" entry with the correct ADR number ("ADR-007") or swap ADR-002 for an
ADR whose title actually is "Centralized Field Limit Constants"; ensure the list
items for ADR-002/ADR-007 reflect the correct titles and descriptions so the
bullet for "Context Mutability" points to ADR-007 (or the accurate ADR) and the
"Centralized Field Limit Constants" title remains associated with ADR-002 as
appropriate.
In `@docs/guides/EFFECT_SUBCONTRACT_GUIDE.md`:
- Around line 1-2: The breadcrumb link is pointing to a non-existent
../index.md; update the breadcrumb line in EFFECT_SUBCONTRACT_GUIDE (the line
starting with "> **Navigation**: [Home](../index.md) > Guides > ...") to use the
existing guides index by replacing it with "> **Navigation**:
[Guides](README.md) > Effect Subcontract Guide" and apply the same replacement
for other guide files that reference "../index.md" so all guide breadcrumbs
point to README.md until a root docs/index.md is added.
In `@docs/guides/ISP_PROTOCOL_MIGRATION.md`:
- Around line 1-2: The breadcrumb navigation link currently points to
"../index.md" which is the wrong case; update the link target string
"../index.md" to "../INDEX.md" so it matches the actual documentation index
filename (change the breadcrumb line that contains "**Navigation**:
[Home](../index.md) > Guides > ISP Protocol Migration Guide" to use
"../INDEX.md").
In `@docs/guides/node-building/03_COMPUTE_NODE_TUTORIAL.md`:
- Around line 1-4: The breadcrumb Home links reference ../../index.md
(lowercase) but the repository currently has docs/INDEX.md (uppercase); rename
the file docs/INDEX.md to docs/index.md so the case-sensitive path
../../index.md resolves correctly across all affected docs (this change will fix
the broken links referenced in files like
docs/guides/node-building/03_COMPUTE_NODE_TUTORIAL.md and the ~183 other
documentation files).
In `@docs/guides/node-building/04_EFFECT_NODE_TUTORIAL.md`:
- Around line 1-3: Update the breadcrumb navigation line that defines the Home
link in the EFFECT Node Tutorial by replacing the lowercase path
"../../index.md" with the correct uppercase "../../INDEX.md" so the Home link
points to the existing docs entry; locate the line starting with
"**Navigation**: [Home](" and edit the URL accordingly.
In `@docs/patterns/LEASE_MANAGEMENT_PATTERN.md`:
- Around line 1-2: Replace the incorrect breadcrumb link "../index.md" with the
correct "../INDEX.md" in the Lease Management pattern file (the line containing
"**Navigation**: [Home](../index.md) > [Patterns](./README.md) > Lease
Management Pattern") and make the same replacement in the other listed pattern
files and patterns README (files containing the same breadcrumb string),
ensuring every occurrence of "[Home](../index.md)" becomes
"[Home](../INDEX.md)".
In `@docs/services/invariant/CUSTOM_CALLABLES.md`:
- Around line 1-2: The breadcrumb in docs/services/invariant/CUSTOM_CALLABLES.md
points Home to ../../index.md which does not exist; update the Home link to a
valid existing doc (for example ../../README.md or ../../docs.md) or create the
missing docs/index.md file, and ensure the breadcrumb line that currently
contains "**Navigation**: [Home](../../index.md) > [Services](../README.md) >
Invariant > Custom Callables" is modified to reference the chosen valid path so
the Home link is not broken.
In `@docs/testing/COVERAGE.md`:
- Around line 1-2: Update the breadcrumb in COVERAGE.md to point to the correct
root docs file by changing the link target from ../index.md to ../INDEX.md (edit
the existing breadcrumb line). Also either add a README.md file under
docs/testing/ (create docs/testing/README.md with the same section intro used by
other sections) so the "Testing" breadcrumb link resolves, or remove the
hyperlink from the "Testing" segment in the breadcrumb so it stays plain text;
ensure consistency with other docs sections' breadcrumb style when making the
change.
In `@docs/testing/INTEGRATION_TESTING.md`:
- Around line 1-2: The breadcrumb link "[Home](../index.md)" in
docs/testing/INTEGRATION_TESTING.md points to a non-existent target; either add
a new docs/index.md page or update the breadcrumb link text to an existing home
file (e.g., change the link target in the string "[Home](../index.md)" to the
correct existing file path used for your docs home), and ensure the markdown
link resolves correctly.
🟡 Minor comments (20)
docs/standards/onex_terminology.md-1-1 (1)
1-1: Align breadcrumb label with document title.The breadcrumb ends with “Terminology” while the document title is “ONEX Core Terminology”. Consider updating the breadcrumb label to match the title for consistency and easier navigation.
docs/guides/node-building/05_REDUCER_NODE_TUTORIAL.md-1-3 (1)
1-3: Remove the blank line inside the blockquote.Markdownlint flags a blank line between blockquote lines. Keep the blockquote contiguous to satisfy MD028.
🛠️ Proposed fix
> **Navigation**: [Home](../../index.md) > [Guides](../README.md) > [Node Building](./README.md) > REDUCER Node Tutorial - > **Note**: For authoritative coding standards, see [CLAUDE.md](../../../CLAUDE.md).docs/conventions/ERROR_HANDLING_BEST_PRACTICES.md-1-1 (1)
1-1: Fix breadcrumb link casing to avoid broken navigation.PR objectives reference
docs/index.md, but the breadcrumb points to../INDEX.md. On case‑sensitive systems this link will break. Please align the casing with the actual filename.✅ Suggested change
-> **Navigation**: [Home](../INDEX.md) > Conventions > Error Handling Best Practices +> **Navigation**: [Home](../index.md) > Conventions > Error Handling Best Practicesdocs/guides/node-building/06_ORCHESTRATOR_NODE_TUTORIAL.md-1-3 (1)
1-3: Fix MD028: remove blank line inside blockquote.The blank line between the two blockquoted lines triggers MD028 (no-blanks-blockquote). Keep the note contiguous or separate into two blockquote blocks.
🔧 Proposed fix
-> **Navigation**: [Home](../../index.md) > [Guides](../README.md) > [Node Building](./README.md) > ORCHESTRATOR Node Tutorial - -> **Note**: For authoritative coding standards, see [CLAUDE.md](../../../CLAUDE.md). +> **Navigation**: [Home](../../index.md) > [Guides](../README.md) > [Node Building](./README.md) > ORCHESTRATOR Node Tutorial +> **Note**: For authoritative coding standards, see [CLAUDE.md](../../../CLAUDE.md).docs/guides/mixin-development/README.md-1-2 (1)
1-2: Remove the blank line inside the blockquote to satisfy MD028.
markdownlint flags a blank line inside the blockquote. Consider removing the empty line or keeping the blockquote contiguous.🛠️ Proposed fix
-> **Navigation**: [Home](../../index.md) > [Guides](../README.md) > Mixin Development - +> **Navigation**: [Home](../../index.md) > [Guides](../README.md) > Mixin DevelopmentAs per markdownlint.
docs/guides/templates/COMPUTE_NODE_TEMPLATE.md-1-2 (1)
1-2: Fix MD028: blank line inside blockquote. This triggers the markdownlint failure reported for Line 2.🧩 Suggested fix
-> **Navigation**: [Home](../../index.md) > [Guides](../README.md) > Templates > COMPUTE Node Template - +> **Navigation**: [Home](../../index.md) > [Guides](../README.md) > Templates > COMPUTE Node Templatedocs/architecture/decisions/ADR-002-context-mutability-design-decision.md-1-2 (1)
1-2: Remove or deprecate the old ADR-002 file to avoid confusion with the consolidated ADR-007.The navigation breadcrumb addition is appropriate. However, the duplication concern is valid:
ADR-007-context-mutability-design-decision.mdindocs/decisions/is the consolidated authoritative version (originally ADR-002, renumbered during consolidation to avoid conflict with the new ADR-002-field-limit-constants.md). The oldADR-002-context-mutability-design-decision.mdindocs/architecture/decisions/still exists and should either be removed entirely or explicitly marked as superseded by ADR-007 to prevent developers from referencing the wrong file.docs/guides/node-building/07_PATTERNS_CATALOG.md-30-33 (1)
30-33: Align base-class imports with CLAUDE.md guidance.Examples import
NodeComputefromomnibase_core.nodes.node_compute, but CLAUDE.md states base classes should be imported fromomnibase_core.nodes. Please update all code samples to match the standard. Based on learnings, ...docs/guides/node-building/07_PATTERNS_CATALOG.md-1-3 (1)
1-3: Fix blockquote blank line (MD028).Markdownlint flags a blank line inside the blockquote. Add a
>to the blank line or remove it.💡 Minimal fix
-> **Navigation**: [Home](../../index.md) > [Guides](../README.md) > [Node Building](./README.md) > Patterns Catalog -> -> **Note**: For authoritative coding standards, see [CLAUDE.md](../../../CLAUDE.md). +> **Navigation**: [Home](../../index.md) > [Guides](../README.md) > [Node Building](./README.md) > Patterns Catalog +> +> **Note**: For authoritative coding standards, see [CLAUDE.md](../../../CLAUDE.md).docs/guides/node-building/08_COMMON_PITFALLS.md-1-4 (1)
1-4: Fix markdown blockquote formatting.Lines 1-4 create two separate blockquotes due to the blank line at line 2. Per MD028 (no-blanks-blockquote), blank lines should not appear inside blockquote blocks.
📝 Fix blockquote formatting
Option 1: Remove the blank line to create a single blockquote:
> **Navigation**: [Home](../../index.md) > [Guides](../README.md) > [Node Building](./README.md) > Common Pitfalls -> +> > **Note**: For authoritative coding standards, see [CLAUDE.md](../../../CLAUDE.md). -Option 2: Separate into two distinct blockquotes (remove the
>continuation):> **Navigation**: [Home](../../index.md) > [Guides](../README.md) > [Node Building](./README.md) > Common Pitfalls > **Note**: For authoritative coding standards, see [CLAUDE.md](../../../CLAUDE.md).docs/conventions/FILE_HEADERS.md-1-1 (1)
1-1: Use consistent index.md casing to avoid broken link on case‑sensitive filesystems.
Most other docs reference../index.md. If the actual file isdocs/index.md, the current../INDEX.mdmay break in CI/link checks on Linux.🔧 Suggested fix
-> **Navigation**: [Home](../INDEX.md) > Conventions > File Headers +> **Navigation**: [Home](../index.md) > Conventions > File Headersdocs/guides/replay/REPLAY_SAFETY_INTEGRATION.md-1-2 (1)
1-2: Remove blank line inside blockquote to satisfy markdownlint (MD028).The empty blockquote line triggers MD028. Remove the blank
>line to clear the lint warning.🧹 Proposed fix
> **Navigation**: [Home](../../index.md) > [Guides](../README.md) > Replay > Replay Safety Integration -docs/guides/node-building/02_NODE_TYPES.md-1-4 (1)
1-4: Remove blank line inside blockquote to satisfy markdownlint (MD028).The empty blockquote line triggers MD028. Remove the blank
>line or collapse into two separate blockquotes without a blank line.🧹 Proposed fix
> **Navigation**: [Home](../../index.md) > [Guides](../README.md) > [Node Building](./README.md) > Node Types - > **Note**: For authoritative coding standards, see [CLAUDE.md](../../../CLAUDE.md).docs/guides/node-building/01_WHAT_IS_A_NODE.md-1-4 (1)
1-4: Fix markdownlint MD028 (blank line inside blockquote).
Line 2 is a blank line between two blockquotes, which triggers MD028 in markdownlint. Remove the blank line or keep it within the blockquote by prefixing>.🔧 Suggested fix
> **Navigation**: [Home](../../index.md) > [Guides](../README.md) > [Node Building](./README.md) > What is a Node? - -> **Note**: For authoritative coding standards, see [CLAUDE.md](../../../CLAUDE.md). +> **Note**: For authoritative coding standards, see [CLAUDE.md](../../../CLAUDE.md).docs/reference/node-archetypes.md-377-383 (1)
377-383: Use a supported condition operator in the reducer example.Line 381 uses
is_present, which doesn’t align with the documented operator set (e.g.,exists/not_exists). This can mislead readers implementing validators.🔧 Suggested fix
- - expression: "order_id is_present" + - expression: "order_id exists _"docs/reference/node-archetypes.md-41-49 (1)
41-49: Clarify handlers location and label the directory tree fence.Line 41 uses an unlabeled fenced block (MD040), and the
handlers/folder placement can be read as core‑repo guidance even though handlers live in infra. Consider adding a language tag and clarifying that handlers are infra‑side only.🔧 Suggested update
-``` +```text nodes/<node_name>/ ├── contract.yaml # ONEX contract (required) ├── node.py # Node class implementation (required) ├── models/ # Node-specific Pydantic models │ ├── __init__.py │ └── model_*.py -└── handlers/ # Handler implementations (optional) +└── handlers/ # Handler implementations (omnibase_infra only) └── handler_*.py</details> </blockquote></details> <details> <summary>docs/decisions/README.md-40-47 (1)</summary><blockquote> `40-47`: **Category counts appear inconsistent.** The category counts sum to 10 (3+2+2+1+1+1), but the ADR Index lists 9 ADRs. This might indicate a counting error or an ADR being counted in multiple categories. <details> <summary>Suggested fix</summary> Verify each ADR's category assignment and update counts accordingly. If ADR-006 and ADR-013 are both in "Type System", the count of 2 is correct, but then Architecture (3) + Error Handling (2) + Type System (2) + Validation (1) + API Design (1) + Security (1) = 10 ≠ 9 ADRs. One possibility: RISK-009 might be incorrectly counted in the Architecture category instead of only in Security. </details> </blockquote></details> <details> <summary>scripts/validation/validate_markdown_links.py-36-41 (1)</summary><blockquote> `36-41`: **Potential line number calculation bug when link is not found.** If `match.group(0)` is not found in the original `content` (e.g., the link was inside a code block that was removed), `content.find()` returns `-1`, resulting in line number `0`. This could produce misleading error output. <details> <summary>Suggested fix</summary> ```diff for match in re.finditer(pattern, clean_content): link = match.group(2) # Find line number in original content - # Search for the same link pattern in original - line_num = content[: content.find(match.group(0))].count("\n") + 1 + # Search for the same link pattern in original content + pos = content.find(match.group(0)) + if pos == -1: + # Link was likely in a code block - skip it + continue + line_num = content[:pos].count("\n") + 1 links.append((link, line_num))docs/architecture/decisions/ADR-001-protocol-based-di-architecture.md-1-1 (1)
1-1: Fix broken Home navigation link.The
[Home](../../index.md)link points todocs/index.md, which does not exist. Either create that file or update the link to point to an existing file.docs/decisions/ADR-013-status-taxonomy.md-1-1 (1)
1-1: Update navigation link to match actual filename casing.The breadcrumb references
../index.md(lowercase), but the actual file isdocs/INDEX.md(uppercase). Update the link to../INDEX.mdto ensure it resolves correctly.
🧹 Nitpick comments (18)
docs/guides/VERSION_FIELD_AUTOMATION_STRATEGY.md (1)
1-2: Navigation breadcrumb addition looks good.The breadcrumb structure is correct and follows the PR pattern. The relative link
../index.mdproperly points fromdocs/guides/todocs/index.md.Optional consistency improvements
Consider these optional enhancements:
- Link the "Guides" section: Since the PR mentions creating
docs/guides/README.md, you could make "Guides" a hyperlink for consistency:-> **Navigation**: [Home](../index.md) > Guides > Version Field Automation Strategy +> **Navigation**: [Home](../index.md) > [Guides](README.md) > Version Field Automation Strategy
- Update the "Last Updated" field (line 909): Since the file is being modified, consider updating the date from
2025-11-22to2026-01-18.docs/conventions/TERMINOLOGY_GUIDE.md (1)
7-7: Consider updating the "Last Updated" dates.The dates show
2025-11-18, which is approximately two months old. Since this file is part of the comprehensive documentation rewrite (PR#405), consider updating these dates to reflect the current changes.📅 Proposed date update
-**Last Updated**: 2025-11-18 +**Last Updated**: 2026-01-18And at the bottom of the file:
-**Last Updated**: 2025-11-18 +**Last Updated**: 2026-01-18Also applies to: 442-442
docs/patterns/APPROVED_UNION_PATTERNS.md (1)
2-2: Optional: Fix markdown blockquote formatting.The blank line at line 2 breaks the blockquote, creating two separate blockquote blocks instead of one continuous section. While this doesn't affect functionality, it triggers a markdown linting warning (MD028).
📝 Suggested formatting fix
Option 1: Combine into a single blockquote by prefixing the blank line:
> **Navigation**: [Home](../index.md) > [Patterns](./README.md) > Approved Union Patterns -> +> > **Note**: For authoritative coding standards, see [CLAUDE.md](../../CLAUDE.md).Option 2: Separate clearly by removing the blockquote prefix from line 2:
> **Navigation**: [Home](../index.md) > [Patterns](./README.md) > Approved Union Patterns - + > **Note**: For authoritative coding standards, see [CLAUDE.md](../../CLAUDE.md).docs/ci/TRANSPORT_IMPORT_CHECKER_EVALUATION.md (1)
1-2: Consider adding a section index link for consistency.Similar to the Architecture section navigation, consider linking "CI" to a section index if one exists (e.g.,
[CI](./README.md)). This would provide consistent navigation patterns across the documentation.docs/guides/PERFORMANCE_BENCHMARKS.md (1)
1-2: Link "Guides" in the breadcrumb for consistency with other documentation sections.Most guides files link their section header (e.g.,
[Guides](../README.md)in node-building and mixin-development files), and other documentation sections (Architecture, Patterns, Decisions) follow the same pattern. Make this breadcrumb consistent:Suggested change
-> **Navigation**: [Home](../index.md) > Guides > Performance Benchmarks +> **Navigation**: [Home](../index.md) > [Guides](./README.md) > Performance Benchmarksdocs/getting-started/installation.md (1)
1-4: Consider addressing the markdownlint warning for blockquote formatting.The navigation header and CLAUDE.md reference are valuable additions. However, the blank line at Line 2 creates two separate blockquotes, which triggers the MD028 markdownlint rule.
If these are intended as separate informational blocks, you can suppress the warning. If they should be a single block, remove the blank line:
Option 1: Single blockquote block
> **Navigation**: [Home](../index.md) > Getting Started > Installation -> > **Note**: For authoritative coding standards, see [CLAUDE.md](../../CLAUDE.md).Option 2: Keep separate (suppress warning)
If the separation is intentional for visual clarity, add a markdownlint suppression comment.docs/getting-started/QUICK_START.md (1)
1-4: Fix MD028: remove blank line inside blockquote.markdownlint flags the blank line between blockquote lines. Consider collapsing into a single blockquote block.
♻️ Suggested fix
-> **Navigation**: [Home](../index.md) > Getting Started > Quick Start - -> **Note**: For authoritative coding standards, see [CLAUDE.md](../../CLAUDE.md). +> **Navigation**: [Home](../index.md) > Getting Started > Quick Start +> **Note**: For authoritative coding standards, see [CLAUDE.md](../../CLAUDE.md).docs/guides/node-building/09_TESTING_INTENT_PUBLISHER.md (1)
1-4: Fix MD028: remove blank line inside blockquote.markdownlint flags the blank line between blockquote lines. Consider collapsing into a single blockquote block.
♻️ Suggested fix
-> **Navigation**: [Home](../../index.md) > [Guides](../README.md) > [Node Building](./README.md) > Testing Intent Publisher - -> **Note**: For authoritative coding standards, see [CLAUDE.md](../../../CLAUDE.md). +> **Navigation**: [Home](../../index.md) > [Guides](../README.md) > [Node Building](./README.md) > Testing Intent Publisher +> **Note**: For authoritative coding standards, see [CLAUDE.md](../../../CLAUDE.md).docs/guides/node-building/10_AGENT_TEMPLATES.md (1)
1-4: Fix MD028: remove blank line inside blockquote.markdownlint flags the blank line between blockquote lines. Consider collapsing into a single blockquote block.
♻️ Suggested fix
-> **Navigation**: [Home](../../index.md) > [Guides](../README.md) > [Node Building](./README.md) > Agent Templates - -> **Note**: For authoritative coding standards, see [CLAUDE.md](../../../CLAUDE.md). +> **Navigation**: [Home](../../index.md) > [Guides](../README.md) > [Node Building](./README.md) > Agent Templates +> **Note**: For authoritative coding standards, see [CLAUDE.md](../../../CLAUDE.md).docs/decisions/README.md (1)
27-31: Clarify the distinction between ADR-006 and ADR-013.Both ADR-006 and ADR-013 are titled "Status Taxonomy" with similar categories (Type System). Consider clarifying their distinct purposes in the title or description to avoid confusion:
- ADR-006: "Status Taxonomy and Categorical Organization"
- ADR-013: "Status Taxonomy (Canonical Enums)"
If these are genuinely distinct decisions, the differentiation could be clearer in the index descriptions.
scripts/validation/validate_markdown_links.py (2)
1-14: Missingfrom __future__ import annotationsimport.Per coding guidelines, Python files should have
from __future__ import annotationsas the second import after the module docstring.Suggested fix
#!/usr/bin/env python3 """ Validate markdown links in documentation. Checks for: - Broken internal file links (relative paths) - Missing anchor links - Unreachable files """ +from __future__ import annotations + import re import sys from pathlib import Path
116-121: Consider using more specific exception handling.The broad
Exceptioncatch could mask unexpected errors. Per coding guidelines, consider using more specific exception types or adding an error handling comment marker.Suggested fix
try: content = md_file.read_text(encoding="utf-8") - except Exception as e: + except (OSError, UnicodeDecodeError) as e: + # fallback-ok: Log and continue to validate other files print(f"❌ Error reading {md_file.relative_to(repo_root)}: {e}") errors += 1 continuedocs/decisions/ADR-012-VALIDATOR-ERROR-HANDLING.md (1)
198-198: Minor: Consider hyphenating "code-driven" as compound adjective.The phrase "Error code driven logic" would read better as "Error code-driven logic" when used as a compound modifier.
📝 Suggested fix
-**Example - Error code driven logic**: +**Example - Error code-driven logic**:docs/reference/contracts.md (2)
2-2: Address the blank line inside blockquote.Static analysis flagged a blank line inside the blockquote block at line 2. While this is a minor formatting issue, it's good practice to maintain consistent Markdown formatting.
📝 Proposed fix
> **Navigation**: [Home](../index.md) > Reference > Contracts - > **Note**: For authoritative coding rules, see [CLAUDE.md](../../CLAUDE.md).Based on learnings from static analysis tools.
645-654: Add language identifier to the fenced code block.The fenced code block at line 645 lacks a language identifier, which degrades syntax highlighting and readability. Based on the content (directory structure), this should be marked as a
textorbashcode block.📝 Proposed fix
-``` +```text # WRONG - Both files in same directory nodes/my_node/ contract.yaml handler_contract.yaml # Causes AMBIGUOUS_CONTRACT_CONFIGURATION error # CORRECT - One contract per directory nodes/my_node/ contract.yaml # Single source of truth</details> Based on learnings from static analysis tools. </blockquote></details> <details> <summary>docs/decisions/ADR-013-status-taxonomy.md (1)</summary><blockquote> `118-122`: **Consider clarifying the COMPLETED vs SUCCESS distinction.** The explanation that both `COMPLETED` and `SUCCESS` are successful outcomes but used in different scenarios may be confusing to developers. Consider adding a concrete code example showing when to prefer `COMPLETED` over `SUCCESS`, or consolidating to a single value if the distinction isn't essential. </blockquote></details> <details> <summary>docs/INDEX.md (2)</summary><blockquote> `212-217`: **Add language identifier to fenced code block.** The ASCII diagram fenced code block should specify a language identifier for proper rendering and to satisfy markdown linters. <details> <summary>📝 Proposed fix</summary> ```diff -``` +```text ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ EFFECT │───>│ COMPUTE │───>│ REDUCER │───>│ORCHESTRATOR │ │ (Input) │ │ (Process) │ │(Aggregate) │ │(Coordinate) │ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘</details> Based on static analysis hints. --- `265-295`: **Add language identifier to fenced code block.** The package structure code block should specify a language identifier (e.g., `text` or `tree`) for proper rendering and to satisfy markdown linters. <details> <summary>📝 Proposed fix</summary> ```diff -``` +```text src/omnibase_core/ ├── constants/ # Project constants ├── container/ # DI container implementationBased on static analysis hints.
| > **Navigation**: [Home](../index.md) > [Architecture](./overview.md) > Dict[str, Any] Prevention | ||
|
|
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Verify the breadcrumb navigation links in the file
# First, check if the file exists
if [ -f "docs/architecture/DICT_STR_ANY_PREVENTION.md" ]; then
echo "✓ File exists: docs/architecture/DICT_STR_ANY_PREVENTION.md"
else
echo "✗ File not found: docs/architecture/DICT_STR_ANY_PREVENTION.md"
exit 1
fi
# Check the content of lines 1-2
echo ""
echo "Content of lines 1-2:"
head -n 2 "docs/architecture/DICT_STR_ANY_PREVENTION.md"
echo ""
# Now verify the link targets from docs/architecture/ directory
cd docs/architecture
# Check if Home link target exists
if [ -f ../index.md ]; then
echo "✓ Home link target exists: ../index.md"
else
echo "✗ Missing: ../index.md"
fi
# Check if Architecture link target exists
if [ -f ./overview.md ]; then
echo "✓ Architecture link target exists: ./overview.md"
else
echo "✗ Missing: ./overview.md"
fiRepository: OmniNode-ai/omnibase_core
Length of output: 323
🏁 Script executed:
#!/bin/bash
# Find all index.md files in the repository to locate the actual home page
echo "Searching for index.md files in the repository:"
find . -name "index.md" -type f | head -20
echo ""
echo "Checking docs directory structure:"
ls -la docs/ | head -20Repository: OmniNode-ai/omnibase_core
Length of output: 1305
🏁 Script executed:
#!/bin/bash
# Check other files in docs/architecture to see what Home link they use
echo "Checking breadcrumb patterns in architecture files:"
rg "Navigation.*Home" docs/architecture/ --type md
echo ""
echo "Verifying that INDEX.md is the actual home page:"
head -20 docs/INDEX.mdRepository: OmniNode-ai/omnibase_core
Length of output: 10446
Fix broken Home links in breadcrumb navigation: use ../INDEX.md instead of ../index.md
The breadcrumb navigation contains a broken link. The Home link references ../index.md, but the actual home page is docs/INDEX.md (uppercase). This issue affects all 40+ breadcrumbs added to the architecture directory files.
Change line 1 from:
> **Navigation**: [Home](../index.md) > [Architecture](./overview.md) > Dict[str, Any] Prevention
To:
> **Navigation**: [Home](../INDEX.md) > [Architecture](./overview.md) > Dict[str, Any] Prevention
This same fix is needed across all architecture files and nested subdirectories (using ../../INDEX.md for nested files).
🤖 Prompt for AI Agents
In `@docs/architecture/DICT_STR_ANY_PREVENTION.md` around lines 1 - 2, Update the
breadcrumb "Home" link in the architecture markdown files: replace any
occurrence of "[Home](../index.md)" with "[Home](../INDEX.md)" in top-level
architecture docs (e.g., the breadcrumb line containing "Navigation:
[Home](../index.md) > [Architecture](./overview.md) > ..."), and for nested
subdirectory files replace "[Home](../../index.md)" with
"[Home](../../INDEX.md)"; ensure you update all similar breadcrumb strings
across files in the architecture directory so the Home link points to the
correct uppercase INDEX.md.
| > **Navigation**: [Home](../index.md) > [Architecture](./overview.md) > Effect Timeout Behavior | ||
|
|
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Verify navigation breadcrumb links
# Check if the files referenced in the breadcrumb exist
echo "=== Verifying breadcrumb link targets ==="
echo ""
# Target 1: ../index.md from docs/architecture/ = docs/index.md
echo "Checking Home link target (../index.md from docs/architecture/):"
if [ -f "docs/index.md" ]; then
echo "✓ docs/index.md exists"
else
echo "✗ docs/index.md NOT FOUND"
fi
# Target 2: ./overview.md from docs/architecture/ = docs/architecture/overview.md
echo ""
echo "Checking Architecture link target (./overview.md from docs/architecture/):"
if [ -f "docs/architecture/overview.md" ]; then
echo "✓ docs/architecture/overview.md exists"
else
echo "✗ docs/architecture/overview.md NOT FOUND"
fi
# Verify the file itself exists
echo ""
echo "Checking the file being modified:"
if [ -f "docs/architecture/EFFECT_TIMEOUT_BEHAVIOR.md" ]; then
echo "✓ docs/architecture/EFFECT_TIMEOUT_BEHAVIOR.md exists"
echo ""
echo "First 5 lines of the file:"
head -5 "docs/architecture/EFFECT_TIMEOUT_BEHAVIOR.md"
else
echo "✗ docs/architecture/EFFECT_TIMEOUT_BEHAVIOR.md NOT FOUND"
fiRepository: OmniNode-ai/omnibase_core
Length of output: 579
The "Home" link in the breadcrumb navigation is broken.
The breadcrumb references ../index.md which resolves to docs/index.md, but this file does not exist in the repository. The "Architecture" link to ./overview.md is correct, but the "Home" link will fail.
Update the breadcrumb to point to the correct home page location, or create docs/index.md if it is intended to exist.
🤖 Prompt for AI Agents
In `@docs/architecture/EFFECT_TIMEOUT_BEHAVIOR.md` around lines 1 - 2, The
breadcrumb in EFFECT_TIMEOUT_BEHAVIOR.md uses the broken link string
"../index.md"; update that link to the actual repository home page path (for
example the correct relative path to the site root or main docs landing file) or
alternatively add a docs/index.md file if the intent was to have a docs landing
page; locate the breadcrumb line containing "../index.md" and either replace
"../index.md" with the correct path to the home page or create the missing
docs/index.md to restore the link.
| > **Navigation**: [Home](../index.md) > [Patterns](./README.md) > Lease Management Pattern | ||
|
|
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Check if the files mentioned in the breadcrumb exist
echo "=== Checking file existence ==="
echo "Checking docs/index.md:"
ls -la docs/index.md 2>&1
echo -e "\nChecking docs/patterns/README.md:"
ls -la docs/patterns/README.md 2>&1
echo -e "\nChecking docs/patterns/LEASE_MANAGEMENT_PATTERN.md:"
ls -la docs/patterns/LEASE_MANAGEMENT_PATTERN.md 2>&1
echo -e "\n=== Showing first few lines of LEASE_MANAGEMENT_PATTERN.md ==="
head -5 docs/patterns/LEASE_MANAGEMENT_PATTERN.md 2>&1Repository: OmniNode-ai/omnibase_core
Length of output: 634
🏁 Script executed:
#!/bin/bash
# Search for pre-commit configuration or markdown link validation
echo "=== Looking for pre-commit configuration ==="
find . -name ".pre-commit-config.yaml" -o -name ".pre-commit-hooks.yaml" | head -10Repository: OmniNode-ai/omnibase_core
Length of output: 139
🏁 Script executed:
#!/bin/bash
# List files in docs directory to understand structure
echo "=== Files in docs/ ==="
ls -la docs/ 2>&1
echo -e "\n=== Files in docs/patterns/ ==="
ls -la docs/patterns/ 2>&1Repository: OmniNode-ai/omnibase_core
Length of output: 2380
🏁 Script executed:
#!/bin/bash
# Check if other pattern files have the same breadcrumb issue
echo "=== Checking other markdown files in docs/patterns/ for breadcrumb ==="
grep -l "Navigation" docs/patterns/*.md 2>&1
echo -e "\n=== Check breadcrumb in a few other files ==="
for file in docs/patterns/CIRCUIT_BREAKER_PATTERN.md docs/patterns/README.md; do
echo "File: $file"
head -1 "$file" 2>&1
doneRepository: OmniNode-ai/omnibase_core
Length of output: 745
🏁 Script executed:
#!/bin/bash
# Check pre-commit config for markdown link validation
echo "=== Contents of .pre-commit-config.yaml ==="
cat .pre-commit-config.yaml 2>&1 | head -50Repository: OmniNode-ai/omnibase_core
Length of output: 2033
Fix broken navigation breadcrumb: ../index.md should be ../INDEX.md
The relative path to the home page is incorrect. The file docs/index.md does not exist; the root documentation file is docs/INDEX.md (uppercase). The breadcrumb link must be corrected to [Home](../INDEX.md).
Additionally, this broken link pattern exists in all 8 pattern files and the patterns README:
docs/patterns/ANTI_PATTERNS.mddocs/patterns/APPROVED_UNION_PATTERNS.mddocs/patterns/CIRCUIT_BREAKER_PATTERN.mddocs/patterns/CONFIGURATION_MANAGEMENT.mddocs/patterns/CUSTOM_BOOL_PATTERN.mddocs/patterns/EVENT_DRIVEN_ARCHITECTURE.mddocs/patterns/LEASE_MANAGEMENT_PATTERN.mddocs/patterns/PURE_FSM_REDUCER_PATTERN.mddocs/patterns/README.md
All breadcrumb navigation links must be updated to use ../INDEX.md instead of ../index.md.
🤖 Prompt for AI Agents
In `@docs/patterns/LEASE_MANAGEMENT_PATTERN.md` around lines 1 - 2, Replace the
incorrect breadcrumb link "../index.md" with the correct "../INDEX.md" in the
Lease Management pattern file (the line containing "**Navigation**:
[Home](../index.md) > [Patterns](./README.md) > Lease Management Pattern") and
make the same replacement in the other listed pattern files and patterns README
(files containing the same breadcrumb string), ensuring every occurrence of
"[Home](../index.md)" becomes "[Home](../INDEX.md)".
| > **Navigation**: [Home](../../index.md) > [Services](../README.md) > Invariant > Custom Callables | ||
|
|
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Verify navigation link targets exist
# Check from the context of docs/services/invariant/CUSTOM_CALLABLES.md
# ../../index.md should be docs/index.md
# ../README.md should be docs/services/README.md
echo "=== Checking for docs/index.md (Home link) ==="
if [ -f "docs/index.md" ]; then
echo "✓ docs/index.md exists"
else
echo "✗ docs/index.md NOT found"
fi
echo ""
echo "=== Checking for docs/services/README.md (Services link) ==="
if [ -f "docs/services/README.md" ]; then
echo "✓ docs/services/README.md exists"
else
echo "✗ docs/services/README.md NOT found"
fi
echo ""
echo "=== Checking the target file ==="
if [ -f "docs/services/invariant/CUSTOM_CALLABLES.md" ]; then
echo "✓ docs/services/invariant/CUSTOM_CALLABLES.md exists"
echo "First 5 lines:"
head -5 "docs/services/invariant/CUSTOM_CALLABLES.md"
else
echo "✗ docs/services/invariant/CUSTOM_CALLABLES.md NOT found"
fiRepository: OmniNode-ai/omnibase_core
Length of output: 642
Fix broken Home navigation link — docs/index.md does not exist.
The navigation breadcrumb contains a broken link to ../../index.md (Home). While the Services link to ../README.md is valid, the Home link points to a non-existent file. Either create docs/index.md or update the Home link to point to an existing documentation file.
🤖 Prompt for AI Agents
In `@docs/services/invariant/CUSTOM_CALLABLES.md` around lines 1 - 2, The
breadcrumb in docs/services/invariant/CUSTOM_CALLABLES.md points Home to
../../index.md which does not exist; update the Home link to a valid existing
doc (for example ../../README.md or ../../docs.md) or create the missing
docs/index.md file, and ensure the breadcrumb line that currently contains
"**Navigation**: [Home](../../index.md) > [Services](../README.md) > Invariant >
Custom Callables" is modified to reference the chosen valid path so the Home
link is not broken.
| > **Navigation**: [Home](../index.md) > Testing > Code Coverage Testing | ||
|
|
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Verify the navigation link target exists
echo "=== Checking navigation target ==="
if [ -f "docs/index.md" ]; then
echo "✓ docs/index.md exists"
echo " (Navigation link target is valid)"
else
echo "✗ docs/index.md is missing"
fi
# Check Testing section structure
echo ""
echo "=== Testing section structure ==="
if [ -d "docs/testing" ]; then
echo "Testing directory exists"
ls -la docs/testing/ | grep -E "(README|index|COVERAGE)" || echo "No README/index found in docs/testing/"
else
echo "docs/testing/ directory not found"
fi
# Check navigation patterns in other documentation files
echo ""
echo "=== Navigation breadcrumb patterns in documentation ==="
rg "^\> \*\*Navigation\*\*:" docs/ -A 1 | head -30
# Check the actual content of COVERAGE.md
echo ""
echo "=== First few lines of docs/testing/COVERAGE.md ==="
head -5 docs/testing/COVERAGE.mdRepository: OmniNode-ai/omnibase_core
Length of output: 650
🏁 Script executed:
#!/bin/bash
# Find all index/README files in docs directory
echo "=== Index/README files in docs/ ==="
find docs -maxdepth 2 -type f \( -name "index.md" -o -name "README.md" \)
# Check what's at docs root level
echo ""
echo "=== Files at docs/ root ==="
ls -la docs/ | head -20
# Check git status to see what files are staged/modified
echo ""
echo "=== Git status for docs/ ==="
git status docs/ 2>/dev/null | head -30
# Look for any references to docs/index.md in the codebase
echo ""
echo "=== References to docs/index in repository ==="
rg "docs/index" --max-count 5
# Check if there's a root navigation that COVERAGE.md should link to
echo ""
echo "=== Top-level documentation files ==="
ls -la *.md 2>/dev/null || echo "No .md files at repo root"Repository: OmniNode-ai/omnibase_core
Length of output: 1907
🏁 Script executed:
#!/bin/bash
# Check docs/INDEX.md exists and is the root navigation
echo "=== docs/INDEX.md content (first 30 lines) ==="
head -30 docs/INDEX.md
# Check if docs/testing/ should have a README.md
echo ""
echo "=== docs/testing/ directory contents ==="
ls -la docs/testing/
# Check the pattern of other section README files
echo ""
echo "=== Example section README (docs/guides/README.md first 10 lines) ==="
head -10 docs/guides/README.md
# Verify path resolution for the COVERAGE.md navigation
echo ""
echo "=== Testing relative path resolution ==="
echo "From docs/testing/COVERAGE.md:"
echo " ../index.md would resolve to: docs/index.md (DOES NOT EXIST)"
echo " ../INDEX.md would resolve to: docs/INDEX.md (EXISTS)"Repository: OmniNode-ai/omnibase_core
Length of output: 2533
Fix navigation link: change ../index.md to ../INDEX.md.
The navigation breadcrumb uses incorrect case for the root documentation link. From docs/testing/, the path ../index.md resolves to docs/index.md, which does not exist. The actual root documentation index is docs/INDEX.md, so the link should be ../INDEX.md.
Additionally, the Testing breadcrumb cannot be linked because docs/testing/README.md does not exist (unlike other sections: guides, patterns, decisions, reference, services, which all have README.md files). Either create docs/testing/README.md for consistency or remove the link from the breadcrumb text.
🤖 Prompt for AI Agents
In `@docs/testing/COVERAGE.md` around lines 1 - 2, Update the breadcrumb in
COVERAGE.md to point to the correct root docs file by changing the link target
from ../index.md to ../INDEX.md (edit the existing breadcrumb line). Also either
add a README.md file under docs/testing/ (create docs/testing/README.md with the
same section intro used by other sections) so the "Testing" breadcrumb link
resolves, or remove the hyperlink from the "Testing" segment in the breadcrumb
so it stays plain text; ensure consistency with other docs sections' breadcrumb
style when making the change.
| > **Navigation**: [Home](../index.md) > Testing > Integration Testing Guide | ||
|
|
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Check if the home page link target exists
echo "=== Checking link targets ==="
if [ -f "docs/index.md" ]; then
echo "✓ Home page exists: docs/index.md"
else
echo "✗ Missing: docs/index.md"
fi
# Check for Testing section index pages
echo ""
echo "=== Checking for Testing section index ==="
fd -t f "(README|index)\.md" docs/testing/ 2>/dev/null || echo "No index files found in docs/testing/"
# Check the actual file content to verify breadcrumb format
echo ""
echo "=== Actual file content (lines 1-5) ==="
head -5 docs/testing/INTEGRATION_TESTING.mdRepository: OmniNode-ai/omnibase_core
Length of output: 351
Link target does not exist. The navigation breadcrumb references ../index.md, which resolves to docs/index.md, but this file does not exist in the repository. This creates a broken link in the documentation. Either create the missing docs/index.md file or update the breadcrumb to point to an existing location.
🤖 Prompt for AI Agents
In `@docs/testing/INTEGRATION_TESTING.md` around lines 1 - 2, The breadcrumb link
"[Home](../index.md)" in docs/testing/INTEGRATION_TESTING.md points to a
non-existent target; either add a new docs/index.md page or update the
breadcrumb link text to an existing home file (e.g., change the link target in
the string "[Home](../index.md)" to the correct existing file path used for your
docs home), and ensure the markdown link resolves correctly.
- Fix breadcrumb navigation links (index.md → INDEX.md) across 13 files - Correct ADR-002 mislabeling in ADR_BEST_PRACTICES.md - Fix MD028 blockquote formatting in 8 files - Add language identifiers to code blocks in INDEX.md - Fix compound adjective "code-driven" in ADR-012
There was a problem hiding this comment.
Actionable comments posted: 5
🤖 Fix all issues with AI agents
In `@docs/decisions/ADR_BEST_PRACTICES.md`:
- Line 1: Update the breadcrumb link in ADR_BEST_PRACTICES.md (the string
"[Home](../index.md)") to use the correct casing ("[Home](../INDEX.md)"); search
other ADR files in the same directory for the same breadcrumb pattern and
replace any "../index.md" occurrences with "../INDEX.md" so all ADR files
reference the actual docs/INDEX.md filename.
In `@docs/decisions/ADR-006-status-taxonomy.md`:
- Around line 83-289: The ADR enum docs are out of sync with the actual code:
update the EnumWorkflowStatus section to reflect that the code defines PAUSED
(not SIMULATED), update EnumHealthStatus to include INITIALIZING and DISPOSING
(in addition to listed values), and expand EnumSeverityLevel to include the
RFC5424 entries TRACE, EMERGENCY, ALERT, and NOTICE; edit the canonical value
lists for EnumWorkflowStatus, EnumHealthStatus, and EnumSeverityLevel to exactly
match the runtime definitions (EnumWorkflowStatus, EnumHealthStatus,
EnumSeverityLevel) and consider adding a note or a small automation step
(docstring extraction or validation tool) to keep ADRs in sync with the enum
declarations.
In `@docs/guides/EFFECT_SUBCONTRACT_GUIDE.md`:
- Around line 1-2: A blank line inside the blockquote after the line starting
with "> **Navigation**: [Home](../INDEX.md) > Guides > Effect Subcontract Guide"
violates MD028; open EFFECT_SUBCONTRACT_GUIDE.md, locate the blockquote line
that begins with "> **Navigation**" and remove the empty line that follows it
(or replace that empty line with a lone ">" to preserve the blockquote),
ensuring there are no blank lines between consecutive ">"-prefixed lines.
In `@docs/guides/node-building/04_EFFECT_NODE_TUTORIAL.md`:
- Around line 1-3: The blockquote in EFFECT_NODE_TUTORIAL has a blank line
between quoted lines which triggers MD028; edit the blockquote in
docs/guides/node-building/04_EFFECT_NODE_TUTORIAL.md (the lines starting with ">
**Navigation**" and "> **Note**") and remove the empty line or convert it to a
blockquote line by prefixing it with ">" so both lines remain contiguous
blockquote lines (e.g., ensure the blank line is either deleted or changed to ">
" to keep the entire quote as a single block).
In `@docs/INDEX.md`:
- Around line 167-168: Update the two ADR links that currently point to
"architecture/adr/…" so they use the correct directory
"architecture/decisions/…": specifically change the link targets for "ADR-012:
Validator Error Handling" and "ADR-013: Status Taxonomy" to point to
architecture/decisions/ADR-012-VALIDATOR-ERROR-HANDLING.md and
architecture/decisions/ADR-013-status-taxonomy.md respectively so they match the
ADR index path.
🧹 Nitpick comments (2)
docs/testing/COVERAGE.md (1)
1-2: Navigation breadcrumb correctly addresses past review feedback.The navigation header properly links to
../INDEX.md(correct case) and keeps "Testing" as plain text sincedocs/testing/README.mddoesn't exist. Both issues flagged in the previous review have been resolved.For consistency with other documentation sections (guides, patterns, decisions, reference), consider adding a
docs/testing/README.mdindex file that provides an overview of the testing documentation and links to COVERAGE.md, PARALLEL_TESTING.md, and other testing docs.docs/decisions/ADR-012-VALIDATOR-ERROR-HANDLING.md (1)
1-868: Avoid duplicate ADR sources; prefer a single canonical doc.This ADR content appears duplicated with
docs/architecture/adr/ADR-012-VALIDATOR-ERROR-HANDLING.md. To prevent drift, consider making one location canonical and have the other be a short stub that links to it.
| @@ -0,0 +1,294 @@ | |||
| > **Navigation**: [Home](../index.md) > [Decisions](README.md) > ADR Best Practices | |||
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Check breadcrumb target files exist and see what other ADRs reference.
echo "=== Breadcrumb targets ==="
ls -la docs/index.md docs/decisions/README.md docs/decisions/INDEX.md 2>/dev/null
echo -e "\n=== Breadcrumb usage in docs/decisions ==="
rg -n --type=md -C2 '^> \*\*Navigation\*\*:' docs/decisionsRepository: OmniNode-ai/omnibase_core
Length of output: 3529
🏁 Script executed:
#!/bin/bash
# Check if docs/index.md exists at all
echo "=== Check docs/index.md ==="
if [ -f docs/index.md ]; then
echo "docs/index.md EXISTS"
ls -la docs/index.md
else
echo "docs/index.md NOT FOUND"
fi
echo -e "\n=== List all markdown files in docs root ==="
find docs -maxdepth 1 -type f -name "*.md" 2>/dev/null
echo -e "\n=== Check docs directory structure ==="
ls -la docs/ 2>/dev/null | head -20Repository: OmniNode-ai/omnibase_core
Length of output: 1390
🏁 Script executed:
#!/bin/bash
# Check if the broken link pattern is consistent across all ADRs
echo "=== Checking 3 sample ADR files for the same issue ==="
for file in docs/decisions/ADR-001-*.md docs/decisions/ADR_BEST_PRACTICES.md docs/decisions/RISK-009-*.md; do
if [ -f "$file" ]; then
echo "File: $file"
head -1 "$file"
echo ""
fi
doneRepository: OmniNode-ai/omnibase_core
Length of output: 526
Fix breadcrumb casing: change ../index.md to ../INDEX.md.
The breadcrumb references [Home](../index.md) but the actual file is docs/INDEX.md (uppercase). This same issue affects all ADR files in the directory.
🤖 Prompt for AI Agents
In `@docs/decisions/ADR_BEST_PRACTICES.md` at line 1, Update the breadcrumb link
in ADR_BEST_PRACTICES.md (the string "[Home](../index.md)") to use the correct
casing ("[Home](../INDEX.md)"); search other ADR files in the same directory for
the same breadcrumb pattern and replace any "../index.md" occurrences with
"../INDEX.md" so all ADR files reference the actual docs/INDEX.md filename.
| #### 1. Execution Status (`EnumExecutionStatus`) | ||
|
|
||
| **Purpose**: Track the execution lifecycle of tasks, nodes, and individual operations. | ||
|
|
||
| **Canonical Values**: | ||
| ```python | ||
| class EnumExecutionStatus(str, Enum): | ||
| PENDING = "pending" # Queued, not yet started | ||
| RUNNING = "running" # Currently executing | ||
| COMPLETED = "completed" # Finished execution (neutral) | ||
| SUCCESS = "success" # Finished with success | ||
| FAILED = "failed" # Finished with failure | ||
| SKIPPED = "skipped" # Intentionally not executed | ||
| CANCELLED = "cancelled" # Terminated by external request | ||
| TIMEOUT = "timeout" # Exceeded time limit | ||
| PARTIAL = "partial" # Some steps succeeded, others failed | ||
| ``` | ||
|
|
||
| **Value Classifications**: | ||
| - **Active States**: `PENDING`, `RUNNING` | ||
| - **Terminal Success**: `COMPLETED`, `SUCCESS` | ||
| - **Terminal Failure**: `FAILED`, `TIMEOUT` | ||
| - **Terminal Neutral**: `SKIPPED`, `CANCELLED`, `PARTIAL` | ||
|
|
||
| **When to Use**: Node execution, task processing, batch operations, pipeline steps. | ||
|
|
||
| **Location**: `src/omnibase_core/enums/enum_execution_status.py` | ||
|
|
||
| --- | ||
|
|
||
| #### 2. Operation Status (`EnumOperationStatus`) | ||
|
|
||
| **Purpose**: Track the outcome of discrete service operations (API calls, CRUD operations). | ||
|
|
||
| **Canonical Values**: | ||
| ```python | ||
| class EnumOperationStatus(str, Enum): | ||
| SUCCESS = "success" # Operation completed successfully | ||
| FAILED = "failed" # Operation failed | ||
| IN_PROGRESS = "in_progress" # Operation ongoing | ||
| CANCELLED = "cancelled" # Operation cancelled | ||
| PENDING = "pending" # Operation queued | ||
| TIMEOUT = "timeout" # Operation timed out | ||
| ``` | ||
|
|
||
| **When to Use**: Service manager operations, API responses, repository operations. | ||
|
|
||
| **Distinction from Execution**: Operation status is for discrete, atomic operations. Execution status is for longer-running tasks with richer lifecycle tracking. | ||
|
|
||
| **Location**: `src/omnibase_core/enums/enum_operation_status.py` | ||
|
|
||
| --- | ||
|
|
||
| #### 3. Workflow Status (`EnumWorkflowStatus`) | ||
|
|
||
| **Purpose**: Track multi-step workflow progression. | ||
|
|
||
| **Canonical Values**: | ||
| ```python | ||
| class EnumWorkflowStatus(str, Enum): | ||
| PENDING = "pending" # Workflow not yet started | ||
| RUNNING = "running" # Workflow in progress | ||
| COMPLETED = "completed" # Workflow finished successfully | ||
| FAILED = "failed" # Workflow failed | ||
| CANCELLED = "cancelled" # Workflow cancelled | ||
| SIMULATED = "simulated" # Workflow executed in simulation mode | ||
| ``` | ||
|
|
||
| **When to Use**: ORCHESTRATOR nodes, multi-step pipelines, workflow coordination. | ||
|
|
||
| **Location**: `src/omnibase_core/enums/enum_workflow_status.py` | ||
|
|
||
| --- | ||
|
|
||
| #### 4. Health Status (`EnumHealthStatus`) | ||
|
|
||
| **Purpose**: Report the current health state of systems, services, or components. | ||
|
|
||
| **Canonical Values**: | ||
| ```python | ||
| class EnumHealthStatus(str, Enum): | ||
| HEALTHY = "healthy" # Fully operational | ||
| DEGRADED = "degraded" # Operational with reduced capacity | ||
| UNHEALTHY = "unhealthy" # Not operational | ||
| CRITICAL = "critical" # Severe issues requiring immediate attention | ||
| UNKNOWN = "unknown" # Health cannot be determined | ||
| WARNING = "warning" # Potential issues detected | ||
| UNREACHABLE = "unreachable" # Cannot connect to determine health | ||
| AVAILABLE = "available" # Service is available | ||
| UNAVAILABLE = "unavailable" # Service is unavailable | ||
| ERROR = "error" # Health check encountered error | ||
| ``` | ||
|
|
||
| **Health Classifications**: | ||
| - **Operational**: `HEALTHY`, `DEGRADED`, `AVAILABLE` | ||
| - **Non-Operational**: `UNHEALTHY`, `CRITICAL`, `UNAVAILABLE`, `UNREACHABLE`, `ERROR` | ||
| - **Indeterminate**: `UNKNOWN`, `WARNING` | ||
|
|
||
| **When to Use**: Health checks, monitoring endpoints, service discovery, circuit breakers. | ||
|
|
||
| **Location**: `src/omnibase_core/enums/enum_health_status.py` | ||
|
|
||
| --- | ||
|
|
||
| #### 5. Lifecycle Status (`EnumLifecycle`) | ||
|
|
||
| **Purpose**: Track the maturity/availability lifecycle of entities (nodes, features, APIs). | ||
|
|
||
| **Canonical Values**: | ||
| ```python | ||
| class EnumLifecycle(str, Enum): | ||
| DRAFT = "draft" # Under development, not ready for use | ||
| ACTIVE = "active" # Ready for production use | ||
| DEPRECATED = "deprecated" # Still functional, but scheduled for removal | ||
| ARCHIVED = "archived" # No longer functional, kept for history | ||
| ``` | ||
|
|
||
| **When to Use**: Node metadata, feature flags, API versioning, documentation status. | ||
|
|
||
| **Location**: `src/omnibase_core/enums/enum_metadata.py` | ||
|
|
||
| --- | ||
|
|
||
| #### 6. Registration Status (`EnumRegistryEntryStatus`) | ||
|
|
||
| **Purpose**: Track the state of entries in discovery/registry systems. | ||
|
|
||
| **Canonical Values**: | ||
| ```python | ||
| class EnumRegistryEntryStatus(str, Enum): | ||
| EPHEMERAL = "ephemeral" # Temporary registration | ||
| ONLINE = "online" # Registered and available | ||
| VALIDATED = "validated" # Registration verified | ||
| ``` | ||
|
|
||
| **When to Use**: Service discovery, node registration, tool registry. | ||
|
|
||
| **Location**: `src/omnibase_core/enums/enum_registry_entry_status.py` | ||
|
|
||
| --- | ||
|
|
||
| ### Severity Enums (Three Categories) | ||
|
|
||
| #### Issue Severity (`EnumSeverity`) - Canonical | ||
|
|
||
| **Purpose**: Classify the severity of violations, issues, and findings using a standard 6-level scale aligned with logging conventions. | ||
|
|
||
| **Values**: | ||
| ```python | ||
| class EnumSeverity(str, Enum): | ||
| DEBUG = "debug" # Detailed diagnostic information for debugging | ||
| INFO = "info" # General operational information | ||
| WARNING = "warning" # Unexpected situation that doesn't prevent operation | ||
| ERROR = "error" # Operation failed but system can continue | ||
| CRITICAL = "critical" # Serious error requiring attention, system can continue degraded | ||
| FATAL = "fatal" # Unrecoverable error, system must terminate | ||
| ``` | ||
|
|
||
| **When to Use**: Validation findings, code analysis results, issue classification, diagnostic messages. **Not for log level selection** - when you call `logger.warning()` or `logger.info()`, you are not using `EnumSeverity`. For logging infrastructure requiring numeric level ordering, use `EnumSeverityLevel`. | ||
|
|
||
| **Location**: `src/omnibase_core/enums/enum_severity.py` | ||
|
|
||
| --- | ||
|
|
||
| #### Log Severity (`EnumSeverityLevel`) - Keep Separate | ||
|
|
||
| **Purpose**: RFC 5424-inspired logging levels with numeric ordering. | ||
|
|
||
| **Values**: | ||
| ```python | ||
| class EnumSeverityLevel(str, Enum): | ||
| EMERGENCY = "emergency" # 80 - System unusable | ||
| ALERT = "alert" # 70 - Immediate action required | ||
| CRITICAL = "critical" # 60 - Critical conditions | ||
| ERROR = "error" # 50 - Error conditions | ||
| WARNING = "warning" # 40 - Warning conditions | ||
| NOTICE = "notice" # 35 - Normal but significant | ||
| INFO = "info" # 30 - Informational | ||
| DEBUG = "debug" # 20 - Debug messages | ||
| TRACE = "trace" # 10 - Detailed debug | ||
| FATAL = "fatal" # 80 - Alias for EMERGENCY | ||
| WARN = "warn" # 40 - Alias for WARNING | ||
| ``` | ||
|
|
||
| **Why Keep Separate**: RFC 5424 compliance, numeric level ordering, logging framework integration. | ||
|
|
||
| **Location**: `src/omnibase_core/enums/enum_severity_level.py` | ||
|
|
||
| --- | ||
|
|
||
| #### Business Impact (`EnumImpactSeverity`) - Keep Separate | ||
|
|
||
| **Purpose**: Classify business impact of issues or changes. | ||
|
|
||
| **Values**: | ||
| ```python | ||
| class EnumImpactSeverity(str, Enum): | ||
| CRITICAL = "critical" # Business-critical impact | ||
| HIGH = "high" # Significant business impact | ||
| MEDIUM = "medium" # Moderate business impact | ||
| LOW = "low" # Minor business impact | ||
| MINIMAL = "minimal" # Negligible business impact | ||
| ``` | ||
|
|
||
| **Why Keep Separate**: Different semantic domain (business vs. technical), different usage context. | ||
|
|
||
| **Location**: `src/omnibase_core/enums/enum_impact_severity.py` |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Check if enum source files exist and inspect their definitions
echo "=== EnumExecutionStatus ==="
cat src/omnibase_core/enums/enum_execution_status.py 2>/dev/null || echo "FILE NOT FOUND"
echo -e "\n=== EnumOperationStatus ==="
cat src/omnibase_core/enums/enum_operation_status.py 2>/dev/null || echo "FILE NOT FOUND"
echo -e "\n=== EnumWorkflowStatus ==="
cat src/omnibase_core/enums/enum_workflow_status.py 2>/dev/null || echo "FILE NOT FOUND"
echo -e "\n=== EnumHealthStatus ==="
cat src/omnibase_core/enums/enum_health_status.py 2>/dev/null || echo "FILE NOT FOUND"
echo -e "\n=== EnumLifecycle ==="
cat src/omnibase_core/enums/enum_metadata.py 2>/dev/null || echo "FILE NOT FOUND"
echo -e "\n=== EnumRegistryEntryStatus ==="
cat src/omnibase_core/enums/enum_registry_entry_status.py 2>/dev/null || echo "FILE NOT FOUND"
echo -e "\n=== EnumSeverity ==="
cat src/omnibase_core/enums/enum_severity.py 2>/dev/null || echo "FILE NOT FOUND"
echo -e "\n=== EnumSeverityLevel ==="
cat src/omnibase_core/enums/enum_severity_level.py 2>/dev/null || echo "FILE NOT FOUND"
echo -e "\n=== EnumImpactSeverity ==="
cat src/omnibase_core/enums/enum_impact_severity.py 2>/dev/null || echo "FILE NOT FOUND"Repository: OmniNode-ai/omnibase_core
Length of output: 38503
Sync enum documentation with actual code definitions—multiple values missing or incorrect.
The ADR contains several inaccuracies:
- EnumWorkflowStatus: ADR documents
SIMULATEDbut the actual enum usesPAUSEDinstead - EnumHealthStatus: ADR is missing
INITIALIZINGandDISPOSINGvalues present in the code - EnumSeverityLevel: ADR's documentation is incomplete—RFC 5424 values
TRACE,EMERGENCY,ALERT, andNOTICEare not listed
Update the ADR to reflect the actual enum values. Consider automating this documentation using docstring extraction or a validation tool to prevent future drift between enums and their documentation.
🤖 Prompt for AI Agents
In `@docs/decisions/ADR-006-status-taxonomy.md` around lines 83 - 289, The ADR
enum docs are out of sync with the actual code: update the EnumWorkflowStatus
section to reflect that the code defines PAUSED (not SIMULATED), update
EnumHealthStatus to include INITIALIZING and DISPOSING (in addition to listed
values), and expand EnumSeverityLevel to include the RFC5424 entries TRACE,
EMERGENCY, ALERT, and NOTICE; edit the canonical value lists for
EnumWorkflowStatus, EnumHealthStatus, and EnumSeverityLevel to exactly match the
runtime definitions (EnumWorkflowStatus, EnumHealthStatus, EnumSeverityLevel)
and consider adding a note or a small automation step (docstring extraction or
validation tool) to keep ADRs in sync with the enum declarations.
| > **Navigation**: [Home](../INDEX.md) > Guides > Effect Subcontract Guide | ||
|
|
There was a problem hiding this comment.
Remove blank line inside the blockquote to satisfy MD028.
The blank line right after the > **Navigation** line triggers the no-blanks-blockquote rule. Remove it (or replace with a > line) to keep lint clean.
🛠️ Suggested fix
-> **Navigation**: [Home](../INDEX.md) > Guides > Effect Subcontract Guide
-
+> **Navigation**: [Home](../INDEX.md) > Guides > Effect Subcontract Guide📝 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.
| > **Navigation**: [Home](../INDEX.md) > Guides > Effect Subcontract Guide | |
| > **Navigation**: [Home](../INDEX.md) > Guides > Effect Subcontract Guide |
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
2-2: Blank line inside blockquote
(MD028, no-blanks-blockquote)
🤖 Prompt for AI Agents
In `@docs/guides/EFFECT_SUBCONTRACT_GUIDE.md` around lines 1 - 2, A blank line
inside the blockquote after the line starting with "> **Navigation**:
[Home](../INDEX.md) > Guides > Effect Subcontract Guide" violates MD028; open
EFFECT_SUBCONTRACT_GUIDE.md, locate the blockquote line that begins with ">
**Navigation**" and remove the empty line that follows it (or replace that empty
line with a lone ">" to preserve the blockquote), ensuring there are no blank
lines between consecutive ">"-prefixed lines.
| > **Navigation**: [Home](../../INDEX.md) > [Guides](../README.md) > [Node Building](./README.md) > EFFECT Node Tutorial | ||
|
|
||
| > **Note**: For authoritative coding standards, see [CLAUDE.md](../../../CLAUDE.md). |
There was a problem hiding this comment.
Fix MD028: avoid blank line inside the blockquote.
Markdownlint flags the blank line between blockquote lines. Remove the blank line or keep it as a blockquote line (>).
🛠️ Minimal fix
-> **Navigation**: [Home](../../INDEX.md) > [Guides](../README.md) > [Node Building](./README.md) > EFFECT Node Tutorial
-
-> **Note**: For authoritative coding standards, see [CLAUDE.md](../../../CLAUDE.md).
+> **Navigation**: [Home](../../INDEX.md) > [Guides](../README.md) > [Node Building](./README.md) > EFFECT Node Tutorial
+> **Note**: For authoritative coding standards, see [CLAUDE.md](../../../CLAUDE.md).📝 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.
| > **Navigation**: [Home](../../INDEX.md) > [Guides](../README.md) > [Node Building](./README.md) > EFFECT Node Tutorial | |
| > **Note**: For authoritative coding standards, see [CLAUDE.md](../../../CLAUDE.md). | |
| > **Navigation**: [Home](../../INDEX.md) > [Guides](../README.md) > [Node Building](./README.md) > EFFECT Node Tutorial | |
| > **Note**: For authoritative coding standards, see [CLAUDE.md](../../../CLAUDE.md). |
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
2-2: Blank line inside blockquote
(MD028, no-blanks-blockquote)
🤖 Prompt for AI Agents
In `@docs/guides/node-building/04_EFFECT_NODE_TUTORIAL.md` around lines 1 - 3, The
blockquote in EFFECT_NODE_TUTORIAL has a blank line between quoted lines which
triggers MD028; edit the blockquote in
docs/guides/node-building/04_EFFECT_NODE_TUTORIAL.md (the lines starting with ">
**Navigation**" and "> **Note**") and remove the empty line or convert it to a
blockquote line by prefixing it with ">" so both lines remain contiguous
blockquote lines (e.g., ensure the blank line is either deleted or changed to ">
" to keep the entire quote as a single block).
| | [ADR-012: Validator Error Handling](architecture/adr/ADR-012-VALIDATOR-ERROR-HANDLING.md) | Error handling in validators | | ||
| | [ADR-013: Status Taxonomy](architecture/adr/ADR-013-status-taxonomy.md) | Canonical status enums | |
There was a problem hiding this comment.
Fix ADR links to the architecture/decisions/ directory.
These two links point to architecture/adr/… which is inconsistent with the ADR index path above and likely broken.
🛠️ Suggested fix
-| [ADR-012: Validator Error Handling](architecture/adr/ADR-012-VALIDATOR-ERROR-HANDLING.md) | Error handling in validators |
-| [ADR-013: Status Taxonomy](architecture/adr/ADR-013-status-taxonomy.md) | Canonical status enums |
+| [ADR-012: Validator Error Handling](architecture/decisions/ADR-012-VALIDATOR-ERROR-HANDLING.md) | Error handling in validators |
+| [ADR-013: Status Taxonomy](architecture/decisions/ADR-013-status-taxonomy.md) | Canonical status enums |📝 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.
| | [ADR-012: Validator Error Handling](architecture/adr/ADR-012-VALIDATOR-ERROR-HANDLING.md) | Error handling in validators | | |
| | [ADR-013: Status Taxonomy](architecture/adr/ADR-013-status-taxonomy.md) | Canonical status enums | | |
| | [ADR-012: Validator Error Handling](architecture/decisions/ADR-012-VALIDATOR-ERROR-HANDLING.md) | Error handling in validators | | |
| | [ADR-013: Status Taxonomy](architecture/decisions/ADR-013-status-taxonomy.md) | Canonical status enums | |
🤖 Prompt for AI Agents
In `@docs/INDEX.md` around lines 167 - 168, Update the two ADR links that
currently point to "architecture/adr/…" so they use the correct directory
"architecture/decisions/…": specifically change the link targets for "ADR-012:
Validator Error Handling" and "ADR-013: Status Taxonomy" to point to
architecture/decisions/ADR-012-VALIDATOR-ERROR-HANDLING.md and
architecture/decisions/ADR-013-status-taxonomy.md respectively so they match the
ADR index path.
PR Review: Comprehensive Documentation RewriteOverall Assessment: Approve - This is an excellent documentation modernization that significantly improves developer experience and navigation. SummaryThis PR successfully consolidates and restructures the documentation with:
Strengths1. Navigation Architecture
2. ADR ConsolidationThe new docs/decisions/ structure is exemplary:
Example quality - ADR-012 (868 lines):
3. Link Validation Infrastructure.markdown-link-check.json configuration is well-designed:
4. Documentation Completeness
ObservationsMinor: INDEX.md Net Reduction
Minor: Pre-commit Hook Performance
Good: No Test Coverage Needed
Quality AlignmentPer CLAUDE.md requirements:
Final RecommendationAPPROVE AND MERGE This PR represents a substantial improvement to developer experience with:
Merge Criteria Met
Post-Merge Actions (Optional)
Reviewed by: Claude Sonnet 4.5 |
1 participant
Summary
Comprehensive documentation rewrite providing coherent developer onboarding and navigation for ONEX Core, aligning with the documentation patterns established in omnibase_infra PR #172.
docs/index.mdas central navigation hub with "How to Use These Docs" guidedocs/reference/node-archetypes.mdcovering all 4 node types (EFFECT, COMPUTE, REDUCER, ORCHESTRATOR)docs/reference/contracts.mdwith complete contract.yaml field-by-field referencedocs/decisions/directory with categorized README index.markdown-link-check.jsonfor link validation configuration.pre-commit-config.yamlwith markdown link validation hookdocs/patterns/README.mdas patterns section indexdocs/guides/README.mdas guides section indexNew Documentation Structure
Test plan
Linear
Related to OMN-1375 (omnibase_infra documentation rewrite)
Summary by CodeRabbit
Documentation
Chores
✏️ Tip: You can customize this high-level summary in your review settings.