docs(constitution): update principles and add implementation gates

# [PROJECT_NAME] Constitution

<!-- Example: Spec Constitution, TaskFlow Constitution, etc. -->

<!--

Sync Impact Report:

- Version change: unversioned -> 1.0.0

- Modified principles: Placeholder Principle 1 -> I. Library-First Development; Placeholder Principle 2 ->

  II. CLI Text + JSON Interface; Placeholder Principle 3 -> III. Test-Driven Development (Non-Negotiable)

- Added sections: Implementation Gates; Development Workflow

- Removed sections: Core Principles item 4; Core Principles item 5

- Templates requiring updates:

  - UPDATED: .specify/templates/plan-template.md

  - UPDATED: .specify/templates/spec-template.md

  - UPDATED: .specify/templates/tasks-template.md

  - PENDING: .specify/templates/commands/*.md (directory not present)

- Follow-up TODOs: None

-->

# tdoc-crawler Constitution

## Core Principles

### [PRINCIPLE_1_NAME]

<!-- Example: I. Library-First -->

[PRINCIPLE_1_DESCRIPTION]

<!-- Example: Every feature starts as a standalone library; Libraries must be self-contained, independently testable, documented; Clear purpose required - no organizational-only libraries -->

### I. Library-First Development

Every feature must start as a standalone, reusable library component. Application or CLI

code may only call into this library; direct feature implementation inside application

modules is prohibited. Libraries must be independently testable and have a clear,

reusable interface.

### [PRINCIPLE_2_NAME]

<!-- Example: II. CLI Interface -->

[PRINCIPLE_2_DESCRIPTION]

<!-- Example: Every library exposes functionality via CLI; Text in/out protocol: stdin/args → stdout, errors → stderr; Support JSON + human-readable formats -->

### II. CLI Text + JSON Interface

Every library must expose its functionality through a command-line interface. Each CLI

must accept text input via stdin, arguments, or files, and must emit text output via

stdout. Every CLI must support a JSON output mode for structured data exchange; errors

go to stderr.

### [PRINCIPLE_3_NAME]

<!-- Example: III. Test-First (NON-NEGOTIABLE) -->

[PRINCIPLE_3_DESCRIPTION]

<!-- Example: TDD mandatory: Tests written → User approved → Tests fail → Then implement; Red-Green-Refactor cycle strictly enforced -->

### III. Test-Driven Development (Non-Negotiable)

Implementation code must not be written until unit tests are written, reviewed by the

user, and explicitly approved. The approved tests must be executed and verified to fail

(red phase) before any implementation begins. Development must follow the

red-green-refactor cycle for each change.

### [PRINCIPLE_4_NAME]

<!-- Example: IV. Integration Testing -->

[PRINCIPLE_4_DESCRIPTION]

<!-- Example: Focus areas requiring integration tests: New library contract tests, Contract changes, Inter-service communication, Shared schemas -->

## Implementation Gates

### [PRINCIPLE_5_NAME]

<!-- Example: V. Observability, VI. Versioning & Breaking Changes, VII. Simplicity -->

[PRINCIPLE_5_DESCRIPTION]

<!-- Example: Text I/O ensures debuggability; Structured logging required; Or: MAJOR.MINOR.BUILD format; Or: Start simple, YAGNI principles -->

- Gate 1: A standalone library interface exists and is planned before any application

  integration.

- Gate 2: The library CLI contract includes text input/output and JSON output support.

- Gate 3: Unit tests are written, user-approved, and verified failing before

  implementation begins.

## [SECTION_2_NAME]

<!-- Example: Additional Constraints, Security Requirements, Performance Standards, etc. -->

## Development Workflow

[SECTION_2_CONTENT]

<!-- Example: Technology stack requirements, compliance standards, deployment policies, etc. -->

## [SECTION_3_NAME]

<!-- Example: Development Workflow, Review Process, Quality Gates, etc. -->

[SECTION_3_CONTENT]

<!-- Example: Code review requirements, testing gates, deployment approval process, etc. -->

- Feature specs and plans must document the library boundary, CLI I/O contract, and TDD

  evidence.

- Code reviews and CI checks must verify the gates above; exceptions require a

  constitution amendment.

## Governance

<!-- Example: Constitution supersedes all other practices; Amendments require documentation, approval, migration plan -->

[GOVERNANCE_RULES]

<!-- Example: All PRs/reviews must verify compliance; Complexity must be justified; Use [GUIDANCE_FILE] for runtime development guidance -->

- This constitution supersedes all other guidance for feature work.

- Amendments require a documented proposal, explicit user approval, and a version bump

  following semantic versioning (MAJOR for removals/redefinitions, MINOR for additions,

  PATCH for clarifications).

- Compliance is verified in specs, plans, task lists, and code reviews; non-compliant

  changes must be blocked or accompanied by an approved amendment.

**Version**: [CONSTITUTION_VERSION] | **Ratified**: [RATIFICATION_DATE] | **Last Amended**: [LAST_AMENDED_DATE]

<!-- Example: Version: 2.1.1 | Ratified: 2025-06-13 | Last Amended: 2025-07-16 -->

**Version**: 1.0.0 | **Ratified**: 2026-02-05 | **Last Amended**: 2026-02-05

**Branch**: `[###-feature-name]` | **Date**: [DATE] | **Spec**: [link]

**Input**: Feature specification from `/specs/[###-feature-name]/spec.md`

**Note**: This template is filled in by the `/speckit.plan` command. See `.specify/templates/commands/plan.md` for the execution workflow.

**Note**: This template is filled in by the planning workflow.

## Summary

*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*

[Gates determined based on constitution file]

- [ ] Library-first boundary documented (standalone library + integration points).

- [ ] CLI contract defined (text input/output + JSON mode).

- [ ] TDD evidence planned (tests written/approved + red phase before implementation).

## Library Boundary & CLI Contract

[Describe the standalone library module, its public API, and the CLI entrypoints.

Include text input/output channels and JSON output mode.]

## TDD Evidence

[Describe the unit tests to be written first and how failing tests (red phase) will be

validated before implementation begins.]

## Project Structure

- **FR-003**: Users MUST be able to [key interaction, e.g., "reset their password"]

- **FR-004**: System MUST [data requirement, e.g., "persist user preferences"]

- **FR-005**: System MUST [behavior, e.g., "log all security events"]

- **FR-006**: Every feature MUST begin as a standalone library with a defined public

  interface before application integration.

- **FR-007**: Every library MUST expose a CLI that accepts text input and emits text

  output, and MUST provide a JSON output mode for structured data.

- **FR-008**: Unit tests MUST be written, user-approved, and verified failing before

  implementation begins.

*Example of marking unclear requirements:*

- **FR-006**: System MUST authenticate users via [NEEDS CLARIFICATION: auth method not specified - email/password, SSO, OAuth?]

- **FR-007**: System MUST retain user data for [NEEDS CLARIFICATION: retention period not specified]

- **FR-009**: System MUST authenticate users via [NEEDS CLARIFICATION: auth method not specified - email/password, SSO, OAuth?]

- **FR-010**: System MUST retain user data for [NEEDS CLARIFICATION: retention period not specified]

### Key Entities *(include if feature involves data)*

**Input**: Design documents from `/specs/[###-feature-name]/`

**Prerequisites**: plan.md (required), spec.md (required for user stories), research.md, data-model.md, contracts/

**Tests**: The examples below include test tasks. Tests are OPTIONAL - only include them if explicitly requested in the feature specification.

**Tests**: The examples below include test tasks. Tests are REQUIRED unless explicitly

exempted by the feature specification and approved in the constitution.

**Organization**: Tasks are grouped by user story to enable independent implementation and testing of each story.

**Independent Test**: [How to verify this story works on its own]

### Tests for User Story 1 (OPTIONAL - only if tests requested) ⚠️

### Tests for User Story 1 (REQUIRED) ⚠️

> **NOTE: Write these tests FIRST, ensure they FAIL before implementation**

**Independent Test**: [How to verify this story works on its own]

### Tests for User Story 2 (OPTIONAL - only if tests requested) ⚠️

### Tests for User Story 2 (REQUIRED) ⚠️

- [ ] T018 [P] [US2] Contract test for [endpoint] in tests/contract/test_[name].py

- [ ] T019 [P] [US2] Integration test for [user journey] in tests/integration/test_[name].py

**Independent Test**: [How to verify this story works on its own]

### Tests for User Story 3 (OPTIONAL - only if tests requested) ⚠️

### Tests for User Story 3 (REQUIRED) ⚠️

- [ ] T024 [P] [US3] Contract test for [endpoint] in tests/contract/test_[name].py

- [ ] T025 [P] [US3] Integration test for [user journey] in tests/integration/test_[name].py

### Within Each User Story

- Tests (if included) MUST be written and FAIL before implementation

- Tests MUST be written, user-approved, and FAIL before implementation

- Models before services

- Services before endpoints

- Core implementation before integration