Add a Scoring Rule

The scoring engine is deterministic and lives in kredal-app/src/lib/scoring/. After the Phase 2 refactor, rules are declarative data in rules.ts, consumed by engine.ts and rendered into the scoring reference by a generator.

Anatomy of a rule

Each rule belongs to one of the seven categories and specifies:

• a condition over the ScoringInput (company, owners, documents, questionnaire answers),
• a deduction (points removed from that category's max when the condition is true),
• a severity (high / medium),
• an issue (what is wrong, in plain language),
• a fix (the exact action the founder should take).

Steps

1. Add the rule to the appropriate category in src/lib/scoring/rules.ts. Keep the deduction within the category's remaining budget (categories are 25/15/15/15/10/10/10 = 100 points total). Use the same plain, verdict-first language as existing issues.

2. Add a unit test in src/lib/scoring/engine.test.ts. Follow the existing pattern: build a ScoringInput that triggers your rule and assert the flag appears with the right severity, plus assert the category score drops. Keep all existing tests green.

   cd kredal-app && npm test

3. Regenerate the reference doc so reference/scoring-engine.md reflects the new rule:

   npm run docs:gen

   CI runs this and fails if the generated doc is stale, so do not skip it.

4. Rebuild to confirm nothing else broke:

   npm run build

Guidance

• Prefer many small, explainable rules over one opaque rule — explainability is the product.
• Never introduce a rule whose fix a founder cannot act on.
• Do not change category weights without an ADR; they map to the risk-band UI and the design tokens.