artyomboyko · Jul 18, 2026 · Jul 13, 2026 · Jul 18, 2026 · Jul 18, 2026 · Jul 18, 2026
diff --git a/.github/REPOSITORY_SETTINGS.md b/.github/REPOSITORY_SETTINGS.md
@@ -54,4 +54,5 @@ GitHub Pages is published from the `/docs` folder on `main`.
 - Review Issues, PRs, and Actions logs.
 - Confirm About description, Website, topics, and social preview.
 - Confirm GitHub Actions checks and Pages deployment are green.
-- Create release `v1.2`.
+- Confirm citation metadata and release notes match the active standard version.
+- Create a tagged GitHub release when a tag is part of the publication plan.
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
@@ -29,6 +29,9 @@ Closes #
 - [ ] Forms are valid when changed.
 - [ ] Required stage or final result comment exists.
 - [ ] Smoke tests were run or reason is documented.
+- [ ] Mandatory containerization decision was confirmed when relevant, or not applicable.
+- [ ] Changed Compose configuration was rendered and checked, or reason and risk are documented.
+- [ ] Automated GUI tests avoid position-dependent selectors, or manual/supervised checks are documented.
 
 ## State updates
 

diff --git a/AGENTS.md b/AGENTS.md
@@ -12,11 +12,14 @@ Before meaningful work, read these files:
 8. `ai/TASK_REPORT_PROTOCOL.md`
 9. `ai/PROJECT_STATE.md`
 10. `ai/DECISIONS.md`
-11. related Issue or PR
-12. relevant handoffs through `ai/handoffs/INDEX.md`
+11. `ai/CONTAINERIZATION.md` when Docker or Compose is used, planned, present, or being discussed
+12. related Issue or PR
+13. relevant handoffs through `ai/handoffs/INDEX.md`
 
 Use GitHub Issues and Pull Requests as the primary workflow system.
 
 Report each meaningful Issue with a required stage or final result comment.
 
+When initializing Agent Handoff in a new repository or adding it to an existing repository, ask the user a separate explicit question about containerization and file layout before changing any Docker or Compose structure. Do not infer or automatically select the recommended approach.
+
 Keep `ai/` files compact.
diff --git a/AGENT_HANDOFF_STANDARD.md b/AGENT_HANDOFF_STANDARD.md
@@ -1,8 +1,8 @@
 ---
 standard: Agent Handoff
-version: "1.2"
+version: "1.3"
 status: active
-updated: 2026-07-07
+updated: 2026-07-18
 ---
 
 # Agent Handoff Standard
