OSVauco/docs/DECISIONS.md

Architectural Decision Log

D-001: Git/Gitea as the Source of Truth for Versioned Artifacts

Status: Accepted

Date: 2026-09-20

Decision: Git/Gitea is the authoritative source for versioned repository artifacts: source code, committed configuration, documentation, and commit history. Remote branch state and immutable commit SHA are canonical references for code state.

Reason: To ensure consistency and avoid drift between different sources, a single, version-controlled repository must be the ultimate authority for versioned artifacts. This prevents ambiguity and provides a reliable foundation for development and auditing. Existing documentation (.gemini/GEMINI.md, docs/HANDOFF.md) already establishes this convention for code. This decision formalizes the scope of that authority.

Consequences:

• All work on versioned artifacts must be committed to Gitea to be considered canonical.
• Other sources (local workstations, chat history) are considered non-authoritative for versioned artifacts.
• Automation and deployment pipelines must pull code and configuration from the Gitea repository.
• Live cloud state, including deployed revisions, traffic, build status, IAM, VPC Service Controls, and runtime configuration, must be determined through live read-only platform/API verification, not from Git alone.

Verification / rollback:

• Verification: git remote -v should show Gitea as the origin.
• Rollback: Not applicable.

D-002: WORKING_STATE.md as Canonical Handoff

Status: Proposed

Date: 2026-09-20

Decision: docs/WORKING_STATE.md will serve as the canonical, versioned handoff document for human and agent operators. It provides a concise, structured overview of the current project state.

Reason: The project needs a single, easily parsable document to answer critical questions about the current state of work. While docs/HANDOFF.md has served this purpose, a more structured format is needed to ensure clarity and reduce ambiguity for automated agents.

Consequences:

• All operators (human and agent) must consult docs/WORKING_STATE.md at the beginning of a session.
• The file must be kept up-to-date as the project state changes.
• This document records intended and last-verified operational status, but it does not replace the need for live verification of cloud resources.

Verification / rollback:

• Verification: The file exists and is readable. Agents and operators can successfully parse it to determine the project state.
• Rollback: Revert to using docs/HANDOFF.md as the primary handoff document.

D-003: Immutable Commit SHAs for Deployment

Status: Accepted

Date: 2026-09-20

Decision: All deployment requests and processes must resolve a mutable branch name to an immutable 40-character commit SHA before source retrieval and build submission.

Reason: Using commit SHAs ensures that deployments are deterministic, reproducible, and auditable. A branch name can move, leading to ambiguity about what code is actually being deployed. This principle is critical for stability and security.

Consequences:

• Deployment systems must be designed to work with commit SHAs, not just branch names.
• Tooling must exist to resolve a branch to its current HEAD SHA at the time of deployment.

Verification / rollback:

• Verification: Inspect the implemented deploy-MCP path and build submission request once that implementation exists. Do not infer compliance solely from documentation.
• Rollback: Not applicable. This is a fundamental best practice.