TicketLab_MCP/.specify/memory/constitution.md

<!--
Sync Impact Report
- Version change: 1.0.0 → 1.0.1
- Modified principles: none (clarification only)
- Added sections: none
- Removed sections: none
- Follow-up TODOs:
  - TODO(RFC): no RFC pages found in Plane Workshop SDLC; confirm whether RFCs will be introduced
  - Gherkin: Plane page "TicketLab — Cenários Gherkin" authored from matriz + TL-01/02/03 (2026-08-11); linked on epic and stories
-->

# 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:

```text
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