# Engineering Principles

This standard owns cross-cutting engineering style for Blueprint code, shell
helpers, markdown standards, regexes, prompts, and workflow tooling.

## DRY Ownership

- Put each rule, lifecycle, schema, command contract, and policy in one
  canonical owner.
- Other files should link or briefly reference the owner instead of duplicating
  long prose.
- If two files disagree, fix the ownership boundary instead of adding a third
  interpretation.
- Prefer small reusable helpers over copy-pasted shell blocks, markdown
  checklists, regular expressions, or prompt fragments.
- Generated summaries and handoffs should point to canonical commands rather
  than restating command logic.

## Functional Core

Prefer a functional-core / imperative-shell shape:

- Keep parsing, validation, classification, rendering, and schema shaping as
  pure and deterministic as practical.
- Isolate side effects: filesystem writes, Git actions, tmux, network calls,
  Telegram sends, daemon execution, and process management should sit at clear
  boundaries.
- Make side-effecting commands idempotent or fail closed when possible.
- Keep inputs and outputs explicit, stable, and machine-readable for AI use.
- Avoid hidden state dependencies unless the state directory and lifecycle are
  documented.

## Regex And Text Processing

- Prefer structured data, JSON, env-style records, or existing parsers over
  brittle regexes.
- When regex is appropriate, keep patterns narrow, named by context, and tested
  with representative examples.
- Do not duplicate complex regexes across files. Put them behind a helper or
  document the canonical owner.
- Treat markdown as an interface: headings, handoff fields, status labels, and
  command examples should be stable enough for tools and humans.

## Runtime And Workflow Tooling

- Trusted runtime state must flow through canonical helpers and scorecards
  rather than prose parsing where possible.
- Registered local/dev actions belong in the trusted operator daemon.
- Missing recurring actions must be registered, not improvised.
- Notifications are informational unless routed through operator Q&A.
- Every new workflow helper should have a narrow command surface, focused
  tests, and a clear owner standard.

## Review Rule

During implementation and QA, check whether the change introduced duplicated
policy, scattered side effects, hidden state, or untested regex/string parsing.
If so, refactor to the canonical owner or document a follow-up blocker.

For QA, this is a core gate for workflow/tooling chunks. A change that
duplicates canonical policy, spreads side effects across unclear boundaries, or
adds brittle untested parsing should be blocked unless the risk is explicitly
accepted as a follow-up by the operator.