# 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.