TicketLab_MCP/.specify/memory/constitution.md

TicketLab Constitution

Core Principles

I. Spec-Driven Development

All implementation work MUST start from an identified Plane story (or task under that story). Before writing application code, the agent MUST complete specification, clarification of gaps, planning, and task decomposition for the approved scope. The agent MUST implement only that approved scope and MUST NOT expand into out-of-scope capabilities (for this increment: no frontend, auth, attachments, queues, RAG, dashboards, or production deploy unless a future approved story explicitly adds them).

Rationale: TicketLab is an SDD workshop laboratory; the Plane contract for agents and the epic require verifiable, scoped delivery rather than ad-hoc coding.

II. Plane as Requirements Source

Plane is the source of truth for stories, acceptance criteria, Gherkin scenarios, tasks, ADRs, and RFCs (when present). ADRs and RFCs act as binding constraints on design and implementation. Missing, ambiguous, or contradictory information MUST trigger a clarification request. Missing requirements MUST NOT be invented.

Rationale: The agent execution contract lists Gherkin/criteria, ADRs, and related artifacts ahead of code; inventing gaps breaks workshop control and traceability.

III. End-to-End Traceability

Every change MUST preserve a verifiable chain:

Story → acceptance criteria / Gherkin → spec → plan → tasks → code → tests → evidence → Pull Request

Work items, Plane pages (ADRs, matriz, readiness, PR template), Spec Kit artifacts, tests, quality evidence, and the Pull Request MUST be correlatable. Orphan implementation without a Plane story reference is not allowed.

Rationale: The Plane matriz and PR template exist to keep epic, stories, ADRs, and evidence connected through delivery.

IV. Behavior-Oriented Testing

Gherkin scenarios and acceptance criteria in Plane are the origin of behavior tests. Each acceptance criterion MUST have verifiable evidence (automated test and/or recorded operational evidence as required by the story). Changes MUST preserve applicable existing tests. Tests MUST run before review and before opening a Pull Request. External dependencies MUST be exercised with deterministic fakes in the quality gate (no real LLM in CI gate), per ADR-004.

Rationale: The epic requires verifiable behavior via Vitest + Gherkin; ADR-004 mandates Vitest, ESLint, SonarQube Quality Gate, and fake/simulated external dependencies for the gate.

V. Implementation Simplicity

Deliver the smallest solution that fully satisfies the approved specification and binding ADRs. Reuse existing capabilities before introducing new abstractions. New dependencies, layers, or generalizations require demonstrated need from Plane artifacts. Simplicity does not waive validation, error handling, security constraints, or observability requirements.

Rationale: ADR-001 chooses a modular monolith walking skeleton; unnecessary complexity fights the laboratory goals and the agent rule to stay in scope.

VI. Observability

When a change touches an observed flow, the following minimum MUST hold (ADR-003 / TL-03):

• structured JSON logs (Pino);
• Prometheus/OpenMetrics metrics (GET /metrics);
• OpenTelemetry tracing with OTLP export;
• correlation via trace_id / request_id between execution and evidence;
• no ticket description, prompts, raw model responses, or secrets in logs or traces.

Cardinality of metric labels MUST remain controlled. Observability names and detail for a given story remain defined in that story and ADR-003—not invented here.

VII. Quality Before Pull Request

A Pull Request MUST NOT be opened without evidence of, as applicable to the change:

• TypeScript typecheck;
• lint (ESLint);
• tests (Vitest), including coverage when configured for the gate;
• build;
• SonarQube analysis with Quality Gate pass;
• diff review;
• adherence to the approved spec, plan, tasks, ADRs, and RFCs (when present);
• operational evidence required by the story (for example JSON logs, metrics, OTLP spans) and alignment with the OpenAPI contract.

Rationale: TL-03.4, ADR-004, and the Plane PR template require build, lint, tests, Quality Gate, and observable evidence before merge review.

Artifact Authority

Authority	Governs
This Constitution	Permanent development principles and process gates
ADRs (and RFCs when present) in Plane	Specific technical decisions and constraints
Plane stories + acceptance criteria / Gherkin	Requested behavior for an increment
Spec Kit spec.md / plan.md / tasks.md	Derived working artifacts for an approved story; they MUST NOT contradict Plane or this Constitution

Conflict resolution order: Constitution principles → accepted ADRs/RFCs → active story acceptance criteria/Gherkin → derived Spec Kit artifacts → implementation detail. Unresolved conflict MUST stop implementation and request clarification.

Stack and design choices (for example Node.js 22, TypeScript, Fastify, SQLite with better-sqlite3, LiteLLM OpenAI-compatible API, OpenAPI) are recorded in ADRs and Plane pages; they are not restated as mutable constitution clauses.

Governance

1. This Constitution is the authority for permanent principles. Amending it requires an explicit change to .specify/memory/constitution.md, a Sync Impact Report, semantic version bump, and recorded ratification or amendment date.
2. ADRs and RFCs remain in Plane. Do not copy them wholesale into this file; reference them as constraints.
3. Stories, criteria, Gherkin, and tasks remain in Plane and define increment behavior.
4. Versioning uses semantic versions:
   • MAJOR: incompatible removal or redefinition of principles/gates;
   • MINOR: new principle/section or material expansion;
   • PATCH: clarifications and non-semantic wording fixes.
5. Compliance: reviews and Pull Requests MUST verify alignment with this Constitution, applicable ADRs/RFCs, and the active story evidence chain.
6. First effective version was 1.0.0 (ratified 2026-08-11).

Version: 1.0.1 | Ratified: 2026-08-11 | Last Amended: 2026-08-11