Feature: Surface Health column in Component Index output

[GitSmart86]

Summary

Archidoc parses the 4-column file table from mod.rs / index.ts files (File | Pattern | Purpose | Health), but the Health column is dropped during compilation. The Component Index in ARCHITECTURE.ai.md outputs Module | Level | Pattern | Description — health data authored by developers is invisible in the compiled output.

This feature request adds Health as a first-class column in archidoc's output, turning the compiled architecture file into a project-wide compliance dashboard.

Motivation

In projects using the Triforce Framework (3-tier orchestration architecture), every file in a mod.rs / index.ts table is annotated with a health value reflecting production readiness and architectural compliance:

Value	Meaning
✅	Production-ready and architecturally compliant
⚠️	Functional with documented trade-off
🔧	Needs remediation
planned	Not yet implemented
—	Health not assessed

This data is already authored at the source level. Archidoc should surface it in compiled output so developers and reviewers can assess project health from a single file without reading every mod.rs.

Proposed Changes

1. Parse Health from file tables

Archidoc already reads the 4-column markdown table in mod.rs / index.ts header comments. Extract column 4 (Health) as a structured field alongside Pattern and Purpose.

2. Add Health column to Component Index

Current output:

| Module | Level | Pattern | Description |

Proposed output:

| Module | Level | Pattern | Health | Description |

3. Aggregate child health to parent modules

When a module's file table contains mixed health values, the module-level health in the Component Index should reflect the worst child:

• Any 🔧 child → module shows 🔧
• Any ⚠️ child (no 🔧) → module shows ⚠️
• All ✅ → module shows ✅
• No health data → module shows —

This surfaces problems at the container level without requiring drill-down.

4. --check validation for Health column

When running archidoc --check, flag any file table entry with a missing or empty Health column as a warning. This makes Health a required field that can be enforced in CI, preventing new files from being added without a health assessment.

5. Mermaid diagram coloring (optional / stretch goal)

In the C4 Component diagram output, optionally color-code components by their aggregated health:

• ✅ → default/green styling
• ⚠️ → yellow/orange styling
• 🔧 → red styling

This turns the architecture diagram into a visual health map.

Example

Source (backend/engine/src/engine/handlers/mod.rs):

//! | File | GoF Pattern(s) | Purpose | Health |
//! |------|----------------|---------|--------|
//! | `orchestrator.rs` | Mediator | Cross-domain capability coordination | ✅ |
//! | `history.rs` | — | Dynamic chart history chunk loading | ⚠️ |
//! | `orders.rs` | — | Order execution via LKAS | ✅ |

Compiled output (Component Index row):

| backend.engine.src.engine.handlers | component | Mediator | ⚠️ | Domain handlers receiving EngineContext |

The ⚠️ aggregates from the history.rs child — one file with a documented trade-off is visible at the module level.

Backwards Compatibility

• Projects that don't use the Health column will show — (no health data) — no breaking change
• The --check validation should be a warning, not an error, so existing projects aren't broken
• Health column in output is additive — existing parsers of the 4-column Component Index will see a new column but won't break (markdown tables are flexible)

Priority

Medium — the data is already being authored manually. This feature makes it visible and enforceable.