refs.yaml

# Intensity — Central reference map
#
# Convention
# ----------
# - Stable identifier: `id` (kebab-case). Only `path` changes when files move.
# - Cite in Markdown prose: `@ref:<id>` (backticks optional).
# - Human-clickable links: keep standard `[label](path)` where the path matches
#   the `path` field below (resolve from this file when moving artifacts).
#
# Validation
# ----------
#   python3 scripts/validate-refs.py
#
# Registers every English spec document plus pt-br/it equivalents, entry points,
# and folders used by the development plan and agents.

version: 1

validate:
  scan_files:
    - README.md
    - backlog.md
    - client/STORE_RELEASE.md
    - openapi/openapi.yaml
    - docs/en/engineering-and-operations/tools.md
    - ia/agents/code.md
    - ia/agents/refactor.md
    - ia/skills/architectural-philosophy.md
    - ia/skills/documenter.md
    - ia/skills/referencer.md
    - ia/tasks/big-refactoring/exec.md
    - ia/tasks/big-refactoring/safety.md
    - ia/tasks/big-refactoring/progress.md
    - ia/tasks/big-refactoring/diagnosis.md
    - ia/tasks/big-refactoring/target-tree.md

entries:
  # --- Entry points & meta ---
  - id: readme
    path: README.md
    label: Repository README
    role: entrypoint

  - id: backlog
    path: backlog.md
    label: Product backlog — what to build next
    role: entrypoint

  - id: refs
    path: docs/refs.yaml
    label: This reference map
    role: metadata

  - id: store-release
    path: client/STORE_RELEASE.md
    label: Store release checklist
    role: engineering

  - id: openapi
    path: openapi/openapi.yaml
    label: OpenAPI REST v1 contract
    role: contract

  - id: deploy-readme
    path: deploy/README.md
    label: VPS production deploy guide
    role: engineering

  # --- Logical folders ---
  - id: docs-en
    path: docs/en
    label: Canonical product & engineering spec (English)
    role: spec-canonical
    locale: en

  - id: docs-pt-br
    path: docs/pt-br
    label: Product spec (Portuguese Brazil)
    role: spec-translation
    locale: pt-br

  - id: docs-it
    path: docs/it
    label: Product spec (Italian)
    role: spec-translation
    locale: it

  - id: ia
    path: ia
    label: Agents and skills for AI-assisted development
    role: ia

  # --- IA agents ---
  - id: agent-code
    path: ia/agents/code.md
    label: Code development agent
    role: agent

  - id: agent-refactor
    path: ia/agents/refactor.md
    label: Refactor agent
    role: agent

  # --- IA skills ---
  - id: skill-architectural-philosophy
    path: ia/skills/architectural-philosophy.md
    label: Architectural philosophy skill
    role: skill

  - id: skill-documenter
    path: ia/skills/documenter.md
    label: Documentation skill (en / pt-br / it)
    role: skill

  - id: skill-referencer
    path: ia/skills/referencer.md
    label: Reference map citation skill
    role: skill

  # --- IA tasks ---
  - id: task-big-refactoring
    path: ia/tasks/big-refactoring
    label: Whole-repo cognitive refactoring task
    role: task

  - id: task-big-refactoring-exec
    path: ia/tasks/big-refactoring/exec.md
    label: Big refactoring execution plan
    role: task

  - id: task-big-refactoring-safety
    path: ia/tasks/big-refactoring/safety.md
    label: Big refactoring safety gates
    role: task

  - id: task-big-refactoring-progress
    path: ia/tasks/big-refactoring/progress.md
    label: Big refactoring progress tracker
    role: task

  - id: task-big-refactoring-diagnosis
    path: ia/tasks/big-refactoring/diagnosis.md
    label: Big refactoring diagnosis notes
    role: task

  - id: task-big-refactoring-target-tree
    path: ia/tasks/big-refactoring/target-tree.md
    label: Big refactoring target trees
    role: task

  # --- Layer 1: Product conception (en) ---
  - id: en-overview-what-is-it
    path: docs/en/product-conception/overview-what-is-it.md
    label: Overview — what is Intensity
    locale: en
    layer: product-conception

  - id: en-how-it-works
    path: docs/en/product-conception/how-it-works.md
    label: How it works
    locale: en
    layer: product-conception

  - id: en-principles-why-it-works-this-way
    path: docs/en/product-conception/principles-why-it-works-this-way.md
    label: Principles — why it works this way
    locale: en
    layer: product-conception

  # --- Layer 2: Solution specification (en) ---
  - id: en-data-model
    path: docs/en/solution-specification/data-model.md
    label: Data model
    locale: en
    layer: solution-specification

  - id: en-experience-and-identity
    path: docs/en/solution-specification/experience-and-identity.md
    label: Experience and identity
    locale: en
    layer: solution-specification

  - id: en-functional-components
    path: docs/en/solution-specification/functional-components.md
    label: Functional components
    locale: en
    layer: solution-specification

  - id: en-design-system
    path: docs/en/solution-specification/design-system.md
    label: Design system
    locale: en
    layer: solution-specification

  # --- Layer 3: Solution architecture (en) ---
  - id: en-architectural-decisions
    path: docs/en/solution-architecture/architectural-decisions.md
    label: Architectural decisions (ADRs)
    locale: en
    layer: solution-architecture

  - id: en-artifacts
    path: docs/en/solution-architecture/artifacts.md
    label: Artifacts
    locale: en
    layer: solution-architecture

  - id: en-integrations-and-communication
    path: docs/en/solution-architecture/integrations-and-communication.md
    label: Integrations and communication
    locale: en
    layer: solution-architecture

  - id: en-platforms-and-environments
    path: docs/en/solution-architecture/platforms-and-environments.md
    label: Platforms and environments
    locale: en
    layer: solution-architecture

  # --- Layer 4: Engineering and operations (en) ---
  - id: en-development-process
    path: docs/en/engineering-and-operations/development-process.md
    label: Development process
    locale: en
    layer: engineering-and-operations

  - id: en-technical-decisions
    path: docs/en/engineering-and-operations/technical-decisions.md
    label: Technical decisions (DTs)
    locale: en
    layer: engineering-and-operations

  - id: en-team-and-responsibilities
    path: docs/en/engineering-and-operations/team-and-responsibilities.md
    label: Team and responsibilities
    locale: en
    layer: engineering-and-operations

  - id: en-tools
    path: docs/en/engineering-and-operations/tools.md
    label: Tools inventory
    locale: en
    layer: engineering-and-operations

  # --- pt-br (structural parity) ---
  - id: pt-br-overview-what-is-it
    path: docs/pt-br/product-conception/overview-what-is-it.md
    label: Visão geral — o que é o Intensity
    locale: pt-br
    layer: product-conception

  - id: pt-br-how-it-works
    path: docs/pt-br/product-conception/how-it-works.md
    label: Como funciona
    locale: pt-br
    layer: product-conception

  - id: pt-br-principles-why-it-works-this-way
    path: docs/pt-br/product-conception/principles-why-it-works-this-way.md
    label: Princípios — por que funciona assim
    locale: pt-br
    layer: product-conception

  - id: pt-br-data-model
    path: docs/pt-br/solution-specification/data-model.md
    label: Modelo de dados
    locale: pt-br
    layer: solution-specification

  - id: pt-br-experience-and-identity
    path: docs/pt-br/solution-specification/experience-and-identity.md
    label: Experiência e identidade
    locale: pt-br
    layer: solution-specification

  - id: pt-br-functional-components
    path: docs/pt-br/solution-specification/functional-components.md
    label: Componentes funcionais
    locale: pt-br
    layer: solution-specification

  - id: pt-br-design-system
    path: docs/pt-br/solution-specification/design-system.md
    label: Design system
    locale: pt-br
    layer: solution-specification

  - id: pt-br-architectural-decisions
    path: docs/pt-br/solution-architecture/architectural-decisions.md
    label: Decisões arquiteturais
    locale: pt-br
    layer: solution-architecture

  - id: pt-br-artifacts
    path: docs/pt-br/solution-architecture/artifacts.md
    label: Artefatos
    locale: pt-br
    layer: solution-architecture

  - id: pt-br-integrations-and-communication
    path: docs/pt-br/solution-architecture/integrations-and-communication.md
    label: Integrações e comunicação
    locale: pt-br
    layer: solution-architecture

  - id: pt-br-platforms-and-environments
    path: docs/pt-br/solution-architecture/platforms-and-environments.md
    label: Plataformas e ambientes
    locale: pt-br
    layer: solution-architecture

  - id: pt-br-development-process
    path: docs/pt-br/engineering-and-operations/development-process.md
    label: Processo de desenvolvimento
    locale: pt-br
    layer: engineering-and-operations

  - id: pt-br-technical-decisions
    path: docs/pt-br/engineering-and-operations/technical-decisions.md
    label: Decisões técnicas
    locale: pt-br
    layer: engineering-and-operations

  - id: pt-br-team-and-responsibilities
    path: docs/pt-br/engineering-and-operations/team-and-responsibilities.md
    label: Equipe e responsabilidades
    locale: pt-br
    layer: engineering-and-operations

  - id: pt-br-tools
    path: docs/pt-br/engineering-and-operations/tools.md
    label: Inventário de ferramentas
    locale: pt-br
    layer: engineering-and-operations

  # --- it (structural parity) ---
  - id: it-overview-what-is-it
    path: docs/it/product-conception/overview-what-is-it.md
    label: Panoramica — cos'è Intensity
    locale: it
    layer: product-conception

  - id: it-how-it-works
    path: docs/it/product-conception/how-it-works.md
    label: Come funziona
    locale: it
    layer: product-conception

  - id: it-principles-why-it-works-this-way
    path: docs/it/product-conception/principles-why-it-works-this-way.md
    label: Principi — perché funziona così
    locale: it
    layer: product-conception

  - id: it-data-model
    path: docs/it/solution-specification/data-model.md
    label: Modello dati
    locale: it
    layer: solution-specification

  - id: it-experience-and-identity
    path: docs/it/solution-specification/experience-and-identity.md
    label: Esperienza e identità
    locale: it
    layer: solution-specification

  - id: it-functional-components
    path: docs/it/solution-specification/functional-components.md
    label: Componenti funzionali
    locale: it
    layer: solution-specification

  - id: it-design-system
    path: docs/it/solution-specification/design-system.md
    label: Design system
    locale: it
    layer: solution-specification

  - id: it-architectural-decisions
    path: docs/it/solution-architecture/architectural-decisions.md
    label: Decisioni architetturali
    locale: it
    layer: solution-architecture

  - id: it-artifacts
    path: docs/it/solution-architecture/artifacts.md
    label: Artefatti
    locale: it
    layer: solution-architecture

  - id: it-integrations-and-communication
    path: docs/it/solution-architecture/integrations-and-communication.md
    label: Integrazioni e comunicazione
    locale: it
    layer: solution-architecture

  - id: it-platforms-and-environments
    path: docs/it/solution-architecture/platforms-and-environments.md
    label: Piattaforme e ambienti
    locale: it
    layer: solution-architecture

  - id: it-development-process
    path: docs/it/engineering-and-operations/development-process.md
    label: Processo di sviluppo
    locale: it
    layer: engineering-and-operations

  - id: it-technical-decisions
    path: docs/it/engineering-and-operations/technical-decisions.md
    label: Decisioni tecniche
    locale: it
    layer: engineering-and-operations

  - id: it-team-and-responsibilities
    path: docs/it/engineering-and-operations/team-and-responsibilities.md
    label: Team e responsabilità
    locale: it
    layer: engineering-and-operations

  - id: it-tools
    path: docs/it/engineering-and-operations/tools.md
    label: Inventario strumenti
    locale: it
    layer: engineering-and-operations