Merge branch 'feature/phase-1-doc-alignment' into develop

AGENTS.md

@@ -2,15 +2,20 @@
 
 ## Scope of this repository
 
-This repository is in **phase 0**.
+Phase 0 is complete.
 
-The goal of this phase is to define:
+The repository now has:
+- a completed workflow and portability foundation from phase 0
+- accepted phase-1 technical decisions recorded through ADRs
+- enough documented guidance to support implementation work that follows the accepted baseline
+
+The goal of the current phase is to continue:
 - how development with Codex and custom agents works
 - how repository workflow works
-- how tasks are executed and closed
+- how technical decisions are documented and applied
-- how the project remains portable across machines
+- how implementation work follows accepted repository decisions
 
-This phase is **not** for deciding the product architecture or implementing application features.
+This repository is no longer limited to workflow/bootstrap work. Runtime, database, structure, workflow, and configuration baselines have already been accepted through ADRs and must guide future implementation tasks.
 
 Agents must optimize for:
 - repeatability
@@ -170,6 +175,14 @@ Never claim tests passed unless they were actually executed.
 
 ---
 
+## ADR Discipline
+
+Implementation work must follow accepted ADRs.
+
+Current accepted decisions live under `docs/adr/` and include the baseline runtime, structure, developer workflow, and configuration strategy. If a task depends on a new major technical choice, document or update the decision explicitly rather than relying on undocumented assumptions.
+
+---
+
 ## Documentation discipline
 
 Whenever behavior changes, update docs if relevant.
@@ -186,15 +199,9 @@ Do not let docs drift from actual workflow.
 
 ## Out of scope in phase 0
 
-Do not decide yet:
+Phase 0 no longer blocks technical decision-making. Phase-1 baseline decisions have already been accepted.
-- final application architecture
-- final domain model
-- runtime services beyond workflow tooling
-- database technology
-- ingestion strategy
-- feature list
 
-If a task drifts into product design, stop and ask for a separate explicit decision.
+Still do not treat product decisions as implicit. If a task drifts into new product scope or a major technical choice that is not yet documented, stop and ask for a separate explicit decision or ADR update.
 
 ---
 
@@ -208,4 +215,5 @@ Avoid:
 - speculative optimization
 - introducing tools that are not yet justified
 
-This phase is about building a clean development method first.
+This phase is about building a clean development method first.
+That method now extends to implementation work that follows the accepted ADR baseline.

README.md

@@ -1,18 +1,31 @@
 # HoopScout v2
 
-HoopScout v2 is currently in phase 0. This repository is being used to define a durable, repository-owned development workflow for Codex and custom agents before product architecture or application features are decided.
+HoopScout v2 has completed its phase-0 workflow foundation and is now using accepted phase-1 decisions to guide implementation planning. The repository remains repository-owned, portable across machines, and explicit about how humans and Codex should work.
 
-The current goal is to establish:
+The current goal is to maintain:
 - Codex-assisted development
 - custom agent usage
 - repeatable task execution
 - repository-owned instructions
 - machine portability
 - branch discipline
+- implementation guidance driven by accepted ADRs
 
-## Phase 0 Scope
+## Current Phase
 
-Phase 0 is focused on how work is done in this repository, not yet what gets built. The current scope includes:
+Phase 0 established the working method for the repository. Phase 1 has already added accepted technical decisions for:
+- architecture principles
+- technical decision process
+- runtime and development stack
+- initial project structure
+- containerized developer workflow
+- configuration and environment strategy
+
+Current work should follow those accepted decisions rather than re-deciding them informally.
+
+## Workflow Foundation
+
+The repository still depends on the phase-0 foundation for:
 - repository workflow
 - branch policy
 - Codex project configuration
@@ -21,18 +34,15 @@ Phase 0 is focused on how work is done in this repository, not yet what gets bui
 - machine setup guidance
 - documentation discipline
 
-Out of scope for now:
+Key decision references:
-- application architecture
+- `docs/ARCHITECTURE.md`
-- domain model
+- `docs/ARCHITECTURE_PRINCIPLES.md`
-- runtime topology
+- `docs/DECISION_PROCESS.md`
-- ingestion strategy
+- `docs/adr/`
-- database choice
-- feature set
-- external integrations
 
 ## Repository Structure
 
-The repository is organized to keep durable workflow guidance in version control and portable across machines.
+The repository is organized to keep durable workflow guidance and technical decision records in version control and portable across machines.
 
 ```text
 .
@@ -49,7 +59,7 @@ The repository is organized to keep durable workflow guidance in version control
 
 - `.codex/` stores repository-scoped Codex configuration and agent definitions.
 - `.agents/skills/` stores reusable skills for repeatable repository workflows.
-- `docs/` stores workflow, machine setup, and task execution guidance.
+- `docs/` stores workflow, architecture, ADRs, machine setup, and task execution guidance.
 - `scripts/` stores repository utility scripts such as local checks.
 - `AGENTS.md` defines repository-wide agent behavior and task rules.
 - `Makefile` exposes standard project commands.
@@ -91,7 +101,7 @@ When starting on a new machine:
 1. Clone the repository.
 2. Authenticate Codex locally.
 3. Checkout the correct branch, typically `develop` or the assigned task branch.
-4. Read `AGENTS.md`, `docs/WORKFLOW.md`, `docs/MACHINE_SETUP.md`, and `docs/TASK_TEMPLATE.md`.
+4. Read `AGENTS.md`, `docs/WORKFLOW.md`, `docs/MACHINE_SETUP.md`, `docs/TASK_TEMPLATE.md`, and the current architecture/ADR documents.
 5. Run `make doctor` to validate the local repository bootstrap before starting a task.
 
 ## Codex Task Style
@@ -114,20 +124,21 @@ Run `make doctor` as part of machine/bootstrap validation to confirm the reposit
 ## Current Status
 
 The repository currently provides:
-- repository bootstrap
+- repository bootstrap and workflow foundation
-- Codex/agent workflow foundation
+- Codex/agent collaboration setup
-- collaboration setup
 - portable development baseline
+- accepted phase-1 technical decisions for future implementation work
 
-## After Phase 0
+## Decision Baseline
 
-Future technical decisions will be made explicitly in later phases once the workflow foundation is stable.
+Future implementation work should follow the accepted ADR baseline unless a later ADR supersedes it.
 
 ## Contributing
 
 To contribute in the current phase:
 - read `AGENTS.md`
 - read `docs/WORKFLOW.md`
+- read the current ADR set in `docs/adr/`
 - create a task branch from `develop`
 - keep tasks narrowly scoped
 

docs/PHASE_1.md

@@ -55,3 +55,5 @@ Phase 1 is complete when:
 - the architecture overview exists and points to ADRs
 - required major technical decisions are recorded as ADRs
 - implementation can begin without relying on undocumented assumptions
+
+The current ADR baseline is sufficient to support the next implementation-oriented phase, provided future work follows the accepted decisions or explicitly supersedes them through later ADRs.

docs/adr/README.md

@@ -27,7 +27,7 @@ Each ADR should include at least:
 Minimal example:
 
 ```md
-# ADR-0001: Example Decision
+# 0001-example-decision
 
 - Status: proposed
 - Date: YYYY-MM-DD
@@ -62,10 +62,16 @@ Use these status values:
 Name ADR files using a numeric prefix and a short slug:
 
 ```text
-ADR-0001-short-decision-name.md
+0001-short-decision-name.md
-ADR-0002-another-decision.md
+0002-another-decision.md
 ```
 
+The repository currently follows this convention:
+- `0001-runtime-and-development-stack.md`
+- `0002-initial-project-structure.md`
+- `0003-containerized-developer-workflow.md`
+- `0004-configuration-and-environment-strategy.md`
+
 ## Relationship to Implementation Tasks
 
 Implementation tasks should follow documented ADRs when they depend on architecture decisions. If an implementation task exposes a new major technical decision, evaluate the options first, then record the accepted outcome in an ADR before implementation proceeds.