stargue-publishing-engine/.clinerules/12-foundational-principles.md

12 — Foundational Principles (Non-Negotiable)

Status: Active doctrine. Enforced by .claude/hooks/gate-plan-exit.sh and the /bmad-plan skill.

Every implementation plan and the execution of that plan MUST satisfy these principles. They apply to BMAD workflows, ad-hoc fixes, refactors, and tooling work alike.

---

Two-Tier Model

Principles are split into two tiers to keep the rubric discriminating instead of ritualistic.

Tier	When scored	Hook behaviour
Tier-1 (Always)	Every verdict, every plan	Hook denies ExitPlanMode if any verdict scores any tier-1 principle <3 or omits its rationale.
Tier-2 (Conditional)	Only when declared applicable_tier2 for the plan	Hook denies ExitPlanMode if a declared tier-2 principle is unscored, scored <3, or has no rationale.

The Analyst (Mary) declares applicable_tier2 at the end of Phase 1 (plan draft). The list lives at the top of the verdicts file:

{
  "plan_file": "<path>",
  "applicable_tier2": ["RBR", "A11y"],
  "verdicts": [ … ]
}

Allowed tier-2 values: RBR, A11y, Testability. Any other value causes the hook to deny.

---

Tier-1 Principles (always scored)

SEBP — Software Engineering Best Practices

Definition: SOLID (single-responsibility, open-closed, Liskov, interface-segregation, dependency-inversion), DRY, separation of concerns, clear module boundaries.

Score 1 (violation): duplicated logic across files; god-objects; leaky abstractions; mixed concerns (e.g., a route handler that also formats PDFs and writes audit logs inline). Score 3 (adequate): clean enough; no immediate smell; reviewer would not block. Score 5 (exemplary): composition over inheritance; each unit has one reason to change; boundaries documented in code shape, not just comments.

Acceptance signals: named exports with single responsibility; no copy-pasted blocks ≥6 lines; route handlers delegate to src/lib/* modules.

SSoT — Single Source of Truth

Definition: every concept (constant, type, schema, config, secret, user-facing string, status enum) has exactly one authoritative location.

Score 1: the same constant or enum is duplicated in two or more files; type drift between API and DB; magic numbers in components. Score 3: core domain types/constants centralised; minor leakage acceptable when behind a TODO or feature-flag. Score 5: generated artifacts (Prisma client, OpenAPI types) flow from a single schema; constants live in src/lib/constants/*; i18n strings in one bundle.

Acceptance signals: no const RETRY_LIMIT = 3 defined in two files; Zod schemas re-used (not re-declared) on both client and server; status enums imported from one module.

FPT — First Principle Thinking

Definition: reasoning grounded in this codebase, this stack version, and verified docs — not training-data assumptions or generic patterns.

Score 1: "Next.js v15 probably does X" without checking; copy-pastes a pattern that doesn't fit the project's existing shape; ignores Memory-Bank lessons. Score 3: cites at least one file or doc; checks a non-obvious assumption. Score 5: identifies the actual constraint, not the symptom; runs probes (small scripts, type-checks) to verify before committing to a design; references prior incidents in memory-bank/systemPatterns.md.

Acceptance signals: plan references concrete file paths; cites Tailwind v4 / Prisma 6 / NextAuth v5 docs (not v3 patterns); names the prior pattern being followed or deliberately diverged from.

DiDSP — Defense in Depth Security Practices

Definition: multiple independent layers of defence: input validation, authentication, authorization, rate limiting, audit logging, least privilege, output encoding.

Score 1: unvalidated user input reaches the database; missing authz on a sensitive operation; secrets in public/; tokens logged; SQL/HTML built by string concatenation. Score 3: Zod validation + authn + authz on all touched API routes; secrets via env; no obvious OWASP top-10 hole. Score 5: layered controls (Cerbos policy + route guard + DB constraint); audit log on sensitive ops; rate limit on abuse-prone endpoints; structured error responses that don't leak internals.

Acceptance signals: every new src/app/api/**/route.ts calls a Zod parse; every auth() call is paired with a Cerbos check for authz; no console.log of tokens, PII, or secrets; sensitive assets out of public/.

PbD — Privacy by Design

Definition: GDPR Article 25 — data minimisation, purpose limitation, retention limits, lawful basis, transparency, user rights (access, portability, erasure, rectification).

Score 1: collects PII without a documented purpose; retains indefinitely; no consent record for a new processing activity; identity documents accessible without authn; cross-tenant data leakage possible. Score 3: new fields have a documented purpose; consent is recorded if required; deletion path exists; no obvious GDPR regression. Score 5: data minimisation actively reduces surface area; retention timer wired to lifecycle; consent versioning supports SAR/portability/erasure flows; brand-agnostic (no tenant cross-leakage); DPIA reasoning in the plan if processing is high-risk.

