coding-agent-harness 1.0.1 → 1.0.2

package/docs-release/guides/parent-control-repository-pattern.en-US.md

@@ -0,0 +1,252 @@
+# Parent-Control Repository Pattern
+
+Chinese mirror: `docs-release/guides/parent-control-repository-pattern.md`
+
+The parent-control repository pattern is a repository organization model for multi-repo Coding Agent Harness projects.
+
+Its core rule is:
+
+> Business code may be distributed across many repositories, but the agent operating contract must not be distributed.
+
+The parent repository owns the harness. Child repositories own implementation facts.
+
+## Why This Pattern Exists
+
+Multi-repo projects often run into these failures:
+
+- Frontend, backend, SDK, and services each have their own plans, and no one can tell where the global release is blocked.
+- An agent starts inside a child repository, reads only local `AGENTS.md`, and misses cross-repo architecture constraints.
+- Each repository maintains its own Feature SSoT, and the states conflict.
+- Review evidence, test evidence, and walkthroughs are scattered across repositories, making it hard to prove that a cross-repo task is complete.
+
+The parent-control pattern solves a control-plane problem. It does not force code back into a monorepo. It moves the harness source of truth into one place.
+
+## Basic Topology
+
+```text
+product-control-repo/
+  AGENTS.md
+  README.md
+  docs/
+    01-GOVERNANCE/
+    02-PRODUCT/
+    03-ARCHITECTURE/
+    04-DEVELOPMENT/
+    05-TEST-QA/
+    06-INTEGRATIONS/
+    09-PLANNING/
+    10-WALKTHROUGH/
+    11-REFERENCE/
+  tools/
+    check-harness.mjs
+    internal-ci.mjs
+  frontend/       -> child repository
+  backend/        -> child repository
+  sdk/            -> child repository
+  services/auth/  -> child repository
+  services/bill/  -> child repository
+```
+
+Child repositories can be git submodules, git subtrees, workspace checkouts, fixed local paths, or entries in an internal repo registry. The technical mechanism matters less than ownership of facts:
+
+- The parent repository records global plans and evidence.
+- Child repositories record code and local verification.
+
+## Parent Repository Responsibilities
+
+The parent repository is the control plane.
+
+It should contain:
+
+- `AGENTS.md`: the single agent startup entrypoint and reading matrix.
+- `docs/03-ARCHITECTURE/repository-topology.md`: repository topology, owners, boundaries, dependency direction.
+- `docs/04-DEVELOPMENT/local-development.md`: cross-repo local startup, integration workflow, dependency setup.
+- `docs/06-INTEGRATIONS/`: cross-service APIs, events, SDKs, databases, permissions, and external contracts.
+- `docs/09-PLANNING/Feature-SSoT.md`: global feature and release state.
+- `docs/09-PLANNING/TASKS/`: cross-repo task contracts.
+- `docs/05-TEST-QA/Regression-SSoT.md`: cross-repo regression gates.
+- `docs/05-TEST-QA/Cadence-Ledger.md`: which changes trigger which checks.
+- `docs/10-WALKTHROUGH/`: cross-repo closeout and human confirmation.
+- `docs/11-REFERENCE/`: local standards for using Harness in this project.
+
+The parent repository should also provide a check command, for example:
+
+```bash
+node tools/check-harness.mjs
+```
+
+At minimum, that command should verify:
+
+- Required harness files exist.
+- `AGENTS.md` contains repo topology and child repo routing.
+- Current tasks have planning, progress, review, or closeout state.
+- Cross-repo regression gates have owners and evidence.
+- Child repo pointers, branches, commits, or release versions are recorded.
+
+## Child Repository Responsibilities
+
+Child repositories are the execution plane.
+
+They should contain:
+
+- Local `AGENTS.md`: repository rules, commands, stack, and test workflow.
+- Code, dependencies, lockfiles, and CI.
+- Repository-local reviews or pull requests.
+- Repository-local test evidence.
+
+Child repositories should not independently maintain the global Feature SSoT, and they should not decide whether a cross-repo release is complete.
+
+A child repository `AGENTS.md` can be short:
+
+````md
+# Backend Agent Guide
+
+This child repository owns the backend implementation.
+Parent-level planning, architecture, and cross-repo closeout live in `../docs/`.
+
+## Rules
+
+1. Keep API contracts aligned with the parent task plan.
+2. Do not change frontend or SDK assumptions without updating the parent integration docs.
+3. Run `npm run typecheck` after TypeScript changes.
+
+## Commands
+
+```bash
+npm install
+npm run typecheck
+npm test
+```
+````
+
+## Agent Startup Rule
+
+In the parent-control model, the default rule is:
+
+1. The agent starts from the parent repository.
+2. The agent reads the parent `AGENTS.md`.
+3. The agent reads parent architecture, development, integration, planning, and regression docs based on the task type.
+4. The agent enters one or more child repositories to make code changes.
+5. The agent runs local checks inside child repositories.
+6. The agent returns to the parent repository to record global evidence, review, walkthrough, and residuals.
+
+Do not let agents start cross-repo tasks from random child repositories. They will naturally miss global context.
+
+## Cross-Repo Task Contract
+
+Cross-repo tasks should be created in the parent repository:
+
+```text
+docs/09-PLANNING/TASKS/2026-05-22-example-cross-repo-feature/
+  brief.md
+  task_plan.md
+  execution_strategy.md
+  visual_map.md
+  progress.md
+  review.md
+```
+
+The task plan should state:
+
+- Which child repositories will be modified.
+- The write scope for each child repository.
+- Where shared contracts live, such as API schema, SDK types, or event format.
+- Which local checks each child repository must run.
+- The final cross-repo regression gate.
+- Who updates the parent global SSoT and walkthrough.
+
+A child repository commit is not the end of the task. It is evidence for the parent task.
+
+## What To Put In Architecture / Development / Integration
+
+In the parent-control model, the parent repository must document more external context than a single-repo project.
+
+### Architecture
+
+`docs/03-ARCHITECTURE/` explains how the system is split across repositories:
+
+- Repo topology.
+- Service boundaries.
+- Data flow.
+- Dependency direction.
+- Which repositories are product code and which are upstream references.
+- Which interfaces must not be called across boundaries directly.
+
+### Development
+
+`docs/04-DEVELOPMENT/` explains cross-repo development:
+
+- How to clone or initialize all child repositories.
+- How to install dependencies.
+- How to start the local integration environment.
+- Which ports, environment variables, accounts, or fixtures are shared.
+- How to validate the overall contract when only one child repository changed.
+
+### Integration
+
+`docs/06-INTEGRATIONS/` explains how repositories connect:
+
+- API contract.
+- SDK contract.
+- Event contract.
+- Database ownership.
+- Auth boundary.
+- Queue or topic ownership.
+- External vendor integration.
+- Breaking change policy.
+
+If these external facts are missing, the parent repository becomes only a bigger task list, not a real control plane.
+
+## Regression Strategy
+
+The parent `Regression-SSoT.md` should not duplicate every child repository test. It should define layered gates:
+
+| Gate | Location | Purpose |
+| --- | --- | --- |
+| Repo-local gate | Child repository | Prove local code did not break |
+| Contract gate | Parent repo or shared package | Prove cross-repo interfaces did not drift |
+| Integration gate | Parent tools or CI | Prove multiple child repositories can run together |
+| Release gate | Parent repository | Prove the current feature or release can close |
+
+Child repositories may run `npm test`, `pytest`, or `go test`. The parent repository projects those results into evidence that a release can understand.
+
+## Many Microservices
+
+If there are dozens or hundreds of repositories, do not hand-write long documentation for each one. The parent repository should maintain a repo registry:
+
+```md
+| Repo | Role | Owner | Local checks | Integration surface | Release critical |
+| --- | --- | --- | --- | --- | --- |
+| `services/auth` | auth service | platform | `go test ./...` | JWT, user session events | yes |
+| `services/bill` | billing service | revenue | `npm test` | invoice events, payment API | yes |
+| `frontend` | product shell | product | `npm run typecheck` | backend API, SDK client | yes |
+```
+
+The agent does not need to read all docs in 100 repositories at startup. It reads the parent task first, then enters only the repositories relevant to the current task.
+
+## Anti-Patterns
+
+Avoid:
+
+- Each child repository maintaining its own global Feature SSoT.
+- A parent repository with only a README and no task, regression, or closeout surface.
+- Child `AGENTS.md` files copying large sections from the parent, causing drift.
+- Starting cross-repo tasks from a child repository and backfilling parent records at the end.
+- Putting all business code directly in the parent repository and losing independent release ability.
+- Recording only child repository test passes without contract and release gates.
+
+## Minimum Adoption Checklist
+
+To adopt the parent-control model, start with:
+
+- Parent `AGENTS.md` states that this is the control repository.
+- `docs/03-ARCHITECTURE/repository-topology.md` lists all child repositories.
+- `docs/09-PLANNING/Feature-SSoT.md` is the global feature source of truth.
+- `docs/05-TEST-QA/Regression-SSoT.md` defines local, contract, integration, and release gates.
+- Each child repository has only a short local `AGENTS.md`.
+- New cross-repo tasks are created only in the parent repository.
+- Child commits, PRs, and test output are recorded as parent task evidence.
+
+## One Sentence
+
+The parent-control repository pattern does not add a repository for its own sake. It gives a multi-repo product one harness brain.

