Merge branch 'feature/phase-1-containerized-postgres-baseline' into develop

.agents/skills/task-closeout/SKILL.md

@@ -17,4 +17,4 @@ When this skill is used:
 7. Stop.
 
 Do not perform release actions.
-Do not merge into main.
+Do not merge into main.

README.md

@@ -1,2 +1,136 @@
-# hoopscout-v2
+# 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.
+
+The current goal is to establish:
+- Codex-assisted development
+- custom agent usage
+- repeatable task execution
+- repository-owned instructions
+- machine portability
+- branch discipline
+
+## Phase 0 Scope
+
+Phase 0 is focused on how work is done in this repository, not yet what gets built. The current scope includes:
+- repository workflow
+- branch policy
+- Codex project configuration
+- agent roles
+- reusable task-closeout behavior
+- machine setup guidance
+- documentation discipline
+
+Out of scope for now:
+- application architecture
+- domain model
+- runtime topology
+- ingestion strategy
+- database choice
+- feature set
+- external integrations
+
+## Repository Structure
+
+The repository is organized to keep durable workflow guidance in version control and portable across machines.
+
+```text
+.
+|-- .codex/
+|-- .agents/skills/
+|-- docs/
+|-- scripts/
+|-- AGENTS.md
+|-- Makefile
+|-- README.md
+|-- .editorconfig
+`-- .gitignore
+```
+
+- `.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.
+- `scripts/` stores repository utility scripts such as local checks.
+- `AGENTS.md` defines repository-wide agent behavior and task rules.
+- `Makefile` exposes standard project commands.
+- `README.md` introduces the repository and current phase.
+- `.editorconfig` provides shared formatting defaults.
+- `.gitignore` defines ignored files for the repository.
+
+## Workflow
+
+Protected branches:
+- `main`
+- `develop`
+
+Normal work goes through `feature/*` branches created from `develop`. Tasks should be completed on the task branch, committed there, and merged back into `develop` when done.
+
+## Working with Codex
+
+Durable project behavior should live in the repository so that work remains consistent across machines and contributors.
+
+Repository-owned configuration examples:
+- task workflow
+- branch strategy
+- coding process
+- agent roles
+- reusable skills
+- machine setup instructions
+- test and validation instructions
+
+Local-only configuration examples:
+- Codex authentication
+- personal shell aliases
+- editor preferences
+- secrets and API keys
+- machine-specific customizations not documented as shared examples
+
+## New Machine Setup
+
+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`.
+5. Run `make doctor` to validate the local repository bootstrap before starting a task.
+
+## Codex Task Style
+
+Codex tasks in this repository should follow this order:
+1. Confirm branch strategy.
+2. State the branch being used.
+3. List the files to change.
+4. Explain the design briefly.
+5. Make the requested changes.
+6. Update tests and docs when relevant.
+7. Provide the commit message used.
+8. Confirm the merge target.
+9. Stop.
+
+## Local Checks
+
+Run `make doctor` as part of machine/bootstrap validation to confirm the repository foundation is present and aligned.
+
+## Current Status
+
+The repository currently provides:
+- repository bootstrap
+- Codex/agent workflow foundation
+- collaboration setup
+- portable development baseline
+
+## After Phase 0
+
+Future technical decisions will be made explicitly in later phases once the workflow foundation is stable.
+
+## Contributing
+
+To contribute in the current phase:
+- read `AGENTS.md`
+- read `docs/WORKFLOW.md`
+- create a task branch from `develop`
+- keep tasks narrowly scoped
+
+## License
+
+License is currently unspecified.

docs/ARCHITECTURE.md

@@ -0,0 +1,42 @@
+# Architecture
+
+## Purpose
+
+This document will become the central architecture overview for HoopScout v2. It should summarize the current approved technical direction and provide a stable starting point for future implementation work.
+
+## Current Status
+
+This is still a phase-1 architecture overview, but the repository now has its first accepted concrete technical decision in `docs/adr/0001-runtime-and-development-stack.md`. Later implementation work should follow that corrected baseline unless a future ADR supersedes it.
+
+## Decision-Driven Development
+
+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.
+
+The current baseline decision is:
+- `ADR-0001`: runtime and development stack baseline
+
+The current baseline assumes:
+- Python 3
+- Django
+- PostgreSQL
+- containerized local development by default
+
+Future implementation work should assume the containerized workflow and PostgreSQL baseline rather than introducing non-containerized local setups or a different default database.
+
+## Future Sections Placeholder
+
+Future versions of this document may include sections such as:
+- system context
+- major components
+- data flow
+- deployment/runtime assumptions
+- integration boundaries
+- operational considerations

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/DECISION_PROCESS.md

@@ -0,0 +1,55 @@
+# Technical Decision Process
+
+## Purpose
+
+This document defines the repeatable process for evaluating technical options during phase 1. It exists to keep decisions consistent, reviewable, and useful for both humans and Codex before implementation begins.
+
+## When to Use This Process
+
+Use this process when a task needs to compare meaningful technical options or establish implementation guidance for later work. It applies to architecture choices, tooling direction, integration patterns, and other decisions that shape future implementation constraints.
+
+## Required Evaluation Criteria
+
+Every significant technical decision should evaluate at least:
+- simplicity
+- portability across machines
+- maintainability
+- operational complexity
+- testability
+- developer experience
+- cost
+- risk of lock-in
+- fit for the current project phase
+
+Additional criteria may be added when a decision requires them, but the standard set should always be considered first.
+
+## Decision Format
+
+Each decision should document:
+- the question being decided
+- the options considered
+- the trade-offs for each option
+- the evaluation against the required criteria
+- the preferred option
+- any open assumptions or follow-up constraints
+
+The result should be recorded in a repository document that is durable and reviewable. Major accepted decisions should be captured in ADRs.
+
+## Acceptance Rule
+
+A decision becomes accepted when:
+- the alternatives were compared explicitly
+- the trade-offs were documented clearly
+- the standard evaluation criteria were addressed
+- the chosen option is recorded in the repository
+- the outcome is treated as implementation guidance
+
+If those conditions are not met, the decision should remain proposed rather than treated as settled.
+
+## Relationship to ADRs
+
+ADRs are the durable record for important technical decisions. This process explains how to evaluate options before a decision is accepted. The ADR captures the final accepted outcome, context, and consequences once the decision is ready to guide future work.
+
+## Relationship to Implementation Tasks
+
+Implementation tasks should follow accepted decisions, not reopen them informally. If a task depends on an unresolved technical choice, the decision should be evaluated and documented first. If implementation reveals a new major choice, pause and record it through this process before proceeding.

docs/MACHINE_SETUP.md

@@ -1,37 +1,85 @@
 # Machine Setup
 
-## Goal
+## Purpose
 
-Bring a new machine to a usable Codex development state with minimal local-only setup.
+This document describes the minimum setup needed to continue repository work from a different machine. It is intended as a quick-start handoff for working with HoopScout v2 phase 0 using Codex and repository-defined agent workflows.
 
-## Local-only prerequisites
+## What Is Local-Only
 
-Not stored in the repo:
+These remain local responsibilities and should not be treated as repository-owned configuration:
 - Codex authentication
-- personal shell setup
+- personal shell aliases
-- secrets/API keys
+- personal editor preferences
-- local editor preferences
+- secrets
+- API keys
+- machine-specific paths unless only documented as examples
 
-## Repository bootstrap
+## What Is Repository-Owned
 
-1. Clone the repository
+These should be read from the repository and kept aligned in version control:
-2. Checkout `develop`
+- workflow rules
-3. Read:
+- branch policy
-   - AGENTS.md
+- task format
-   - docs/WORKFLOW.md
+- agent roles
-   - docs/TASK_TEMPLATE.md
+- setup instructions
-4. Ensure Codex can see:
+- test execution instructions
-   - AGENTS.md
+- docs for humans and agents
-   - .codex/config.toml
-   - .codex/agents/*
-   - .agents/skills/*
 
-## Validation checklist
+## Minimal Bootstrap Flow
 
-A machine is considered ready when:
+Use this sequence on a new machine:
-- repo is cloned
+
+1. Clone the repository.
+2. Checkout `develop`.
+3. Authenticate Codex locally.
+4. Read:
+   - `AGENTS.md`
+   - `docs/WORKFLOW.md`
+   - `docs/MACHINE_SETUP.md`
+   - `docs/TASK_TEMPLATE.md`
+5. Run `make doctor`.
+6. Create a task branch from `develop`.
+
+## Validation Checklist
+
+A machine is ready for repository work when:
+- repository is cloned
 - correct branch is checked out
-- Codex authentication is working
+- Codex auth is working
-- AGENTS.md is present at repo root
+- `AGENTS.md` is present
-- .codex/config.toml is present
+- `.codex/config.toml` is present
-- task branches can be created from develop
+- `.codex/agents/` is present
+- `.agents/skills/` is present
+- `docs/WORKFLOW.md` is present
+- `docs/MACHINE_SETUP.md` is present
+- `docs/TASK_TEMPLATE.md` is present
+- `make doctor` works
+
+## Local Checks
+
+Run `make doctor` during bootstrap to verify the repository bootstrap and local working assumptions.
+
+## Troubleshooting
+
+### Wrong Branch Checked Out
+
+Return to `develop`, update local state if needed, and create the correct task branch from there.
+
+### Codex Not Authenticated
+
+Complete Codex authentication locally on the machine before continuing. Authentication is not stored in the repository.
+
+### Missing Repository Files
+
+Confirm the repository was cloned correctly and that required tracked files such as `AGENTS.md`, `.codex/config.toml`, and the `docs/` files are present.
+
+### Local Assumptions Do Not Match Repository Instructions
+
+Follow the repository instructions rather than local habits. If the repository guidance is incomplete or outdated, update the tracked docs instead of relying on undocumented local behavior.
+
+## Related Files
+
+- `AGENTS.md`
+- `docs/WORKFLOW.md`
+- `docs/TASK_TEMPLATE.md`
+- `.codex/config.toml`

docs/PHASE_1.md

@@ -0,0 +1,57 @@
+# Phase 1
+
+## Purpose
+
+Phase 1 defines the technical decision-making framework that must be completed before implementation begins. This phase is about making and documenting core technical choices in a clear order so future work follows shared decisions rather than assumptions.
+
+## Scope
+
+Phase 1 establishes how technical and architectural decisions will be recorded, reviewed, and used to guide later implementation tasks.
+
+## In Scope
+
+- defining the major technical decisions required before implementation
+- documenting architecture decisions in a durable repository-owned form
+- establishing the relationship between architecture overview documents and ADRs
+- clarifying the minimum decision set required before implementation starts
+
+## Out of Scope
+
+Until the phase-1 decision framework is complete, do not:
+- start application implementation
+- introduce runtime services
+- choose implementation details that depend on unresolved architecture decisions
+- expand into feature delivery work
+- treat undocumented assumptions as approved decisions
+
+## Expected Outputs
+
+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
+
+## Decision Order
+
+Make decisions in this order:
+
+1. Define the required decision areas.
+2. Record the technical decision process and evaluation criteria.
+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

docs/TASK_TEMPLATE.md

@@ -1,14 +1,16 @@
 # Task Template
 
-Use this structure for Codex implementation tasks.
+## Purpose
 
-## Required opening
+This document defines the preferred structure for implementation and documentation tasks in this repository. It is intended to keep Codex work small, consistent, and easy to review for both humans and agents.
+
+## Required Opening
 
 - confirm branch strategy
-- name the branch to use
+- state the branch to use
-- state whether remote update succeeded or local state is being used
+- say whether local branch state or updated remote state is being used
 
-## Required execution structure
+## Required Execution Structure
 
 1. files to change
 2. short design explanation
@@ -17,9 +19,43 @@ Use this structure for Codex implementation tasks.
 5. merge target
 6. stop
 
-## Constraints
+## Scope Discipline
 
-- no work on main
+Each task should solve one clear problem. Unrelated cleanup, speculative refactoring, or adjacent changes should not be included unless they were explicitly requested.
-- no work on develop
+
-- no history rewrite
+## Branch Discipline
-- no broadening scope without approval
+
+- do not work directly on `main`
+- do not work directly on `develop`
+- create task branches from `develop`
+- merge task branches back into `develop`
+
+## Testing and Documentation Expectations
+
+- tests should be updated when behavior changes
+- docs should be updated when behavior changes
+- no test should be claimed as passed unless it was actually run
+
+## Small Examples
+
+Documentation-only task:
+- files to change: `README.md`
+- short design explanation: clarify current phase-0 repository purpose
+- code/doc/test changes: update documentation only
+- commit message: `docs: clarify phase 0 repository purpose`
+- merge target: `develop`
+- stop
+
+Code-change task:
+- files to change: `scripts/doctor.sh`, `Makefile`
+- short design explanation: add one validation check and expose it through `make doctor`
+- code/doc/test changes: update script, command entrypoint, and docs if behavior changes
+- commit message: `build: extend doctor validation`
+- merge target: `develop`
+- stop
+
+## Related Files
+
+- `AGENTS.md`
+- `docs/WORKFLOW.md`
+- `docs/MACHINE_SETUP.md`

docs/WORKFLOW.md

@@ -1,33 +1,95 @@
 # Workflow
 
-## Branch policy
+## Purpose
 
-Protected branches:
+This document defines the standard repository workflow for humans and coding agents working in HoopScout v2 phase 0. It describes how repository work should be organized, executed, and closed without drifting into product architecture decisions.
-- main
-- develop
 
-Normal task flow:
+## Branch Policy
-1. checkout develop
-2. create feature/<task-name>
-3. implement the task
-4. commit changes
-5. merge feature branch into develop
-6. delete feature branch when appropriate
 
-## When to use an umbrella branch
+- `main` is the stable branch.
+- `develop` is the integration branch.
+- Normal work happens on `feature/*` branches created from `develop`.
+- `release/*` branches are for release stabilization.
+- `hotfix/*` branches are for urgent production fixes.
 
-Use an umbrella branch only for a large coordinated effort that spans multiple dependent feature branches.
+## Protected Branch Rules
 
-If used, document:
+- Do not work directly on `main`.
+- Do not work directly on `develop`.
+- Do not rewrite history without explicit approval.
+- Do not broaden task scope unnecessarily.
+
+## Standard Task Flow
+
+The normal workflow for a focused task is:
+
+1. Checkout `develop`.
+2. Pull or otherwise update local state.
+3. Create a `feature/*` branch from `develop`.
+4. Complete one focused task.
+5. Commit the changes.
+6. Merge the branch back into `develop`.
+7. Delete the feature branch when appropriate.
+
+If a remote fetch or pull is unavailable, continue using local branch state and state that clearly in task communication.
+
+## Codex Task Discipline
+
+Codex work in this repository should follow this structure:
+
+1. Confirm branch strategy.
+2. State the branch to use.
+3. List the files to change.
+4. Explain the design briefly.
+5. Make the requested changes.
+6. Update tests and docs when relevant.
+7. Provide the commit message.
+8. Confirm the merge target.
+9. Stop.
+
+## Scope Discipline
+
+Each branch should solve one clear problem. Unrelated cleanup, opportunistic refactoring, or scope expansion should not be mixed into the same task unless explicitly approved.
+
+## When To Use an Umbrella Branch
+
+Umbrella branches should be rare. Use one only for a large coordinated effort that requires multiple related task branches to be integrated together before merging back into `develop`.
+
+If an umbrella branch is used, document:
 - why it exists
-- its exact name
+- the exact branch name
-- which child branches merge into it
+- which task branches merge into it
-- when it is expected to merge back into develop
+- when it is expected to merge back into `develop`
 
-## Task discipline
+## Review and Closeout Expectations
 
-Each task should:
+Before closing a task:
-- have one clear goal
+- changed files should match the task scope
-- have one task branch
+- docs should be updated if behavior changes
-- end with a commit and merge target confirmation
+- tests should be updated if behavior changes
-- not silently include unrelated cleanup
+- the merge target should be explicit
+
+## Machine Portability Note
+
+Durable workflow instructions must live in the repository, not only in local Codex configuration. Shared behavior should be documented in tracked files so contributors can work consistently across different machines.
+
+## Minimal Examples
+
+Example feature branch flow:
+
+```bash
+git checkout develop
+git pull
+# if git pull fails, continue using local branch state and say so explicitly
+git checkout -b feature/example-task
+# make focused changes
+git commit -m "docs: describe example task flow"
+git checkout develop
+git merge --no-ff feature/example-task
+```
+
+## Related Files
+
+- `AGENTS.md`
+- `docs/MACHINE_SETUP.md`
+- `docs/TASK_TEMPLATE.md`

docs/adr/0001-runtime-and-development-stack.md

@@ -0,0 +1,110 @@
+# ADR-0001: Runtime and Development Stack
+
+- Status: accepted
+- Date: 2026-03-20
+
+## Context
+
+HoopScout v2 is moving from phase-1 decision framing toward implementation guidance. The project needs one explicit baseline runtime and development stack decision so future implementation prompts do not depend on undocumented assumptions.
+
+The chosen baseline should fit the current architecture principles:
+- keep the stack small and maintainable
+- preserve portability across machines
+- avoid unnecessary operational complexity
+- support fast iteration and learning
+
+This decision covers:
+- programming language and runtime family
+- web application framework direction
+- persistence direction
+- whether containerization is part of the baseline developer workflow
+- acceptable operational complexity for the current stage
+
+This ADR is an intentional correction to the earlier baseline recorded in this same ADR. The previous non-containerized local workflow and SQLite baseline are rejected because they do not match the actual project requirement for containerized development with PostgreSQL as the default database direction.
+
+## Decision
+
+Use the following baseline unless a future ADR supersedes it:
+
+- language/runtime family: Python 3
+- web application framework direction: Django with a single deployable application by default
+- persistence direction: PostgreSQL is the baseline database direction
+- containerization: development must happen in containers by default
+- operational complexity: keep it low, but not at the expense of the required containerized workflow or the PostgreSQL baseline
+
+Practical rule for future implementation work:
+
+- assume Python 3
+- assume Django
+- assume PostgreSQL
+- assume a containerized development workflow
+
+Containerized development is part of the baseline, not an optional convenience.
+
+## Alternatives Considered
+
+### Option A: Python 3 + Django + PostgreSQL + required containerized development
+
+Chosen.
+
+This is the corrected baseline because it matches the actual project requirements and gives future implementation work one explicit, repeatable environment assumption.
+
+### Option B: Python 3 + Django + PostgreSQL + optional or non-containerized development
+
+Not chosen. This is explicitly rejected because development must be containerized. Allowing a non-containerized default would reintroduce machine-specific drift and contradict the project requirement.
+
+### Option C: Python 3 + Django + SQLite + required or optional containers
+
+Not chosen. SQLite is no longer the preferred baseline because the project requires PostgreSQL as the default persistence choice. Once containers are mandatory, the convenience advantage of SQLite is no longer enough to justify choosing a different database than the one future implementation should actually assume.
+
+### Option D: Python 3 + FastAPI + SQLAlchemy + PostgreSQL + required containerized development
+
+Not chosen. This remains a plausible stack in general, but it adds more assembly and more framework decisions than the current phase needs when Django already satisfies the baseline direction.
+
+## Trade-Offs
+
+Evaluation against the standard decision criteria:
+
+- simplicity: acceptable; the required container workflow adds setup structure, but the baseline stays simple by standardizing one framework, one database, and one development path
+- portability: strong fit; containerized development reduces machine-specific drift and gives contributors a more consistent environment
+- maintainability: good fit; Django and PostgreSQL are conventional, well-understood defaults with clear documentation paths
+- operational complexity: moderate but acceptable; containers and PostgreSQL add more moving parts than SQLite, but that complexity is required and bounded
+- testability: good fit; the baseline supports realistic database-backed testing against the same database family future work will assume
+- developer experience: acceptable to good; containers add overhead, but they reduce local setup ambiguity once the workflow is documented
+- fit for the current project phase: good fit; it is more structured than the earlier baseline, but it matches the actual requirement and avoids rework from an unrealistic database choice
+- lock-in risk: acceptable; Django shapes application structure and PostgreSQL becomes the assumed database family, but both are justified by the need for a stable, documented baseline
+
+Trade-offs accepted with this decision:
+- containerized development adds baseline workflow overhead compared with a purely local setup
+- PostgreSQL is heavier than SQLite for the smallest possible local start
+- Django remains opinionated, but that is acceptable for a maintainable default direction
+
+Why the earlier baseline is rejected:
+- non-containerized development is not acceptable because the project requirement is explicit and future work must assume one standard workflow
+- SQLite is not acceptable as the default baseline because future implementation should target PostgreSQL directly rather than split early assumptions from later reality
+
+## Consequences
+
+Future implementation work should assume:
+- Python as the default language
+- Django as the default application framework direction
+- PostgreSQL as the baseline persistence direction
+- local development is expected to run through a containerized workflow by default
+
+This correction is required, not optional. Future implementation prompts should assume containers and PostgreSQL unless a later ADR explicitly supersedes this baseline.
+
+This does not lock the project into a final production topology. It establishes the minimum stack direction needed for implementation to begin consistently.
+
+## Follow-Up Decisions Needed
+
+The following decisions are still expected later:
+- project layout and repository structure for the application code
+- container orchestration details for local development
+- Django and PostgreSQL service wiring details
+- testing tool and test execution details
+- deployment/runtime topology
+
+Still undecided after this correction:
+- exact container tooling details and command structure
+- exact PostgreSQL version/policy
+- how local secrets and environment configuration will be managed inside the containerized workflow

docs/adr/README.md

@@ -0,0 +1,71 @@
+# ADRs
+
+## What an ADR Is
+
+An ADR, or Architecture Decision Record, is a short document that captures one important technical decision, its context, and its outcome.
+
+## When To Create One
+
+Create an ADR when a decision:
+- affects architecture or major technical direction
+- changes implementation constraints for future work
+- needs durable reviewable documentation in the repository
+
+Before an ADR is accepted, compare alternatives using the technical decision process in `docs/DECISION_PROCESS.md`.
+
+## Minimum ADR Template
+
+Each ADR should include at least:
+- title
+- status
+- date
+- context
+- options considered
+- decision
+- consequences
+
+Minimal example:
+
+```md
+# ADR-0001: Example Decision
+
+- Status: proposed
+- Date: YYYY-MM-DD
+
+## Context
+
+What problem or uncertainty is being resolved?
+
+## Options Considered
+
+What meaningful alternatives were compared and why?
+
+## Decision
+
+What was chosen?
+
+## Consequences
+
+What follows from this decision?
+```
+
+## Status Values
+
+Use these status values:
+- proposed
+- accepted
+- superseded
+- rejected
+
+## Naming Convention
+
+Name ADR files using a numeric prefix and a short slug:
+
+```text
+ADR-0001-short-decision-name.md
+ADR-0002-another-decision.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.

scripts/doctor.sh

@@ -6,13 +6,17 @@ echo "== Repo doctor =="
 test -f AGENTS.md && echo "AGENTS.md: OK" || { echo "AGENTS.md: MISSING"; exit 1; }
 test -f .codex/config.toml && echo ".codex/config.toml: OK" || { echo ".codex/config.toml: MISSING"; exit 1; }
 test -d .codex/agents && echo ".codex/agents: OK" || { echo ".codex/agents: MISSING"; exit 1; }
-test -d docs && echo "docs/: OK" || { echo "docs/: MISSING"; exit 1; }
+test -d .agents/skills && echo ".agents/skills: OK" || { echo ".agents/skills: MISSING"; exit 1; }
+test -f .agents/skills/task-closeout/SKILL.md && echo ".agents/skills/task-closeout/SKILL.md: OK" || { echo ".agents/skills/task-closeout/SKILL.md: MISSING"; exit 1; }
+test -f docs/WORKFLOW.md && echo "docs/WORKFLOW.md: OK" || { echo "docs/WORKFLOW.md: MISSING"; exit 1; }
+test -f docs/MACHINE_SETUP.md && echo "docs/MACHINE_SETUP.md: OK" || { echo "docs/MACHINE_SETUP.md: MISSING"; exit 1; }
+test -f docs/TASK_TEMPLATE.md && echo "docs/TASK_TEMPLATE.md: OK" || { echo "docs/TASK_TEMPLATE.md: MISSING"; exit 1; }
 
 branch="$(git rev-parse --abbrev-ref HEAD)"
 echo "Current branch: ${branch}"
 
 if [[ "${branch}" == "main" || "${branch}" == "develop" ]]; then
-  echo "Warning: create a task branch before making changes."
+  echo "Warning: do not make changes on ${branch}; create a task branch from develop first."
 fi
 
-echo "Doctor completed."
+echo "Doctor completed."