saqib mirandClaude Sonnet 5
c61b78fcd1
Adds the specify CLI's .specify/ scaffolding (templates, PowerShell automation scripts, constitution memory) and the .claude/skills/speckit-* slash commands for spec-driven development (constitution, specify, clarify, plan, tasks, checklist, analyze, implement, converge). Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
143 lines
9.0 KiB
Markdown
143 lines
9.0 KiB
Markdown
<!--
|
||
Sync Impact Report
|
||
Version change: [TEMPLATE] → 1.0.0 (initial ratification)
|
||
Modified principles: n/a (first concrete version; template placeholders replaced)
|
||
Added sections:
|
||
- Core Principles I–VIII (SaaS identity authority, configuration over hardcoding,
|
||
layered architecture/module boundaries, AI-recommends/policy-decides, evidence-based
|
||
verification, durable audit & history, concurrency-safe job handling, ticket/problem
|
||
separation)
|
||
- Technology & Platform Constraints
|
||
- Testing, Observability & CI/CD Gates
|
||
- Governance
|
||
Removed sections: none (placeholders only)
|
||
Deferred items:
|
||
- TODO(RATIFICATION_DATE): original adoption date predates this codified constitution
|
||
and was not recorded; using first-codification date as a placeholder until the team
|
||
confirms the true ratification date.
|
||
Templates requiring follow-up: none checked yet — run speckit-specify/plan/tasks next
|
||
and verify they don't reference stale template placeholder names.
|
||
-->
|
||
|
||
# SupportHub Constitution
|
||
|
||
## Core Principles
|
||
|
||
### I. SaaS Is the Sole Identity & Access Authority (NON-NEGOTIABLE)
|
||
SupportHub MUST NOT duplicate, shadow, or re-implement SaaS user identity, tenant identity,
|
||
product access, subscriptions, permissions, or authentication. It integrates with the owning
|
||
SaaS via secure APIs and per-product integration credentials, and stores only external
|
||
references (`externalUserId`, `externalTenantId`, `externalProductId`). SupportHub is the
|
||
sole authority only for its own domain: tickets, problems, support org structure, routing/
|
||
assignment, SLA, escalation, investigation/root cause/solution/verification/resolution,
|
||
knowledge, and support audit. Rationale: a second, drifting identity/RBAC system is worse
|
||
than no system — it creates authorization ambiguity. Exactly one source of truth per concern
|
||
keeps that ambiguity from existing.
|
||
|
||
### II. Configuration Over Hardcoding
|
||
Support hierarchy, SLA values, escalation paths, routing rules, and assignment strategy MUST
|
||
be admin-configurable data, never hardcoded in application code. Anything the business can
|
||
legitimately change without a deploy MUST be driven by configuration or persisted state, not
|
||
by editing source. Rationale: these policies change on business cadence, not engineering
|
||
cadence; hardcoding them forces a deploy for every policy tweak and makes non-engineers
|
||
dependent on engineering for routine changes.
|
||
|
||
### III. Layered Architecture With Enforced Module Boundaries
|
||
Every module follows Route → Schema validation → Controller → Service → (Engine/Rules if
|
||
required) → Repository → Prisma → PostgreSQL. Controllers MUST NOT touch Prisma or contain
|
||
business logic; routes MUST NOT contain business logic; the repository is the only layer
|
||
permitted to call Prisma. A module's internals are reachable only through its own public
|
||
`index.ts` — no deep cross-module imports, no circular module dependencies, no giant global
|
||
services. Rationale: this is what keeps a modular monolith splittable later without a rewrite,
|
||
and what makes module boundaries reviewable rather than aspirational.
|
||
|
||
### IV. AI Recommends, Deterministic Policy Decides
|
||
The AI Support Agent MUST NOT receive unrestricted backend access, MUST NOT invent
|
||
troubleshooting steps or product behavior beyond retrieved knowledge, and MUST NOT execute a
|
||
high-risk action without an explicit permission/policy check — regardless of the model's
|
||
reported confidence. Tool execution is scoped and enforced by deterministic policy code, never
|
||
left to model judgment alone. Rationale: the LLM proposes a diagnosis or action; policy code is
|
||
the actual authority. This is what makes running AI-first support against production systems
|
||
safe.
|
||
|
||
### V. Evidence-Based Verification
|
||
A problem MUST NOT be marked resolved on the customer's say-so alone wherever a system signal
|
||
is available to check the outcome. Recording a resolution requires verification evidence
|
||
attached to the ticket/problem, not just a customer confirmation click. Rationale: customer
|
||
"yes, it's fixed" clicks on problems that recur erode trust in both the AI and human resolution
|
||
paths; evidence is what separates a genuinely closed loop from a hopeful one.
|
||
|
||
### VI. Durable Audit & History
|
||
All important operations — assignment, escalation, SLA transitions, resolution, AI tool calls —
|
||
MUST be audit-logged. Full AI session history and full resolution history MUST be preserved,
|
||
never overwritten or summarized away. Every log line MUST carry a request ID/correlation ID so
|
||
a single ticket's full journey (AI session → tool calls → escalation → assignment → SLA events)
|
||
is traceable end to end. Rationale: admin trust, dispute resolution, and debugging all depend on
|
||
nothing about a ticket's journey being silently lost.
|
||
|
||
### VII. Concurrency-Safe, Durable Job Handling
|
||
SLA enforcement MUST NOT rely on in-memory timers (e.g. `setTimeout`) — enforcement state MUST
|
||
survive a process restart. Assignment and escalation logic MUST be tested under concurrency
|
||
(e.g. two tickets assigned simultaneously must never double-assign or corrupt round-robin
|
||
state), and job handlers MUST be idempotent (a rule firing twice must not create duplicate
|
||
events). Large files (attachments) MUST NOT be stored in PostgreSQL — use object storage.
|
||
Rationale: assignment and SLA are correctness-critical under real concurrent load; treating them
|
||
as single-threaded conveniences is how double-assignment and missed SLA breaches happen in
|
||
production.
|
||
|
||
### VIII. Problem and Ticket Are Separate, Related Entities
|
||
"Ticket" (the durable, customer-facing record created immediately when a problem is reported)
|
||
and "Problem" (the thing being diagnosed and investigated) MUST remain distinct, related
|
||
entities — never collapsed into one model. Rationale: a ticket exists before diagnosis begins
|
||
and can outlive multiple problem/investigation cycles; merging the two loses that lifecycle
|
||
distinction and makes the AI-first flow (ticket created at `NEW`, before AI even starts) harder
|
||
to represent correctly.
|
||
|
||
## Technology & Platform Constraints
|
||
|
||
- Stack: Node.js + TypeScript, Fastify, PostgreSQL + Prisma, Redis + BullMQ, Pino (structured
|
||
logging), OpenAPI, Zod (validation), Vitest, Docker.
|
||
- Architecture style: modular monolith. Do not decompose into microservices prematurely —
|
||
the module boundaries required by Principle III exist to make a future split *possible*,
|
||
not to justify doing one now.
|
||
- Standard module shape: `controller/ routes/ schema/ repository/ service/ types/ mapper/
|
||
constants/ index.ts`. Modules with real decision logic (not just CRUD) additionally use
|
||
`engine/ rules/ strategies/ calculators/`.
|
||
|
||
## Testing, Observability & CI/CD Gates
|
||
|
||
- Required backend test categories: unit, integration, E2E, concurrency (assignment races),
|
||
SLA (pause/resume correctness, business-calendar math, durability across a simulated process
|
||
restart), escalation idempotency, orchestration (capability matching, hierarchy traversal,
|
||
strategy selection), and AI tool-permission tests (the AI must never invoke a tool it isn't
|
||
scoped for; high-risk tools require policy/approval regardless of AI confidence).
|
||
- Two critical end-to-end scenarios MUST exist as automated tests at all times: (A) AI resolves
|
||
directly — problem → knowledge → guided troubleshooting → verification → AI-resolved; (B) AI
|
||
escalates to human — problem → failed AI troubleshooting → escalation → orchestration →
|
||
assignment → SLA → investigation → solution → verification → resolution → closure.
|
||
- Observability is wired in from the start, not retrofitted: Pino structured logs with a
|
||
request ID and correlation ID on every line; `GET /health`, `GET /health/live`,
|
||
`GET /health/ready`, `GET /metrics` exposed from day one.
|
||
- CI (Jenkins) MUST run, in order: checkout → install → environment validation → typecheck →
|
||
lint → format check → unit test → integration test → E2E test → build → Docker build →
|
||
publish → deploy. Production deployments use protected Jenkins-managed credentials; real
|
||
secrets are never committed to the repository.
|
||
|
||
## Governance
|
||
|
||
This constitution supersedes ad hoc conventions and undocumented team habits. All PRs and code
|
||
reviews MUST verify compliance with the principles above before merge.
|
||
|
||
Amendments require: a documented rationale for the change, a version bump under the semantic
|
||
versioning rule below, and an updated Sync Impact Report prepended to this file. MAJOR = a
|
||
backward-incompatible principle removal or redefinition. MINOR = a new principle added, or
|
||
existing guidance materially expanded. PATCH = clarification, wording, or typo fixes with no
|
||
semantic change. Any exception to a MUST/MUST NOT rule requires explicit written justification
|
||
in the relevant PR description and is expected to be rare, not routine.
|
||
|
||
Detailed product and system design lives in `docs/00-INDEX.md` through
|
||
`docs/10-implementation-roadmap.md` — this constitution states the non-negotiable engineering
|
||
rules; the docs explain the full system those rules protect.
|
||
|
||
**Version**: 1.0.0 | **Ratified**: TODO(RATIFICATION_DATE): confirm original adoption date | **Last Amended**: 2026-08-21
|