feat(validate): ontology policy check (#69 Session 2)

[stackbilt-admin]

Summary

Session 2 of #69 ships the enforcement half of the typed data access policy:

```
charter validate --policy typed-data-access
```

A deterministic commit-time check that loads a data-registry YAML file, scans the current diff for business-concept references, and flags non-canonical alias usage in new code. Built on the Session 1 policy module (#96) and the canonical registry in stackbilt_llc.

What it does

Given this diff:
```ts
export async function handler(tenantId: string) {
const credits = await checkCredits(tenantId);
const quota = await getQuota(tenantId);
const tier = subscription.tier;
}
```

Charter validate reports:
```
[warn] Ontology policy: WARN
4 non-canonical aliases found in 1 changed file.
Registry: .charter/data-registry.yaml (default) | 21 concepts

Referenced concepts:

• quota 4× | edge-auth | cross_service_rpc
• subscription 3× | edge-auth | billing_critical
• user 2× | edge-auth | pii_scoped

Violations (4):

• [WARN] src.ts:2
  Uses alias 'credits' for concept 'quota' (edge-auth, cross_service_rpc).
  Prefer the canonical form in new code.
• [WARN] src.ts:5
  Uses alias 'tier' for concept 'subscription' (edge-auth, billing_critical).

Suggestions:

• Prefer canonical forms in new code: credits → quota, tier → subscription
  ```

Architecture

Pure-logic core (@stackbilt/validate)

• parseOntologyRegistry — minimal YAML subset parser for the registry format. Zero external dependencies.
• checkOntologyDiff — scans changed lines, returns informational references + alias-usage violations
• extractIdentifiersFromLine + stripCommentsAndStrings — language-agnostic tokenization with comment/string stripping. Handles JS/C `//`, YAML/shell `#`, SQL `--`, inline `/* */`, JSDoc continuation lines, and all string literals. Guards against false-stripping URLs (`http://`) and C preprocessor directives (`#include`).
• normalizeToken — unified identifier normalization (lowercase, strip separators) so `tenant_id`, `tenantId`, `TENANT_ID` all match.

CLI surface (@stackbilt/cli)

• validate.ts — new `--policy` dispatcher. Routes to ontology check when policy matches; throws on unknown policies.
• validate-ontology.ts — CLI wrapper:
  • Loads registry via --registry flag, config, or default path
  • Parses git diff --unified=0 to extract added lines only
  • Applies per-repo alias ignore list
  • Skips test files and fixture dirs by default (`--scan-tests` to opt back in)
  • Formats output as text or JSON
  • Exit codes: 0 on PASS, 0 on WARN (without --ci), 1 on WARN+--ci or FAIL

Config (`.charter/config.json`)

```jsonc
{
"ontology": {
"registry": ".charter/data-registry.yaml",
"ignoreAliases": ["token", "key", "usage", "audit"]
}
}
```

Two iterations after initial ship

Dogfooding the first iteration against charter's own source tree surfaced two classes of false positives:

1. JSDoc continuation lines

Multi-line block comments (`/** ... /`) weren't stripped because each line was processed independently. Lines like ` tiers and sensitivity levels` in JSDoc prose were tokenized as code. Fixed by treating lines starting with `*` or `/**` as full-line comments (with multiplication guard).

2. Generic alias collisions

Aliases like `token`, `key`, `usage`, `tier`, `audit` collide with common programming vocabulary. Charter's own codebase uses these words in their programming sense (lexer tokens, map keys, resource usage). Every file containing the word was getting flagged.

Fix: added `ontology.ignoreAliases` per-repo config field. Registry stays authoritative ecosystem-wide, but individual repos can opt out of specific noisy alias tokens without touching the shared source of truth.

Charter's own `.charter/config.json` ignores: `token, tokens, key, keys, usage, audit, tier, plan, limit, limits`.

Validation

Unit tests (45 new, 399 total)

• Registry parsing (comments, flow sequences, null tables, malformed input)
• Identifier extraction (// comments, # comments, SQL --, JSDoc, string literals)
• URL/preprocessor guards
• Alias detection, canonical vs alias counts
• Dedup within a line
• Per-repo ignore list
• Multiplication vs JSDoc distinction

End-to-end dogfood

• Fixture test: a 7-line handler with 4 alias usages + 3 canonical → reports exactly 4 violations, 0 false positives
• Charter self-scan: 916 added lines across 5 files on this branch → PASS, 0 violations after tuning

Full suite

• 399/399 charter tests passing (+45)
• Build clean, typecheck clean
• `pnpm run verify:adf` all PASS

What's NOT in this PR (deferred to Session 3+)

• FAIL-severity rules — detecting raw D1 access to other services' tables (needs AST-ish parsing)
• Unregistered-concept heuristic — flag identifiers that LOOK like business terms but aren't in the registry at all
• charter doctor integration — standing health checks for registry configuration
• Registry cleanup PR in stackbilt_llc — narrow the noisy aliases upstream so downstream repos don't need ignore lists (filing as follow-up)

References

• Closes part of feat: Typed Data Access & Disambiguation Policy — ontology enforcement across Stackbilt repos #69 (Session 2 of 4)
• Session 1 (policy module): charter#96
• Session 3 follow-up: registry cleanup in stackbilt_llc (TBD issue)
• Registry source: Stackbilt-dev/stackbilt_llc/policies/data-registry.yaml
• Downstream: aegis disambiguation firewall, codebeast DATA_AUTHORITY

Governed-By: #69

🤖 Generated with Claude Code