65 lines
3.5 KiB
Markdown
65 lines
3.5 KiB
Markdown
# 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.
|