package/docs-release/guides/parent-control-repository-pattern.md

@@ -0,0 +1,252 @@
+# 主控仓库模式
+
+English mirror: `docs-release/guides/parent-control-repository-pattern.en-US.md`
+
+主控仓库模式是一种多仓库 Coding Agent Harness 组织方式。
+
+它的核心判断是：
+
+> 业务代码可以分散在很多仓库，但 Agent 的运行合同不能分散。
+
+父仓库管理 Harness。子仓库管理代码执行事实。
+
+## 为什么需要这个模式
+
+多仓项目里，经常出现这些问题：
+
+- 前端、后端、SDK、微服务各有自己的计划，没人知道全局 release 到底卡在哪里。
+- Agent 从某个子仓库启动，只看到局部 `AGENTS.md`，忽略了跨仓架构约束。
+- 每个仓库各自维护 Feature SSoT，状态互相冲突。
+- Review 证据、测试证据、walkthrough 分散在不同仓库，最后无法证明一个跨仓任务真正完成。
+
+主控仓库模式解决的是控制面问题。它不是要求把代码放回单仓，而是把 Harness 的事实源收回一个地方。
+
+## 基本拓扑
+
+```text
+product-control-repo/
+  AGENTS.md
+  README.md
+  docs/
+    01-GOVERNANCE/
+    02-PRODUCT/
+    03-ARCHITECTURE/
+    04-DEVELOPMENT/
+    05-TEST-QA/
+    06-INTEGRATIONS/
+    09-PLANNING/
+    10-WALKTHROUGH/
+    11-REFERENCE/
+  tools/
+    check-harness.mjs
+    internal-ci.mjs
+  frontend/       -> child repository
+  backend/        -> child repository
+  sdk/            -> child repository
+  services/auth/  -> child repository
+  services/bill/  -> child repository
+```
+
+子仓库可以是 git submodule、git subtree、workspace checkout、固定路径约定，或由内部工具解析的 repo registry。关键不是技术形式，而是事实归属：
+
+- 父仓库记录全局计划和证据。
+- 子仓库记录代码和局部验证。
+
+## 父仓库职责
+
+父仓库是 control plane。
+
+它应该包含：
+
+- `AGENTS.md`：Agent 的唯一启动入口和读文件矩阵。
+- `docs/03-ARCHITECTURE/repository-topology.md`：仓库拓扑、owner、边界、依赖方向。
+- `docs/04-DEVELOPMENT/local-development.md`：跨仓本地启动、联调、依赖安装。
+- `docs/06-INTEGRATIONS/`：跨服务 API、事件、SDK、数据库、权限、外部系统契约。
+- `docs/09-PLANNING/Feature-SSoT.md`：全局 feature 和 release 状态。
+- `docs/09-PLANNING/TASKS/`：跨仓任务合同。
+- `docs/05-TEST-QA/Regression-SSoT.md`：跨仓 regression gates。
+- `docs/05-TEST-QA/Cadence-Ledger.md`：哪些变更触发哪些检查。
+- `docs/10-WALKTHROUGH/`：跨仓 closeout 和人工确认。
+- `docs/11-REFERENCE/`：本项目使用 Harness 的本地标准。
+
+父仓库还应该有一个检查命令，例如：
+
+```bash
+node tools/check-harness.mjs
+```
+
+这个命令至少检查：
+
+- 必需 Harness 文件存在。
+- `AGENTS.md` 含有 repo topology 和子仓库路由。
+- 当前任务有计划、进度、review 或 closeout 状态。
+- 跨仓 regression gate 有 owner 和 evidence。
+- 子仓库 pointer、branch、commit 或 release version 已记录。
+
+## 子仓库职责
+
+子仓库是 execution plane。
+
+它应该包含：
+
+- 局部 `AGENTS.md`：本仓库规则、命令、技术栈、测试方式。
+- 代码、依赖、lockfile、CI。
+- 本仓库局部 review 或 PR。
+- 本仓库局部测试证据。
+
+子仓库不应该单独维护全局 Feature SSoT，也不应该自己决定跨仓 release 是否完成。
+
+一个子仓库 `AGENTS.md` 可以很短：
+
+````md
+# Backend Agent Guide
+
+This child repository owns the backend implementation.
+Parent-level planning, architecture, and cross-repo closeout live in `../docs/`.
+
+## Rules
+
+1. Keep API contracts aligned with the parent task plan.
+2. Do not change frontend or SDK assumptions without updating the parent integration docs.
+3. Run `npm run typecheck` after TypeScript changes.
+
+## Commands
+
+```bash
+npm install
+npm run typecheck
+npm test
+```
+````
+
+## Agent 启动规则
+
+主控仓库模式下，默认规则是：
+
+1. Agent 从父仓库启动。
+2. Agent 先读父仓库 `AGENTS.md`。
+3. Agent 根据任务类型读取父仓库的 architecture、development、integration、planning、regression 文档。
+4. Agent 进入一个或多个子仓库执行代码变更。
+5. Agent 在子仓库跑局部检查。
+6. Agent 回到父仓库记录全局证据、review、walkthrough、residual。
+
+不要让 Agent 直接从随机子仓库启动跨仓任务。那样它会天然缺少全局上下文。
+
+## 跨仓任务合同
+
+跨仓任务应该在父仓库创建：
+
+```text
+docs/09-PLANNING/TASKS/2026-05-22-example-cross-repo-feature/
+  brief.md
+  task_plan.md
+  execution_strategy.md
+  visual_map.md
+  progress.md
+  review.md
+```
+
+任务计划至少说明：
+
+- 哪些子仓库会被修改。
+- 每个子仓库的 write scope。
+- 共享契约在哪里，例如 API schema、SDK type、事件格式。
+- 每个子仓库要跑哪些局部检查。
+- 最终跨仓 regression gate 是什么。
+- 谁负责更新父仓库的全局 SSoT 和 walkthrough。
+
+子仓库提交不是独立任务的终点，而是父任务的 evidence。
+
+## Architecture / Development / Integration 要写什么
+
+主控仓库模式下，父仓库必须比单仓项目多写三类外围事实。
+
+### Architecture
+
+`docs/03-ARCHITECTURE/` 说明系统如何被拆成多个仓库：
+
+- repo topology。
+- 服务边界。
+- 数据流。
+- 依赖方向。
+- 哪些仓库是产品代码，哪些是 upstream reference。
+- 哪些接口不能跨边界直接调用。
+
+### Development
+
+`docs/04-DEVELOPMENT/` 说明如何跨仓工作：
+
+- 如何 clone 或初始化所有子仓库。
+- 如何安装依赖。
+- 如何启动本地联调环境。
+- 哪些端口、环境变量、账号或 fixture 是共享的。
+- 如何在只改一个子仓库时仍然验证整体契约。
+
+### Integration
+
+`docs/06-INTEGRATIONS/` 说明仓库之间如何对接：
+
+- API contract。
+- SDK contract。
+- event contract。
+- database ownership。
+- auth boundary。
+- queue/topic ownership。
+- external vendor integration。
+- breaking change policy。
+
+如果这些外围事实不写，主控仓库只会变成一个更大的任务列表，而不会真正控制多仓协作。
+
+## 回归策略
+
+父仓库的 `Regression-SSoT.md` 不应该复制所有子仓库测试。它应该定义分层 gate：
+
+| Gate | 位置 | 目的 |
+| --- | --- | --- |
+| Repo-local gate | 子仓库 | 证明局部代码没有坏 |
+| Contract gate | 父仓库或共享包 | 证明跨仓接口没有漂移 |
+| Integration gate | 父仓库工具或 CI | 证明多个子仓库可以一起运行 |
+| Release gate | 父仓库 | 证明当前 feature/release 可以收口 |
+
+子仓库可以自己跑 `npm test`、`pytest`、`go test`。父仓库负责把这些结果投影成 release 能看懂的证据。
+
+## 微服务很多时怎么做
+
+如果有几十个或上百个仓库，不要给每个仓库手写大段文档。父仓库应该维护 repo registry：
+
+```md
+| Repo | Role | Owner | Local checks | Integration surface | Release critical |
+| --- | --- | --- | --- | --- | --- |
+| `services/auth` | auth service | platform | `go test ./...` | JWT, user session events | yes |
+| `services/bill` | billing service | revenue | `npm test` | invoice events, payment API | yes |
+| `frontend` | product shell | product | `npm run typecheck` | backend API, SDK client | yes |
+```
+
+Agent 不需要在启动时读 100 个仓库的所有文档。它先读父任务，再按 repo registry 进入本次相关的几个仓库。
+
+## 反模式
+
+避免这些做法：
+
+- 每个子仓库各自维护全局 Feature SSoT。
+- 父仓库只有 README，没有任务、回归和 closeout。
+- 子仓库 `AGENTS.md` 复制父仓库大段内容，导致漂移。
+- 跨仓任务从子仓库启动，最后再补父仓库记录。
+- 父仓库直接承载所有业务代码，失去子仓库独立发布能力。
+- 只记录子仓库测试通过，不记录跨仓 contract 和 release gate。
+
+## 最小落地清单
+
+采用主控仓库模式时，先做到这些：
+
+- 父仓库 `AGENTS.md` 写清楚它是 control repo。
+- `docs/03-ARCHITECTURE/repository-topology.md` 列出所有子仓库。
+- `docs/09-PLANNING/Feature-SSoT.md` 成为全局 feature source of truth。
+- `docs/05-TEST-QA/Regression-SSoT.md` 定义局部、契约、集成、发布 gate。
+- 每个子仓库只有短的局部 `AGENTS.md`。
+- 新跨仓任务只在父仓库创建。
+- 子仓库 commit、PR、test output 都作为父任务 evidence。
+
+## 一句话
+
+主控仓库模式不是为了多建一个仓库，而是为了让多仓项目只有一个 Harness 大脑。

