ratchet(ts-persona): forbidden-strings monotonic-decrease gate (Lane F PR-2)

[joelteply]

Summary

Per-pattern monotonic-decrease ratchet on src/system/user/server/,
mirroring PR #1091's LOC ratchet shape. Companion gate to #1091 — same
shell+python implementation, same independent CI workflow (~5s).

Tracked patterns

Pattern	Baseline	Rationale
fallback_mention (case-insensitive)	83	Joel 2026-04-22: "fallbacks have ruined this project ... they are ILLEGAL." The WORD count proxies conceptual presence; comments saying "no fallback here" count too.
direct_adapter_instantiation (new <Name>Adapter()	12	TS surface should request providers via the ModelRequirement → ResolvedModel resolver shipped in #1066/#1074, not instantiate adapters directly.
direct_api_key_env_read (process.env.*API_KEY)	0	Cloud key lookup belongs in the Rust provider registry per Codex's #1077 boundary. Locks 0 in.

Any pattern growing fails CI; shrinkage allowed and surfaces a hint to
--update-baseline post-merge.

Files

• scripts/ratchets/check-ts-persona-forbidden-strings.sh (~180 LOC, bash + python only — 3 modes: default check / --update-baseline / --verbose)
• scripts/ratchets/ts-persona-forbidden-strings-baseline.json (per-pattern config + rationale, anchored at canary 83513e6)
• .github/workflows/ts-persona-forbidden-strings-ratchet.yml (mirrors ratchet(ts-cognition): add TS persona-cognition deletion ratchet (Lane F) #1091's workflow shape; PR + push triggers on canary/main)
• docs/architecture/TS-PERSONA-COGNITION-RATCHET.md (extends ratchet(ts-cognition): add TS persona-cognition deletion ratchet (Lane F) #1091's doc with the new gate)

Local validation

Scenario	Result
Clean tree (canary 83513e6)	PASS — 3 patterns hold at baseline
Inject // fallback fallback in UserEntityCache.ts	FAIL with ❌ fallback_mention: baseline=83 current=85 delta=+2 + actionable Rust target paths
Restore tree	PASS again
--update-baseline mode	rewrites baseline_count + sha + iso to current
--verbose mode	prints first 5 occurrences per pattern with line numbers

Out of scope (followups, named in #1091)

• Verb-shape detection (cognition VERBS in TS even when LOC drops)
• Pre-commit hook integration after CI-only ratchets have been live ~1 week

Test plan

• CI gate passes on this PR (zero growth — only adds new files)
• Local FAIL path validated (intentional growth detected with named pattern + delta)
• Local PASS path validated (clean tree + restored after intentional growth)
• --update-baseline and --verbose modes validated
• After merge: any subsequent PR adding a tracked-pattern occurrence under src/system/user/server/ should fail this gate

🤖 Generated with Claude Code

[joelteply]

Mac peer review — LGTM, ship.

Strengths:

• Same shape as ratchet(ts-cognition): add TS persona-cognition deletion ratchet (Lane F) #1091 (shell+python, baseline JSON, GHA workflow, docs) — consistency principle
• Per-pattern monotonic decrease (each can only go DOWN) — same ratchet semantics
• 3 patterns with structured rationale per pattern (Joel quote for fallback, ModelRequirement path for adapter instantiation, Codex's refactor(persona): fail hard on missing model selection #1077 boundary for API key)
• direct_api_key_env_read baseline=0 LOCKS IN current cleanliness — any PR adding process.env.OPENAI_API_KEY style read in persona surface fails CI immediately. Strong gate.
• Tests properly excluded via --exclude=*.test.ts --exclude=*.spec.ts so test-side fixtures don't trip the gate
• || true after grep is correctly justified in comment (grep returns 1 on zero matches — that's valid counter behavior, not silent error suppression). Per Joel's "swallow only expected-noise case" rule, this is the right pattern.

One observation (intentional per rationale, NOT a blocker):
fallback_mention regex "fallback" case-insensitive is intentionally aggressive — counts comments like "no fallback here" or "removed fallback" too. Rationale acknowledges this. Trade-off: pedagogically might frustrate devs who legitimately need to discuss historical fallback removal in a comment. As long as baseline 83 trends DOWN it's fine; the friction creates the right incentive. Worth watching whether it produces sour PR experiences in week 1.

LGTM. Ship.