Merge branch 'feature/phase-1-architecture-principles' into develop

docs/ARCHITECTURE.md

@@ -12,6 +12,10 @@ This is a phase-1 placeholder. The architecture is not yet fully defined, and im
 
 Architecture in this repository should be decision-driven. Major technical choices should be documented before implementation begins, and implementation should follow documented decisions rather than informal local reasoning.
 
+## Relationship to Architecture Principles
+
+This document should stay consistent with `docs/ARCHITECTURE_PRINCIPLES.md`. Future architecture sections should reflect the guiding principles and constraints defined there before they commit the repository to more concrete technical choices.
+
 ## Relationship to ADRs
 
 This document should stay aligned with the ADR set in `docs/adr/`. ADRs capture specific decisions and their rationale. This overview should summarize the accepted decisions at a higher level, not replace the ADR record.

docs/ARCHITECTURE_PRINCIPLES.md

@@ -0,0 +1,56 @@
+# Architecture Principles
+
+## Purpose
+
+This document defines the guiding architectural principles and constraints for phase 1. It exists to give future technical decisions a shared reference before concrete stack and runtime choices are finalized.
+
+## Architectural Principles
+
+Use these principles to guide near-term technical decisions:
+
+- prefer simplicity over premature complexity
+- preserve repository portability across machines
+- document important technical decisions explicitly
+- favor small, reviewable increments
+- keep operational complexity low by default
+- maintain clear testing and documentation expectations
+- support reproducible local development workflow
+- avoid lock-in unless it is clearly justified
+- favor maintainability over novelty
+
+## Constraints
+
+Future implementation choices must respect these constraints:
+
+- do not assume a single development machine
+- do not rely on undocumented local setup
+- avoid introducing infrastructure without a clear need
+- justify technology choices through the documented decision process
+- optimize early implementation for learning and iteration, not scale theatre
+
+## What to Optimize for in the Current Phase
+
+In the current phase, optimize for:
+- clear decision-making
+- low ambiguity
+- portability
+- maintainability
+- fast feedback from small changes
+- a workflow that humans and Codex can follow consistently
+
+## What Not to Optimize for Yet
+
+Do not optimize yet for:
+- large-scale deployment assumptions
+- advanced infrastructure
+- speculative performance work
+- premature service decomposition
+- novelty for its own sake
+
+## Decision Consequences
+
+These principles narrow the acceptable set of future technical choices. A technology may be viable in general and still be a poor fit for this phase if it adds unnecessary complexity, weakens portability, or depends on undocumented local behavior.
+
+## Relationship to Future Stack and Runtime Choices
+
+This document does not choose the final stack. It defines the constraints those choices must satisfy. Future stack, runtime, and infrastructure decisions should be justified through the documented decision process and recorded in ADRs when they become important enough to guide implementation.

docs/PHASE_1.md

@@ -29,6 +29,7 @@ Until the phase-1 decision framework is complete, do not:
 Phase 1 should produce:
 - a maintained phase-1 decision plan
 - a documented technical decision process
+- a documented set of architecture principles and constraints
 - a central architecture overview document
 - a set of ADRs covering major technical choices
 - clear implementation preconditions for the next phase
@@ -39,16 +40,18 @@ Make decisions in this order:
 
 1. Define the required decision areas.
 2. Record the technical decision process and evaluation criteria.
-3. Record the ADR process and naming conventions.
-4. Establish the architecture overview and its relationship to ADRs.
-5. Document major technical decisions in ADRs.
-6. Confirm that implementation-critical choices are explicit and aligned.
+3. Define the architecture principles and guiding constraints.
+4. Record the ADR process and naming conventions.
+5. Establish the architecture overview and its relationship to ADRs.
+6. Document major technical decisions in ADRs.
+7. Confirm that implementation-critical choices are explicit and aligned.
 
 ## Exit Criteria for Phase 1
 
 Phase 1 is complete when:
 - the decision framework is documented
 - the technical decision process is documented and usable
+- the architecture principles and constraints are documented
 - the architecture overview exists and points to ADRs
 - required major technical decisions are recorded as ADRs
 - implementation can begin without relying on undocumented assumptions