@@ -42,6 +42,8 @@ ai/handoffs/INDEX.md
 docs/en/
 ```
 
+For projects that use or plan Docker or Docker Compose, `ai/CONTAINERIZATION.md` is also required.
+
 ## Start order
 
 Before meaningful work, read:
@@ -56,8 +58,9 @@ Before meaningful work, read:
 8. `ai/TASK_REPORT_PROTOCOL.md`
 9. `ai/PROJECT_STATE.md`
 10. `ai/DECISIONS.md`
-11. related GitHub Issue or Pull Request
-12. relevant handoffs through `ai/handoffs/INDEX.md`
+11. `ai/CONTAINERIZATION.md` when Docker or Compose is used, planned, or being discussed
+12. related GitHub Issue or Pull Request
+13. relevant handoffs through `ai/handoffs/INDEX.md`
 
 ## Task result reports
 
@@ -84,6 +87,47 @@ Use `ai/TASK_REPORT_PROTOCOL.md` for the required comment templates.
 11. Update PR description.
 12. Leave a handoff when work is completed or interrupted.
 
+## Repository initialization and adoption decision gate
+
+When Agent Handoff is initialized in a new repository or added to an existing repository, the agent MUST inspect the repository and ask the user a separate, explicit question about containerization before changing any Docker or Compose structure.
+
+The question must confirm:
+
+- whether Docker or Docker Compose is used now or planned;
+- which container file layout the user wants;
+- for an existing repository, whether the current layout must be preserved or may be migrated;
+- whether production deployment configuration belongs in the same repository or a separate deployment repository.
+
+The agent MUST NOT infer this decision from existing files, an empty repository, general best practices, or the recommended default.
+
+Until the user answers, the agent must not create, move, rename, delete, or consolidate Dockerfiles, Compose files, build contexts, ignore files, container scripts, environment-file references, or container configuration.
+
+For an unanswered new-repository decision, create no container infrastructure. For an unanswered existing-repository decision, preserve the current layout.
+
+## Containerized project organization
+
+Agent Handoff supports these approaches:
+
+1. no repository-managed containerization;
+2. Dockerfiles colocated with service code and primary Compose files at the root;
+3. centralized Docker and Compose infrastructure under `docker/`;
+4. a hybrid layout with root Compose files, service-local Dockerfiles, and shared infrastructure under `docker/`;
+5. a modular monorepo layout with service-level container modules and explicit top-level orchestration;
+6. a separate deployment repository for production orchestration;
+7. preservation of an established or custom layout.
+
+The hybrid layout is the recommended option to present for many small and medium multi-service repositories, but it must never be selected without explicit user confirmation.
+
+The selected approach, canonical commands, build contexts, Compose file order, environment handling, and migration decision must be documented. Use `ai/CONTAINERIZATION.md` for the complete decision gate, layouts, migration rules, and verification requirements.
+
+## GUI testing
+
+Do not create brittle automated GUI tests that locate, interact with, or validate interface elements through absolute coordinates, screen position, pixel offsets, or incidental layout order.
+
+Position-dependent GUI checks must be performed manually or as supervised exploratory checks with Codex. They must not be committed as part of the routine automated test suite.
+
+Automated GUI tests should use stable semantic selectors such as roles, accessible names, labels, documented component identifiers, or dedicated test IDs.
+
 ## Definition of Done
 
 - related Issue or PR is linked;
@@ -95,7 +139,10 @@ Use `ai/TASK_REPORT_PROTOCOL.md` for the required comment templates.
 - PR description is updated;
 - risks are listed;
 - handoff exists for meaningful work;
-- `ai/handoffs/INDEX.md` is updated when needed.
+- `ai/handoffs/INDEX.md` is updated when needed;
+- mandatory initialization or adoption questions were answered when relevant;
+- container layout and canonical commands are recorded when Docker or Compose is used;
+- changed Compose configuration was rendered and checked, or the reason and risk are documented.
 
 ## Final rule
 

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,6 +2,23 @@
 
 All notable changes to Agent Handoff are documented here.
 
+## 1.3 - 2026-07-18
+
+### Added
+
+- GUI testing rule that prohibits brittle automated tests based on absolute coordinates, screen position, pixel offsets, or incidental layout order.
+- `ai/CONTAINERIZATION.md` with supported Docker and Docker Compose organization approaches.
+- Supported containerization choices for no repository-managed containers, colocated files, centralized `docker/`, hybrid layout, modular monorepos, separate deployment repositories, and established custom layouts.
+- Container layout migration inventory, verification, project-memory, and handoff requirements.
+- Release notes in `docs/releases/v1.3.md`.
+
+### Changed
+
+- New-repository initialization and existing-repository adoption now require a separate, explicit user decision about containerization and file layout.
+- Agents may not infer, create, relocate, consolidate, or migrate container infrastructure before the user answers the mandatory question.
+- The hybrid layout is a recommended option to present, not an automatic default.
+- Repository checks and the Pull Request checklist now cover the containerization protocol and decision gate.
+
 ## 1.2 - 2026-07-07
 
 ### Added

diff --git a/CITATION.cff b/CITATION.cff
@@ -4,7 +4,8 @@ title: "Agent Handoff: GitHub-native context handoff for AI coding agents"
 authors:
   - family-names: "Boyko"
     given-names: "Artyom"
-version: "1.2"
+version: "1.3"
+date-released: 2026-07-18
 url: "https://github.com/artyomboyko/Agent_Handoff"
 repository-code: "https://github.com/artyomboyko/Agent_Handoff"
 license: "GPL-3.0-only"
@@ -16,3 +17,5 @@ keywords:
   - "agent-memory"
   - "multi-agent-system"
   - "handoff-protocol"
+  - "docker-compose"
+  - "containerization"
diff --git a/README.md b/README.md
@@ -1,6 +1,6 @@
 # Agent Handoff
 
-[![Standard](https://img.shields.io/badge/standard-1.2-blue)](AGENT_HANDOFF_STANDARD.md)
+[![Standard](https://img.shields.io/badge/standard-1.3-blue)](AGENT_HANDOFF_STANDARD.md)
 [![Language](https://img.shields.io/badge/language-English-blue)](docs/en/README.md)
 [![GitHub native](https://img.shields.io/badge/GitHub-native-black)](ai/GITHUB_WORKFLOW.md)
 [![AI agent ready](https://img.shields.io/badge/AI%20agent-ready-purple)](ai/AGENT_IDENTITY.md)
@@ -50,6 +50,11 @@ Use the latest standard from https://github.com/artyomboyko/Agent_Handoff.
 Inspect the current repository first.
 Create or update the Agent Handoff files, GitHub Issue Forms, and Pull Request template.
 Keep the repository language English unless the downstream project explicitly chooses another language.
+
+Ask me a separate explicit question about Docker and Docker Compose organization before creating, moving, renaming, deleting, or consolidating any container files or paths.
+Ask whether containerization is used or planned, which supported layout I want, whether an existing layout must be preserved or may be migrated, and whether production deployment configuration belongs in this repository or a separate deployment repository.
+Do not infer the answer or choose the recommended layout automatically.
+
 Open a Pull Request and leave a compact handoff.
 ```
 