package/docs-release/guides/repository-operating-models.en-US.md

@@ -0,0 +1,196 @@
+# Repository Operating Models
+
+Chinese mirror: `docs-release/guides/repository-operating-models.md`
+
+Coding Agent Harness can live inside different repository structures. If you choose the wrong one, the main problem is not "not enough docs." The harness itself becomes another source of confusion.
+
+This guide explains three common models:
+
+- Single-repo model: one code repository, one harness.
+- Independent multi-repo model: multiple code repositories, each with its own harness.
+- Parent-control repository model: one parent control repository owns the harness, while child repositories hold implementation facts.
+
+## Quick Choice
+
+| Model | Fits | Does not fit | Harness source of truth |
+| --- | --- | --- | --- |
+| Single repo | One product, one code repository, clear team boundary | A system already split across independently released repositories | Current repo `AGENTS.md` + `docs/` |
+| Independent multi-repo | Frontend, backend, SDK, or services evolve independently and cross-repo work is rare | Frequent cross-repo features and one shared release plan | Each repo's own `AGENTS.md` + `docs/` |
+| Parent-control repo | Microservices, many subsystems, shared roadmap, cross-repo releases, agents need one startup point | Small projects or short-lived script repositories | Parent repo `AGENTS.md` + `docs/` |
+
+## Single-Repo Model
+
+The single-repo model is the simplest. Code, plans, regression state, and walkthroughs live in one repository.
+
+```text
+product-repo/
+  AGENTS.md
+  docs/
+    03-ARCHITECTURE/
+    04-DEVELOPMENT/
+    05-TEST-QA/
+    09-PLANNING/
+    10-WALKTHROUGH/
+    11-REFERENCE/
+  src/
+  tests/
+```
+
+The agent starts at the repository root, reads `AGENTS.md`, then moves into task files and code.
+
+### When To Choose It
+
+- The application, service, script, or library is in one repository.
+- A feature usually modifies only this repository.
+- Regression commands can run inside one checkout.
+- The team wants to adopt Harness quickly without first changing repository structure.
+
+### Risk
+
+When the project later splits into several repositories, the single-repo harness can lose global visibility. Frontend, backend, and SDK repositories may each have local state, but no single place explains whether the cross-repo task is actually complete.
+
+## Independent Multi-Repo Model
+
+The independent multi-repo model gives each repository its own harness.
+
+```text
+frontend-repo/
+  AGENTS.md
+  docs/
+
+backend-repo/
+  AGENTS.md
+  docs/
+
+sdk-repo/
+  AGENTS.md
+  docs/
+```
+
+Each repository entrypoint only governs that repository. Frontend tasks are planned and closed in the frontend repo. Backend tasks are planned and closed in the backend repo.
+
+### When To Choose It
+
+- The repositories are genuinely independent from an organizational point of view.
+- Each repository has its own owners, release cadence, and review rules.
+- Cross-repo tasks are rare, or humans coordinate them manually.
+- One repository's harness should not know another repository's internal state.
+
+### Required External Context
+
+Independent multi-repo mode is not just "copy the template into every repo." If you do that, cross-repo context disappears.
+
+Each repository should document its external boundary in:
+
+- `docs/03-ARCHITECTURE/`: where this repository sits in the overall system.
+- `docs/04-DEVELOPMENT/`: sibling repo dependencies and local integration startup.
+- `docs/06-INTEGRATIONS/`: APIs, events, SDKs, queues, databases, auth, and other contracts.
+- `docs/05-TEST-QA/Regression-SSoT.md`: which checks cover this repository only and which require integration across repositories.
+- `AGENTS.md`: whether agents should stop, switch repositories, or ask humans when a task crosses repository boundaries.
+
+### Risk
+
+The risk is harness fragmentation:
+
+- The frontend Feature SSoT says a task is complete while the backend Regression SSoT is still red.
+- An SDK breaking change is not projected into the product shell.
+- An agent starts from a child repository, sees only local facts, and incorrectly treats the global task as complete.
+
+If this happens often, move to the parent-control repository model.
+
+## Parent-Control Repository Model
+
+The parent-control model puts the harness in a parent repository. Child repositories hold implementation facts.
+
+```text
+product-control-repo/
+  AGENTS.md
+  docs/
+    03-ARCHITECTURE/
+    04-DEVELOPMENT/
+    05-TEST-QA/
+    06-INTEGRATIONS/
+    09-PLANNING/
+    10-WALKTHROUGH/
+    11-REFERENCE/
+  tools/
+  frontend/   -> child repository
+  backend/    -> child repository
+  sdk/        -> child repository
+  service-a/  -> child repository
+  service-b/  -> child repository
+```
+
+The parent repository is the control plane. It owns:
+
+- Overall architecture and repo topology.
+- Cross-repo Feature SSoT.
+- Task plans, reviews, and walkthroughs.
+- Regression SSoT and cross-repo cadence.
+- Agent entrypoint and reading matrix.
+- Evidence for child repository commits, branches, submodule pointers, or release versions.
+
+Child repositories are the execution plane. They own:
+
+- Code implementation.
+- Repository-local dependencies and lockfiles.
+- Repository-local tests and CI.
+- Repository-local `AGENTS.md`.
+- Concrete commits and pull requests.
+
+### When To Choose It
+
+- One product is delivered by multiple repositories.
+- Features often touch frontend, backend, SDKs, or services together.
+- You want every agent to start from one entrypoint.
+- You need unified task state, review gates, and release closeout.
+- There are many services, and you cannot let each repository maintain its own global plan.
+
+### Main Benefit
+
+The parent-control model fixes global truth in one place. Even if there are 100 child repositories, the agent first reads the parent task contract, then enters the specific child repository to execute.
+
+This avoids:
+
+- Conflicting Feature SSoTs.
+- Each child repo saying "done" while the release still cannot ship.
+- Agents starting from the wrong repository and seeing only local context.
+- Cross-repo review and regression evidence scattered across many places.
+
+See `docs-release/guides/parent-control-repository-pattern.en-US.md` for the full method.
+
+## Moving Between Models
+
+### Single Repo To Multi-Repo
+
+When a single repository splits into frontend, backend, or SDK repositories, do not copy the same `docs/` tree into every repository.
+
+Decide first:
+
+- Which tasks remain global?
+- Which tasks become repository-local?
+- Does the old Regression SSoT stay at a parent layer or split into local gates?
+- Where should agents start in the future?
+
+If cross-repo features remain common, create a parent-control repository.
+
+### Independent Multi-Repo To Parent-Control
+
+Migration order:
+
+1. Create the parent `AGENTS.md` and repo topology.
+2. Move global Feature SSoT, Regression SSoT, and walkthrough index into the parent repository.
+3. Keep local `AGENTS.md` files in child repositories, but point global planning back to the parent.
+4. Create new cross-repo tasks only in the parent repository.
+5. Treat child repository commits as evidence for parent tasks.
+
+Do not rewrite all historical tasks at once. Start by moving the current release and active features into the parent repository.
+
+## Recommended Defaults
+
+- New small project: single-repo model.
+- Several strongly independent teams: independent multi-repo model.
+- One product, multiple code repositories, one release target: parent-control model.
+- Many microservices that need unified agent collaboration: parent-control model.
+
+The real decision is not the number of repositories. It is whether global decisions need one source of truth.