Contributing & Development Guide

Relevant source files

The following files were used as context for generating this wiki page:

• ARCHIVE/remaining-docs-consolidated-2026-02-13/CONTRIBUTING.md
• ARCHIVE/remaining-docs-consolidated-2026-02-13/TAMV-UNIFICATION-STATUS.md
• ARCHIVE/remaining-docs-consolidated-2026-02-13/IMPLEMENTATION-PROGRESS-REPORT.md
• ARCHIVE/remaining-docs-consolidated-2026-02-13/TAMV-COMPLETE-IMPLEMENTATION-PLAN.md
• scripts/analyze-duplicates.ts
• tests/unit/analyze-duplicates.test.ts

This guide outlines the standards, workflows, and technical requirements for contributing to the Territorio Autónomo de Memoria Viva (TAMV) project. It is designed to ensure that all contributions align with the project's goal of creating a unified, federated, and hardened socio-technical infrastructure for digital autonomy.

The development environment is built on a strict TypeScript foundation, utilizing automated analysis tools for maintenance and a robust testing suite to ensure high code quality. Developers are expected to follow the established canonical directory structure and adhere to the English language requirement for all code and documentation.

Project Structure and Tooling

The TAMV project follows a canonical directory structure to maintain organization across frontend, backend, and infrastructure components.

Directory Layout

The project is organized into several key directories:

• frontend/: React/Next.js client-side applications.
• backend/: Node.js/Express.js server-side logic and APIs.
• infrastructure/: Docker, Kubernetes, and Terraform configurations.
• database/: Schema definitions and migrations.
• docs/: Technical and architectural documentation.
• tests/: Unit, integration, and property-based tests.
• scripts/: Maintenance tools such as the File System Analyzer and Merge Strategy scripts.

Sources: TAMV-UNIFICATION-STATUS.md:12-19, TAMV-COMPLETE-IMPLEMENTATION-PLAN.md:28-112

Technical Stack

The core development stack includes:

• Runtime: Node.js ≥18.0.0.
• Language: TypeScript 5.3.3 in strict mode.
• Testing: Jest 29.7.0 and fast-check 3.15.0.
• Formatting: ESLint and Prettier.
• Git Hooks: Husky 8.0.3 for pre-commit checks.

Sources: TAMV-UNIFICATION-STATUS.md:197-217, CONTRIBUTING.md:16-17

Development Workflow

Contributors must follow a structured workflow to maintain the integrity of the unified codebase.

Pull Request Process

The standard flow for introducing changes is as follows:

1. Fork and Clone: Create a local copy of the repository.
2. Branching: Create a branch from main with a descriptive prefix (e.g., feat/, fix/, docs/).
3. Implementation: Code following the strict TypeScript standards and naming conventions.
4. Verification: Run the full test suite and linting tools locally.
5. Submission: Open a pull request with a detailed description of changes and associated issue numbers.

Sources: CONTRIBUTING.md:120-142

Commit Message Standards

The project utilizes the Conventional Commits format: <type>(<scope>): <subject>. Supported types include feat, fix, docs, style, refactor, test, and chore.

Sources: CONTRIBUTING.md:104-118

Coding Standards

General Principles

• Language: All code, comments, and documentation MUST be in English.
• Naming: Use camelCase for variables/functions, PascalCase for classes/interfaces, and UPPER_SNAKE_CASE for constants.
• Types: Avoid any; use unknown if the type is truly uncertain.

Sources: CONTRIBUTING.md:25-50

Automated Quality Checks

Development tools are configured to run automatically during the pre-commit phase via Husky.

# Check linting and formatting
npm run lint
npm run format:check

# Run full test suite
npm test

Sources: CONTRIBUTING.md:38-46, CONTRIBUTING.md:95-98

Testing Architecture

The project employs a multi-tiered testing strategy to ensure reliability.

Test Type	Tool	Purpose
Unit Tests	Jest	Testing individual business logic and edge cases.
Property-Based	fast-check	Testing universal properties across 100+ random iterations.
Integration	Supertest	End-to-end API endpoint validation.

Sources: CONTRIBUTING.md:73-93, TAMV-UNIFICATION-STATUS.md:209-211

Property-Based Testing Example

Developers are encouraged to use fast-check to validate code properties that should hold true for all possible inputs.

import fc from 'fast-check';

test('all imports should be used', () => {
  fc.assert(
    fc.property(fc.sourceFile(), (file) => {
      // Logic to verify import usage
    }),
    { numRuns: 100 }
  );
});

Sources: CONTRIBUTING.md:83-91

Analysis and Maintenance Tools

The project includes specialized scripts to manage large-scale consolidation and prevent code fragmentation.

File System Analyzer

Located in scripts/analyze-duplicates.ts, this tool identifies duplicate folders, documents, and empty directories. It also calculates a Quality Score based on completeness (40%), recency (30%), and code quality (30%).

The analysis logic uses recursive scanning while excluding node_modules, .git, and .kiro.

Sources: scripts/analyze-duplicates.ts:258-294, scripts/analyze-duplicates.ts:405-555

Functional Integration Rules

The analyzer applies specific rules to categorize files into TAMV functional layers:

• Protocols (L2): Logic for controlled protocol engines.
• Memory (L1): Traceability and logging for MSR/BookPI.
• XR (L4): Rendering and visual pipelines.
• Domain Services (L5): Identity, social, and economic APIs.

Sources: scripts/analyze-duplicates.ts:110-148

Conclusion

The TAMV development process is highly structured, emphasizing automation and type safety. By adhering to the standards in this guide—specifically the strict TypeScript rules, testing requirements, and analysis workflows—contributors help maintain the project's integrity as it evolves into a production-ready federated infrastructure.