@@ -59,7 +64,7 @@ Open a Pull Request and leave a compact handoff.
 2. Git is the source of code truth.
 3. `ai/` is compact durable memory.
 4. Handoffs are short, structured, and reviewable.
-5. Humans stay in control.
+5. Humans stay in control of structural and migration decisions.
 
 ## What is included
 
@@ -73,10 +78,12 @@ Open a Pull Request and leave a compact handoff.
 | Task reports | [ai/TASK_REPORT_PROTOCOL.md](ai/TASK_REPORT_PROTOCOL.md) |
 | Agent identity | [ai/AGENT_IDENTITY.md](ai/AGENT_IDENTITY.md) |
 | Refactoring workflow | [ai/REFACTORING.md](ai/REFACTORING.md) |
+| Containerization | [ai/CONTAINERIZATION.md](ai/CONTAINERIZATION.md) |
 | Issue labels | [ISSUE_LABELS.md](ISSUE_LABELS.md) |
 | Issue status | [ISSUE_STATUS.md](ISSUE_STATUS.md) |
 | FAQ | [FAQ.md](FAQ.md) |
 | Examples | [examples/](examples/) |
+| Release notes | [docs/releases/v1.3.md](docs/releases/v1.3.md) |
 
 ## Comparison
 
@@ -90,15 +97,15 @@ Open a Pull Request and leave a compact handoff.
 
 ## Natural search terms
 
-Agent Handoff is related to AI coding agents, Codex-like agents, ChatGPT coding workflows, Cursor, Claude Code, LLM agents, project context, agent memory, GitHub workflow, multi-agent development, handoff protocol, pull request workflow, and human-agent collaboration.
+Agent Handoff is related to AI coding agents, Codex-like agents, ChatGPT coding workflows, Cursor, Claude Code, LLM agents, project context, agent memory, GitHub workflow, multi-agent development, handoff protocol, pull request workflow, containerization decisions, Docker Compose organization, and human-agent collaboration.
 
 ## For humans
 
 Use Agent Handoff to see who owns work, what changed, what was tested, what remains risky, and where the next contributor or agent should continue.
 
 ## For agents
 
-Start from `AGENTS.md`, read the required files, claim work in GitHub, open a Draft PR early, keep `ai/` compact, and leave a handoff when work is completed, paused, blocked, or transferred.
+Start from `AGENTS.md`, read the required files, claim work in GitHub, ask for required user decisions, open a Draft PR early, keep `ai/` compact, and leave a handoff when work is completed, paused, blocked, or transferred.
 
 ## Repository visibility