Acceptance signals: new PII columns have a retention policy reference; consent records updated when processing scope changes; SAR/erasure paths tested; identity-document endpoints require authn + authz + audit; no PII in URLs, logs, or error messages.

OF — Observability First

Definition: every meaningful boundary emits structured signals (logs, metrics, traces, audit) sufficient to diagnose failure without re-running the operation.

Score 1: silent failure paths; bare try/catch that swallows errors; no log on auth/OCR/PDF/contract events; debugging requires re-creating user state. Score 3: errors logged with context; key state transitions emit a record; oncall can locate a failure within minutes. Score 5: structured logs (JSON, correlation IDs); audit trail for regulated ops (consent changes, document state, contract status); user-facing errors carry a trace ID; dashboards/alerts referenced in the plan when introducing new failure modes.

Acceptance signals: new background jobs log start/finish/error with correlation ID; new state machines emit one event per transition; new third-party calls log latency and outcome; PII redacted from logs.

---

Tier-2 Principles (conditional)

Declare in applicable_tier2 when relevant. Score on the same 1–5 scale; ≥3 required when declared.

RBR — Reversibility / Blast Radius

When to declare: the plan touches migrations, deletes, third-party calls (email, SMS, payment, signing), shared infrastructure, CI/CD, production data, or any irreversible state change.

Score 1: destructive operation with no rollback path; one-way migration with no shadow column; bulk delete without dry-run. Score 3: rollback strategy named; non-prod rehearsal planned. Score 5: expand-then-contract migration; feature flags gate rollout; bulk operations are batched and resumable; every irreversible step has a guard, an audit record, and a documented recovery procedure.

A11y — Accessibility (WCAG 2.2 AA)

When to declare: the plan introduces or significantly changes user-facing UI, forms, navigation, or content presentation.

Score 1: keyboard-trap; missing labels; colour-only state; non-semantic markup; forms without error association. Score 3: semantic HTML; visible focus; labels on inputs; passes axe-core baseline. Score 5: keyboard parity with mouse; aria-live where dynamic; respects prefers-reduced-motion; meets contrast ratios on all themes; tested with a screen reader.

Testability

When to declare: the plan introduces or significantly changes business logic, domain rules, or system boundaries that future tests must reach.

Score 1: logic embedded in framework callbacks (Server Components, route handlers) with no extraction; hidden globals; non-deterministic clocks/IDs. Score 3: pure functions extracted into src/lib/*; clock/ID/randomness injectable; tests can call the unit without booting the framework. Score 5: seams expose every branch; fakes/spies straightforward; integration boundaries (DB, external APIs) covered by either real-DB tests or contract tests; no mocks where the real thing fits.

---

Cross-cutting expectations (apply to all principles)

• Plan rationale must cite evidence. "Score 4" alone is not a verdict; the rationale must reference a file, a behaviour, or a decision in the plan.
• Tie-break: when a principle conflicts with another (e.g., DiDSP suggests a layer that hurts SSoT), the plan must name the trade-off explicitly. The reviewer should score resolution quality, not pretend there is no tension.
• No retrofitting scores. Do not raise a score after-the-fact to satisfy the gate; revise the plan instead.

---

Review-process integration

1. Phase 1 (Draft) — author writes the plan and selects applicable_tier2. The plan file should include a short Applicability line stating which tier-2 principles apply and why.
2. Phase 2 (Panel) — each of the 7 BMAD agents (analyst, architect, pm, sm, ux-designer, dev, tea) returns a verdict. Every verdict scores all tier-1 principles + every declared tier-2 principle.
3. Phase 3 (Verdicts file) — write /tmp/bmad-panel-verdicts-<session_id>.json with the schema in the skill.
4. Phase 4 (Consolidate) — address every score <3 in the plan; re-engage the dissenting agent if needed.
5. Phase 5 (Exit) — call ExitPlanMode; the hook validates and approves.

---

Anti-patterns

• Score-inflation: raising scores to clear the gate without revising the plan. The next reviewer will catch it; trust will erode.
• Tier-2 over-declaration: declaring every tier-2 principle on every plan dilutes the signal. Only declare what genuinely applies.
• Tier-2 under-declaration to bypass review: if the plan touches migrations, declare RBR. If it touches UI, declare A11y. If it changes domain logic, declare Testability. The Analyst (Mary) is responsible; gaming this defeats the doctrine.
• Treating principles as a checklist: the rubric exists to surface real tensions and trade-offs. A plan that scores 5 on all six tier-1 principles without acknowledging any trade-off is suspect.

---

Precedence

This file ranks below CLAUDE.md and the documentation-lifecycle / feature-tracking / agent-mode protocols, and above the language-and-framework standards. See CLAUDE.md > Conflict Resolution Precedence for the full ordering.