Concerns

Concerns are composable cross-cutting declarations from a shared library. They encode technology choices, quality requirements, and conventions that apply across multiple beads and phases.

How Concerns Work

1. Select — During Frame, declare active concerns in docs/helix/01-frame/concerns.md
2. Filter — Each concern declares which areas it applies to (all, ui, api, data, infra, cli)
3. Inject — At execution time, area-matched concerns and their practices are loaded into context
4. Digest — Context digests carry concern practices into beads, making them self-contained

Project Concerns File

Every HELIX project declares its concerns in docs/helix/01-frame/concerns.md:

# Project Concerns

## Active Concerns
- rust-cargo (tech-stack)
- security-owasp (security)

## Area Labels
| Label | Applies to |
|-------|-----------|
| all   | Every bead |
| api   | Server, endpoints |
| cli   | CLI tool |

## Project Overrides
### rust-cargo
- **MSRV**: 1.75 (lower than library default)

Project overrides take full precedence over library defaults.

Concern Library

The library lives at workflows/concerns/. Each concern has two files:

• concern.md — Category, areas, components, constraints, quality gates
• practices.md — Phase-specific practices (requirements, design, implementation, testing)

Tech Stack Concerns

Security Concerns

Observability Concerns

Accessibility Concerns

Internationalization Concerns

Quality Concerns

Testing Concerns

Infrastructure Concerns

Tooling Concerns

Drift Signals

Tech-stack concerns can declare drift signals — patterns that indicate the project is straying from its declared technology choices. For example, the typescript-bun concern flags:

• npm run instead of bun run
• prettier or eslint instead of Biome
• vitest or jest instead of bun:test
• @hono/node-server instead of Bun.serve()
• engines.node in package.json

Review and align check for drift signals and report them as findings.

Concerns in the Knowledge Chain

Concerns connect to other HELIX artifacts in a knowledge chain:

Spike/POC (gather evidence)
  → ADR (record decision with rationale)
    → Concern (index for context assembly)
      → Context Digest (injected into beads)

When a referenced ADR is superseded, polish flags the affected concern for re-evaluation.

Where Concerns Are Used

Every HELIX action that involves technology or quality choices loads active concerns: