# DSS Principles Deep Dive (v1.2.0 - Archived Reference)

**Version 1.2.0** | Last Updated: 2025-12-08 | Status: Archived Reference Only

This document contains the full elaboration of DSS principles from **Version 1.2.0**, archived for reference when you need deep understanding of individual principles.

**See PRINCIPLES.md for the current concise version (2.0.0).**

---

## When to Use This Document

You're reading the right document if:
- You need detailed explanation of a principle
- You want to understand the "why" behind enforcement mechanisms
- You're implementing pre-commit hooks or CI/CD checks
- You want to see all the red flags and success metrics

You should read **PRINCIPLES.md** if:
- You're new to DSS (quick overview)
- You're making a decision
- You want decision-making criteria
- You have 5-10 minutes

---

## Structure of This Document

This document covers the same 5 core principles as PRINCIPLES.md (v2.0.0) but with full elaboration:

### For Each Principle:
- **Core Concept**: What it means
- **Why It Matters**: Business/technical rationale
- **How to Apply**: Step-by-step implementation
- **Implementation Checklist**: Verification items
- **Red Flags**: Anti-patterns to watch for
- **Enforcement Mechanism**: Pre-commit hooks and CI checks
- **Success Metrics**: How to measure implementation

---

## The 5 Principles (Detailed)

### Principle 1: Design is an Architectural Concern

**Core Concept**

Design decisions shape system structure, not just aesthetics. Every color, spacing, and component is a **contract** that other parts of the system depend on.

**Why It Matters**

- **Consistency**: Design tokens are dependencies; inconsistency breaks contracts
- **Testability**: Component specs are testable contracts
- **Evolution**: Design changes tracked with same rigor as API changes
- **Autonomy**: Teams can work independently if contracts are clear

**How to Apply**

1. **Treat Design Tokens as Code Dependencies**

Design tokens (colors, spacing, typography) are not styling suggestions—they're contracts that code depends on.

```
❌ WRONG:
<!-- Using hex values directly -->
<Button style={{ background: "#007AFF" }} />

✅ RIGHT:
<!-- Using design token from contract -->
<Button background={tokens.color.primary[500]} />
```

Checklist:
- [ ] All color values come from token definitions
- [ ] All spacing values come from token definitions
- [ ] All typography values come from token definitions
- [ ] Components reference tokens, not hardcoded values
- [ ] Token schema documented in tokens/ directory
- [ ] Tokens versioned with semantic versioning

Enforcement:
```bash
# Pre-commit check: No hardcoded hex colors in component code
grep -r "#[0-9A-F]{6}" packages/components/ && exit 1
```

2. **Design Changes Follow Same Review as API Changes**

A design change that affects components requires the same rigor as an API change.

```
Component Update Example:
Old Contract: Button[variant=primary] uses color.primary[500]
New Contract: Button[variant=primary] uses color.primary[600]

Requires:
✅ Version bump in component spec
✅ Migration guide for consumers
✅ Changelog entry
✅ 6-month deprecation notice for old version
```

Checklist:
- [ ] Design change documented in ARCHITECTURE.md
- [ ] Component contract updated with version
- [ ] Migration path provided if breaking
- [ ] Changelog entry created
- [ ] Deprecation timeline documented

3. **Make Visual Decisions Explicit**

Every design decision should be traceable back to why (not "looks good").

```
❌ "Changed button color to blue"
✅ "Changed button color from color.primary[500] to color.primary[600]
    for improved contrast on light backgrounds (WCAG AA compliance)"
```

Checklist:
- [ ] Design decisions documented in ADR
- [ ] Visual change rationale explained
- [ ] Alternatives considered documented
- [ ] Impact assessment done
- [ ] Accessibility implications checked

**Red Flags**

```
❌ "Let me just tweak this spacing"
   → Is it breaking a contract? Document the change

❌ Figma file has one value, component has another
   → Single source of truth violation; reconcile immediately

❌ "Designers will use Figma, developers will use tokens"
   → Should be the same source (tokens in Figma, imported to code)

❌ Visual change not documented in ARCHITECTURE.md
   → Architectural decisions should be explicit
```

**Enforcement Mechanism**

Pre-commit hook: `check-design-tokens.py`
```python
# Validates all hardcoded colors are in token definitions
# Fails if: component uses non-token color value
# Exception: Comments explaining legacy colors (documented)
```

CI Check: `design-consistency`
```yaml
# Compares Figma tokens against code tokens
# Fails if: values diverge (SSoT violation)
# Validates component specs match contracts
```

**Success Metrics**

- All components use design tokens (zero hardcoded values)
- Figma and code tokens always in sync
- Design changes versioned like API changes
- Component contracts documented in ARCHITECTURE.md
- Developers can cite design decisions in PRs

---

### Principle 2: Contracts are Immutable and Versioned

**Core Concept**

Tier 1 files (API_CONTRACTS.md, ARCHITECTURE.md, PRINCIPLES.md) are the constitution. They change only through semantic versioning.

**Why It Matters**

- **Backwards Compatibility**: Consumers rely on these specs not changing randomly
- **Trust**: External systems can pin to a version and stay stable
- **Intentionality**: Every API change is deliberate, not accidental
- **Governance**: Breaking changes require explicit version bump, not silent updates

**How to Apply**

1. **Immutable Until Version Bump**

```
docs/01_core/API_CONTRACTS.md
Version 1.2.3  ← This is THE contract

Changes allowed:
✅ Add new endpoints (1.3.0 - minor bump)
✅ Extend with optional fields (1.2.4 - patch bump)
✅ Fix documentation clarity (1.2.4 - patch bump)
✅ Deprecate endpoint (add note, bump to 1.4.0)

Breaking changes FORBIDDEN until major bump:
❌ Remove endpoint
❌ Change auth scheme
❌ Change response schema (breaking)
❌ Change error codes
```

2. **Clear Deprecation Path**

```
## Endpoint: GET /api/v1/projects/{id}

**Status**: Active (v1.2.0+)
**Deprecation**: Will remove in v3.0.0 (projected Q2 2026)
**Migration**: See MIGRATION_GUIDE.md for upgrade path

Request: {...}
Response: {...}
```

3. **Version Everything**

- API contracts include version (e.g., "endpoints as of v1.2.3")
- Architecture versioning tracks major design shifts (e.g., "Token merge system v2.1")
- Principles versioning tracks philosophy evolution (rare)

4. **Never Silent Changes**

- Every change to Tier 1 triggers a version bump AND changelog
- Changelog entry: what changed, why, migration path
- Old versions archived in `docs/archive/versions/`

**Implementation Checklist**

- [ ] All Tier 1 files include version number at top (Version X.Y.Z)
- [ ] Versioning follows semantic versioning (MAJOR.minor.patch)
- [ ] Changelog entries for every Tier 1 change
- [ ] Deprecated endpoints marked with sunset date
- [ ] Breaking changes bump MAJOR version (very rare)
- [ ] Non-breaking additions bump minor version
- [ ] Documentation fixes bump patch version
- [ ] Old API versions archived with `VERSIONING.md` map

**Conflict Resolution: Contracts vs MCP First**

When a new MCP tool would require breaking the API contract:
```
Hierarchy: Foundational Contracts > MCP First

Action:
1. Add new MCP tool (doesn't violate contract)
2. Keep legacy API endpoint working
3. Mark legacy as deprecated, suggest MCP alternative
4. Plan sunset in next major version

Example:
OLD API (v1.2.0):
  POST /api/projects/figma/link

NEW MCP TOOL (v1.2.0+):
  dss_add_figma_file (MCP-first approach)

Migration Path:
  • 1.2.0: Both work (API deprecated in docs)
  • 2.0.0: API removed, MCP tool is SSoT
```

**Red Flags**

```
❌ API_CONTRACTS.md updated without version bump
   → Version should change with EVERY update

❌ Endpoint removed, no deprecation notice
   → Should have been deprecated for 6+ months first

❌ No changelog for API changes
   → Every version bump needs "What changed" entry

❌ Architecture changes silently reflected in code
   → Changes must be explicit in ARCHITECTURE.md with rationale
```

**Enforcement Mechanism**

Pre-commit hook: `schema-diff.py`
```python
# Compares API spec version in file against git history
# Fails if: file changed but version number didn't change
# Exception: Version file itself (PR metadata only)
```

CI Check: `version-bump-validator`
```yaml
# For any change to Tier 1 files:
# - Requires version bump
# - Requires changelog entry
# - Validates semver format
# - Updates VERSIONING.md map
```

**Success Metrics**

- No file mirrors content from another (use links instead)
- Each API endpoint documented once with version number
- No "draft" or "TODO" versions of specs floating around
- Git history shows updates to core docs, not creation of new ones
- Breaking changes properly sunset (6+ months deprecation period)

---

### Principle 3: The System is the Single Source of Truth

**Core Concept**

Tier 2 files (PROJECT_STATUS.md, IMPLEMENTATION_SUMMARY.md, README.md) always reflect production reality. They are living documents updated at least weekly.

**Why It Matters**

- **No Hallucination**: Agents read what's actually deployed, not aspirational state
- **Trust**: Stakeholders can check status without asking
- **Incident Response**: Current state is documented for quick triage
- **History**: Changes are logged for retrospectives

**How to Apply**

1. **PROJECT_STATUS.md Is The Source**

```markdown
# Project Status

Last Updated: 2025-12-08
Current Phase: Phase 5D - Production Hardening

## Deployment Status
- Production: v1.2.3 (deployed 2025-12-05)
- Staging: v1.3.0-rc.1 (testing new features)
- Current Focus: MCP tool stabilization

## Open Bugs (prioritized)
1. CRITICAL: Figma token sync timeout (affects 3 projects)
2. HIGH: Pre-commit hook slow on large repos
3. MEDIUM: Typo in INTEGRATION_GUIDE.md

## Roadmap
- Week of 12/8: Fix token sync timeout
- Week of 12/15: Release v1.2.4 (bug fixes)
- Q1 2026: MCP tool ecosystem expansion
```

2. **Update Weekly (Not Monthly)**

- Every Friday: Review bugs, deployment status, roadmap changes
- Update "Last Updated" timestamp
- Use past tense for completed work: "Fixed token timeout (12/8)"

3. **What Goes in PROJECT_STATUS.md**

- Current deployment version in production
- Current phase/sprint (if relevant)
- Open bugs (prioritized)
- In-progress features
- Upcoming roadmap (next 4 weeks visible)
- Known limitations
- Maintenance windows

4. **IMPLEMENTATION_SUMMARY.md**

- Complete inventory of features by phase
- Phase 1: User authentication, project creation
- Phase 2: Figma integration, token management
- Phase 3: Component sync, design tokens
- etc.

**Implementation Checklist**

- [ ] PROJECT_STATUS.md updated every Friday
- [ ] "Last Updated" timestamp current (within 7 days)
- [ ] Production version matches git tags
- [ ] All open bugs tracked with priority
- [ ] Roadmap looks 4 weeks ahead (not vague)
- [ ] Completed work removed from todo lists
- [ ] Deployment changes logged with dates
- [ ] Incident post-mortems update "Known Limitations"

**Red Flags**

```
❌ "Last Updated: 2025-11-15" (older than 7 days)
   → Is this stale? Update it this week

❌ "Phase: TBD" or "Roadmap: TBD"
   → Status should be concrete, not vague

❌ "See MVP_FINAL_REPORT.md for details"
   → Archive the report; put summary in PROJECT_STATUS

❌ "Fixed: Token sync issue (date unknown)"
   → Always date stamp: "Fixed 2025-12-05"
```

**Enforcement Mechanism**

Git hook: `status-staleness-check.py`
```python
# Runs before push to production
# Checks: PROJECT_STATUS.md "Last Updated" is within 7 days
# Fails if stale (prevents deploying with old status)
```

CI Check: `version-sync`
```yaml
# Validates PROJECT_STATUS.md version matches git tag
# Validates IMPLEMENTATION_SUMMARY.md references match features in code
# Fails if status doesn't match deployed code
```

GitHub Actions: `weekly-status-reminder`
```yaml
# Every Friday at 5pm: Opens PR with PROJECT_STATUS.md template
# Reminder to team: Update status before weekend
# Cannot be merged; just a CTA
```

**Success Metrics**

- PROJECT_STATUS.md updated every 7 days max
- Production version in status matches deployed code
- Bugs filed have corresponding entries in status
- Completed features removed from in-progress list
- Roadmap always 4+ weeks visible
- Team consensus: "This is the one source of project truth"

---

### Principle 4: Decisions are Explicit and Traceable

**Core Concept**

Architecture decisions, design rationales, and system history live in a structured knowledge graph (`.knowledge/`), not scattered across markdown files. The graph is queryable and executable.

**Why It Matters**

- **Rationale**: Why was this decision made? Check the graph.
- **Traceability**: Who decided this? When? What alternatives?
- **Evolution**: Track how decisions evolved over time
- **Executability**: Graph can generate code (Year 3 vision)
- **Machine-Readable**: Agents can reason about decisions systematically

**How to Apply**

1. **ADR (Architecture Decision Record) Pattern**

File: `.knowledge/decisions/ADR-0001.md`

```markdown
---
id: ADR-0001
title: Token Merge System as Core DSS Feature
date: 2025-12-05
author(s): Team Name
status: Accepted
principles: [Design is Architectural, Contracts Immutable, Single Source of Truth]
related:
  - doc: docs/01_core/ARCHITECTURE.md#token-merge
  - adr: ADR-0002-MCP-first-architecture
  - ticket: DSS-PR-101
---

## Context

Multiple projects needed to ingest tokens from Figma, CSS, SCSS. Without normalization, incompatible systems couldn't coexist.

## Decision

Implement TokenMerger class with pluggable merge strategies (FIRST, LAST, PREFER_FIGMA, PREFER_CODE, PREFER_SPECIFIC, MERGE_METADATA).

## Alternatives Considered

1. **Manual token mapping**
   - Reason rejected: Doesn't scale; requires human review per project

2. **Single canonical merge strategy**
   - Reason rejected: Too rigid; different projects have different workflows

## Consequences

**Positive:**
- Supports multiple UI libraries (flexibly)
- Non-breaking integration (each project chooses strategy)
- Auditable (all merges logged)

**Negative:**
- More complex than single strategy
- Developers must understand each strategy
- Potential for misconfiguration
```

2. **Design Patterns Library**

File: `.knowledge/patterns/pattern-optional-auth.md`

```markdown
# Optional Authentication Middleware

## Problem

Some endpoints work anonymous (GET /projects) but also work authenticated (same endpoint with per-user filtering).

## Solution

Optional auth middleware that validates token IF present, but doesn't require it.

## Implementation

See docs/01_core/ARCHITECTURE.md#optional-auth-middleware

## Use Cases

- GET /projects (public → all, authenticated → user's projects)
- GET /api/health (always works, no auth needed)

## Trade-offs

- More complex than required auth
- Security: Never trust unauthenticated requests
```

3. **Component Contract Graph**

File: `.knowledge/components/Button.json`

```json
{
  "id": "Button",
  "canonical_path": "packages/components/Button/Button.tsx",
  "contract_version": "1.2.0",
  "interface": {
    "variant": ["primary", "secondary", "ghost"],
    "size": ["sm", "md", "lg"],
    "disabled": "boolean"
  },
  "story_path": "packages/components/Button/Button.stories.tsx",
  "api_endpoint": "GET /api/components/button",
  "figma_file_id": "figd_abc123",
  "figma_component_name": "Button",
  "design_tokens": [
    "color.primary.500",
    "color.primary.600",
    "spacing.md",
    "radius.sm"
  ],
  "accessibility": {
    "wcag_level": "AA",
    "tested": true,
    "issues": []
  },
  "related_components": ["Input", "Modal"],
  "status": "stable"
}
```

4. **Integration Points**

File: `.knowledge/integrations/figma-sync.json`

```json
{
  "id": "figma-sync",
  "name": "Figma ↔ DSS Token Sync",
  "status": "active",
  "flow": {
    "source": "Figma file (figma.json manifest)",
    "processor": "dss_sync_figma (MCP tool)",
    "target": "Local project tokens",
    "frequency": "On-demand (manual trigger via MCP)"
  },
  "reliability": {
    "failures_per_week": 0,
    "timeout_seconds": 30,
    "retry_strategy": "exponential-backoff"
  },
  "related_tools": [
    "dss_add_figma_file",
    "dss_discover_figma_files",
    "dss_get_project_manifest"
  ]
}
```

**Implementation Checklist**

- [ ] Create `.knowledge/` directory structure
- [ ] Document core ADRs (Decision #1 in ADR-0001, etc.)
- [ ] Create pattern library for reusable designs
- [ ] Map component contracts in graph format
- [ ] Record integration points and reliability metrics
- [ ] Link markdown files to related knowledge entries
- [ ] Enable querying: `query_knowledge("token merge")` returns ADRs + patterns
- [ ] Set up graph visualization (D3.js or similar)

**Graph Structure**

```
.knowledge/
├── decisions/            # Architecture Decision Records
│   ├── ADR-0001.md       # Token merge system
│   ├── ADR-0002.md       # MCP-first architecture
│   ├── ADR-0003.md       # Knowledge graph as SSoT
│   └── ...
├── patterns/             # Design patterns library
│   ├── pattern-optional-auth.md
│   ├── pattern-translation-dictionary.md
│   ├── pattern-component-extension.md
│   └── ...
├── components/           # Component contracts
│   ├── Button.json
│   ├── Input.json
│   ├── Card.json
│   └── ...
├── integrations/         # External system integrations
│   ├── figma-sync.json
│   ├── shadcn-migration.json
│   ├── heroui-migration.json
│   └── ...
├── graph.json           # Full knowledge graph (generated)
└── graph.schema.json    # JSON Schema for validation
```

**Conflict Resolution: Knowledge Persistence vs Foundational Contracts**

When a decision conflicts with documented contract:
```
Hierarchy: Foundational Contracts > Knowledge Persistence

Action:
1. If decision is old, update ADR to "superseded"
2. Create new ADR explaining contract change
3. Update API_CONTRACTS.md version number
4. Link new ADR from contract file

Example:
  Old ADR: "Auth is required on all endpoints"
  Current API: "Auth is optional (pattern-optional-auth)"
  Fix: ADR → superseded, new ADR → current pattern
```

**Red Flags**

```
❌ "Design decision" explained only in a commit message
   → Should be in .knowledge/decisions/ as ADR

❌ "Component contract is in Figma notes"
   → Should be in .knowledge/components/ComponentName.json

❌ Multiple integration patterns documented in markdown
   → Should be in .knowledge/patterns/

❌ No link between markdown and knowledge graph entries
   → Each should reference the other
```

**Enforcement Mechanism**

Pre-commit hook: `knowledge-graph-validator.py`
```python
# Validates .knowledge/*.json against schema
# Ensures all ADRs are properly formatted
# Warns if decision made in code without ADR
```

CI Check: `orphaned-knowledge`
```yaml
# Finds ADRs/patterns not referenced in any markdown
# Finds markdown decisions not in knowledge graph
# Flags for review: "Knowledge graph is out of sync"
```

**Success Metrics**

- Every major decision has an ADR (with rationale, alternatives, consequences)
- Every design pattern documented in pattern library
- Every component contract defined in graph
- Markdown links to graph entries (and vice versa)
- Developers can query knowledge: "Why did we choose MCP-first?"
- Year 3: Graph generates TypeScript types (executable specs)

---

### Principle 5: Operations are Exposed as Standardized Tools

**Core Concept**

Model Context Protocol (MCP) tools are first-class citizens for all operations. REST endpoints are secondary (for human access). Agents interact via MCP tools; humans use the tools OR web UI (which uses the tools).

**Why It Matters**

- **Agent Autonomy**: Agents don't wait for UI; they use tools directly
- **Consistency**: All operations (human or agent) go through same tools
- **Auditability**: Every operation logged in mcp_tool_usage
- **Extensibility**: Adding new capability = adding MCP tool (not API endpoint)
- **Future-Proof**: Year 3 vision: All work done via agents, tools are primary interface

**How to Apply**

1. **Tool-First Architecture**

```
WRONG ❌ (REST-first, tools secondary)
───────────────────────────────────
Operation: Create new project

Primary: POST /api/projects
Secondary: dss_create_project MCP tool (calls REST endpoint)

Flow: Agent → MCP tool → REST API → Database
Problem: Extra layer, still tied to HTTP API

RIGHT ✅ (MCP-first, REST is UI only)
──────────────────────────────────
Operation: Create new project

Primary: dss_create_project MCP tool (direct to database)
Secondary: REST endpoint POST /api/projects (uses MCP tool internally)

Flow Agent: Agent → MCP tool → Database
Flow (Human via UI): UI button → MCP tool → Database

Result: Single source of truth (tool), REST is thin wrapper
```

2. **Current MCP Tool Inventory**

**Project Management** (docs/03_reference/MCP_TOOLS_SPEC.md):
- `dss_create_project` - Create new project with figma.json manifest
- `dss_setup_figma_credentials` - Store user's Figma API token (encrypted)
- `dss_get_project_manifest` - Read project's figma.json
- `dss_add_figma_file` - Link Figma file to project
- `dss_discover_figma_files` - List available Figma files
- `dss_list_project_figma_files` - List linked files

**Token Extraction & Merging**:
- `dss_extract_tokens` - Extract from CSS, SCSS, Tailwind, JSON
- `dss_merge_tokens` - Merge multiple sources with strategies
- `dss_resolve_token` - Look up token through cascade

**Design System Operations**:
- `dss_sync_figma` - Sync tokens from Figma file
- `dss_transform_tokens` - Convert between token formats
- `dss_generate_theme` - Generate theme output files

**Analysis & Auditing**:
- `dss_analyze_project` - Analyze codebase for patterns
- `dss_audit_components` - Audit component adoption
- `dss_find_quick_wins` - Identify easy improvements

3. **Tool Design Pattern**

```python
# In tools/dss_mcp/tools/project_tools.py

class ProjectTools:
    """All project operations as MCP tools (primary interface)"""

    async def dss_create_project(
        self,
        name: str,
        root_path: str,
        description: str = ""
    ) -> Dict:
        """Create new project (primary: MCP tool, not REST API)"""
        # 1. Validate input
        # 2. Insert into database
        # 3. Create figma.json manifest
        # 4. Log to mcp_tool_usage table
        # 5. Emit event
        # 6. Return result

    # REST endpoint just wraps this
    # @app.post("/api/projects")
    # async def create_project_rest(request):
    #     return await self.dss_create_project(...)
```

4. **Tool Versioning & Documentation**

```
MCP Tool versioning mirrors API versioning:

Tool: dss_create_project
Version: 1.2.0 (matches API_CONTRACTS.md v1.2.0)

Input Schema: JSON Schema (immutable until version change)
Output Schema: JSON Schema (immutable until version change)

Deprecation: If tool signature changes
- 1.2.0 → 1.3.0: New optional parameter (backwards compatible)
- 1.3.0 → 2.0.0: Required parameter change (breaking)
```

5. **Tool Evolution**

```
Year 1 (Now):
- All major operations exposed as MCP tools
- REST endpoints wrap tools (not standalone)
- Agents have full autonomy via tools

Year 2:
- Tool auto-discovery from API schema
- Agents suggest new tools based on gaps
- Tool testing automated (schema + behavior)

Year 3:
- Tools generate code (tool params become types)
- Graph-driven: Architecture.md generates tool specs
- Agents create new tools via ADRs + execution
```

**Implementation Checklist**

- [ ] All major operations have MCP tool equivalents
- [ ] REST endpoints wrap tools (not standalone logic)
- [ ] Tool input/output documented in JSON Schema
- [ ] Tool versions tracked and versioned
- [ ] All tool calls logged in mcp_tool_usage table
- [ ] Tool errors include context (which tool, which parameters)
- [ ] Deprecation path documented for tool changes
- [ ] Agent can discover available tools via introspection

**Current Tool Implementation Status**

✅ Implemented (production-ready):
- dss_create_project
- dss_setup_figma_credentials
- dss_get_project_manifest
- dss_add_figma_file
- dss_discover_figma_files
- dss_list_project_figma_files
- dss_extract_tokens
- dss_merge_tokens
- dss_transform_tokens
- dss_analyze_project
- dss_audit_components
- dss_find_quick_wins

🔄 In Progress:
- dss_sync_figma (complex Figma API integration)

⏱️ Planned:
- dss_generate_theme (using style-dictionary)
- dss_resolve_token (context cascade)
- Storybook generation tools
- Component generation tools

**Conflict Resolution: MCP First vs Foundational Contracts**

When tool design would violate an API contract:
```
Hierarchy: Foundational Contracts > MCP First

Action:
1. Design tool to honor contract
2. If tool needs breaking change, bump API version
3. Deprecate old tool, introduce new one in 1.3.0
4. Remove old tool in 2.0.0

Example:
  Contract (v1.0): dss_create_project requires root_path
  New Tool (v1.1): Add optional root_path (default: '.')
  Breaking Change (v2.0): Remove root_path requirement
```

**Red Flags**

```
❌ "Just POST /api/projects directly"
   → Should be dss_create_project tool (agents use tools)

❌ Tool that only wraps REST endpoint
   → Tool should be primary; endpoint wraps tool

❌ Tool implementation scattered across 3 files
   → All tools should be in tools/ directory, organized

❌ "REST API is the real source, MCP wraps it"
   → Backwards; tools are source, REST wraps tools

❌ New feature added to REST API but not as MCP tool
   → Every operation MUST be a tool first
```

**Enforcement Mechanism**

Pre-commit hook: `tool-completeness.py`
```python
# Scans new API endpoints
# Fails if: endpoint added without corresponding MCP tool
# Exception: Only UI-specific endpoints (health, status) can skip
```

CI Check: `tool-api-alignment`
```yaml
# Compares MCP tool schema against API_CONTRACTS.md
# Fails if tool version doesn't match contract version
# Validates all tools have input/output schema
```

**Success Metrics**

- All major operations have MCP tools (no REST-only endpoints)
- Agents can complete workflows via tools alone
- Tool call audit trail in mcp_tool_usage (100% coverage)
- Tool documentation auto-generated from JSON schema
- Developer question: "How do I do X?" → Answer: "Use dss_X tool"

---

## Conflict Resolution Hierarchy

When principles seem to conflict, use this hierarchy:

```
1. Foundational Contracts (immutable)
2. Single Source of Truth
3. MCP First
4. Knowledge Persistence
5. Current State Transparency
6. Progressive Detail
7. Phase Agnostic
```

**Example Scenarios:**

**Scenario A: New feature requires API change**
```
Principle 1 (Contracts) vs Principle 7 (MCP First)
→ Contracts win: Design tool to honor contract
→ If breaking change needed, bump major version
→ Keep old endpoint deprecated for 6+ months
```

**Scenario B: Two places have conflicting information**
```
Principle 2 (SSoT) vs others
→ SSoT wins: Find the true source
→ Delete duplicates, link instead
→ Update all references
```

**Scenario C: Historic phase reports pile up**
```
Principle 5 (Phase Agnostic) vs Principle 4 (Knowledge Persistence)
→ Phase Agnostic wins: Archive reports to docs/archive/
→ Extract value into PROJECT_STATUS.md + IMPLEMENTATION_SUMMARY.md
→ Keep ADR in .knowledge/decisions/ for rationale
```

---

## Success Metrics for All Principles

- ✅ No duplicate documentation (link instead of copy)
- ✅ All API endpoints documented once with version number
- ✅ PROJECT_STATUS.md updated weekly (within 7 days)
- ✅ All major decisions in .knowledge/decisions/ADRs
- ✅ No PHASE_*_REPORT.md, DEPLOYMENT_*.md in root
- ✅ Every operation has MCP tool (REST wraps tools)
- ✅ Tier 1 files change only via semantic versioning
- ✅ New developer reads QUICK_REFERENCE.md → starts coding (30 min)
- ✅ Stale docs automatically detected and removed (monthly audit)
- ✅ Team consensus: "Principles guide every PR"

---

## Evolution Path

**Year 1 (Now): Manual Enforcement**
- Team follows principles consciously
- Pre-commit hooks catch violations
- CI/CD validates consistency
- Enforcement: Rules enforced, not automated

**Year 2: Automation**
- Generate semver from change detection
- Auto-generate changelogs from commits
- Tools self-discover from API schema
- Enforcement: Rules mostly automated

**Year 3: Code-from-Graph**
- ARCHITECTURE.md generates TypeScript types
- API_CONTRACTS.md generates OpenAPI + SDK types
- .knowledge/graph generates MCP tools
- ADRs generate test suites
- Enforcement: Rules are executable code

---

**This is an archived reference document. For current principles, see PRINCIPLES.md (v2.0.0).**

**Last Updated**: 2025-12-08
**Archived From**: PRINCIPLES.md v1.2.0
**Reference Status**: Complete elaboration available for deep dives