# Architecture Constraints Packet

本文档是当前 Codex Harness / agent 安装包改造的架构约束真相源。所有 `feature_impl`、安装器改造、doctor gate、manifest/lock 迁移和默认安装语义切换任务，都必须先满足本文件，再进入实现、Stage 1 Review 和发布验证。

## 1. System Shape

- `delivery_shape`: `cli` + `automation` + `package`
- `runtime_model`: `command`
- `deployment_unit`: `package`
- `production_entrypoints`:
  - `tools/install/install-agent.ps1`
  - `docs/codex-harness-engineering/templates/package-assets/root/install-agent.ps1`
  - `tools/harness/codex-loop.ps1`
  - `docs/codex-harness-engineering/templates/runtime/codex-loop.ps1`
  - `tools\harness\doctor.ps1`
  - `tools\harness\verify.ps1`
  - `refresh-agent-package.ps1`
  - `tools/harness/tests/test-install-modes.ps1`

当前项目不是 Web 应用、后端服务、数据库服务或 UI 工程；HTTP、UI route、DB migration、container deployment 均为 `not_applicable`。

## 2. Public Interface Boundary

- `public_interfaces`: `CLI`, `file format`, `package API`
- `contract_source`: `docs/agent-package-redesign/target-layering-standard.md`, `docs/agent-package-redesign/migration-plan.md`, `docs/harness/install-manifest-governance.md`, `docs/harness/new-project-usage.md`, `task.json`
- `interface_trace_rule`:
  - 每个安装器公开入口必须能追踪到 `install-manifest.json`、lock/config 写入规则、doctor 检查和 smoke 测试。
  - 每个 driver/runtime 行为变更必须能追踪到 `tools\harness\codex-loop.ps1`、`task.json`、trace 输出和验证命令。
  - 每个 package surface 变更必须运行 `refresh-agent-package.ps1 -Surface all -Fix`，并用 `-CheckOnly` 证明 root、`agent/`、templates 和 ai-sync 元数据一致。

## 3. Data Boundary

- `persistence_boundary`: `filesystem`
- `schema_or_migration_required`: `no`
- `repository_policy`:
  - 真实交付路径是 PowerShell 脚本对目标项目文件系统的受控读写，以及 JSON/Markdown manifest、lock、config、task 和 trace 文件。
  - 测试可以使用临时目录 fixture，但不能把 fixture-only 行为冒充真实安装语义；所有安装语义必须通过 `tools/harness/tests/test-install-modes.ps1` 或等价 smoke 命令覆盖。
  - JSON 文件必须通过 JSON parser 验证，不用字符串拼接冒充结构化写入。
- `consistency_requirements`:
  - `install-manifest.json`、`.codex-harness/locks/package.lock.json`、`.codex-harness/state/config.json`、用户级 package lock 和 ai-sync metadata 必须可审计。
  - managed file 必须记录 hash；发现 drift 时默认阻断写入、升级或卸载。
  - `-MigratePlan` 必须只读；迁移执行必须以 plan 分类为输入语义来源。

## 4. Async And Worker Boundary

- `async_required`: `no`
- `scheduling_model`: `manual command`
- `concurrency_control`: `single process`
- `time_source`: `server time`

`tools\harness\codex-loop.ps1 -RunUntilDone` 可以串行调度多个 `task.json` 任务，但每轮只处理一个依赖已满足且 `passes=false` 的任务。不得手工把未验证任务标记为 `passes=true`。

## 5. Test Double Policy

- `test_double_allowed_scope`: `unit_tests_only` and `temporary_install_fixtures`
- `mock_as_acceptance_evidence`: `no`
- `minimum_integration_evidence`:
  - PowerShell parser 检查：root、agent、template runtime 脚本。
  - JSON parse：`task.json`、`install-manifest.json`、schema、ai-sync metadata、project task template。
  - Install smoke：旧 `-Mode full/project/vendor/user` 兼容路径，新 `-Scope user/project/vendor`，默认 thin 切换前后的目标路径。
  - Doctor/manifest gate：`tools\harness\doctor.ps1`、`refresh-agent-package.ps1 -Surface all -CheckOnly`。
  - 发布前完整验证：`tools\harness\verify.ps1`。

## 6. Forbidden Implementations

- 禁止把默认 thin project install 做成复制完整 `.agents/skills`、`.agents/workflows`、package docs 或 template source。
- 禁止在未确认迁移计划时递归删除 `.agents/`、`docs/harness/`、`docs/testing/`、`docs/knowledge/` 或 `docs/requirement-prep-kit/`。
- 禁止让 `-MigratePlan` 写文件、创建 lock 或删除目录。
- 禁止绕过 `blocked-user-drift`、`unknown-legacy-file`、`manual-review` 分类直接写 lock 或删除文件。
- 禁止把 `missing-vendor-file` 写入 `managedFiles`。
- 禁止修改 `-Mode full/project/vendor/user` 兼容行为，除非任务明确进入默认切换阶段并保留显式 legacy/vendor 入口。
- 禁止通过字符串拼接 shell 命令执行删除、移动或覆盖；Windows 文件操作必须使用 PowerShell 原生命令和 `-LiteralPath`。
- 禁止只运行 `git diff --check` 就声明实现任务完成；必须运行任务声明的 smoke、doctor、refresh CheckOnly 或 verify。

## 7. Architecture Fitness Checks

最低可执行检查如下：

```powershell
powershell -NoProfile -Command "[scriptblock]::Create((Get-Content -Raw .\tools\harness\codex-loop.ps1)) | Out-Null; [scriptblock]::Create((Get-Content -Raw .\docs\codex-harness-engineering\templates\runtime\codex-loop.ps1)) | Out-Null; [scriptblock]::Create((Get-Content -Raw .\tools\install\install-agent.ps1)) | Out-Null; 'parser ok'"
powershell -NoProfile -Command "Get-Content -Raw .\task.json | ConvertFrom-Json | Out-Null; Get-Content -Raw .\tools\harness\templates\project-task-template.json | ConvertFrom-Json | Out-Null; Get-Content -Raw .\install-manifest.json | ConvertFrom-Json | Out-Null; 'json ok'"
powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\harness\tests\test-install-modes.ps1
powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\harness\doctor.ps1
powershell -NoProfile -ExecutionPolicy Bypass -File .\refresh-agent-package.ps1 -RepoRoot . -PackageRoot agent -Surface all -CheckOnly
powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\harness\verify.ps1
git diff --check
```

文档或契约任务可按 `task.json.test_command` 缩小验证范围，但不能跳过对应的 package freshness 和 whitespace 检查。实现任务必须覆盖 install smoke、doctor 和相关 JSON/PowerShell parser 检查。

## 8. Definition Of Done

- 任务的 `architecture_constraints` 和 `forbidden_implementations` 与本文件一致，且没有冲突。
- 新增或修改的公开 CLI 参数在文档、安装器、doctor/smoke 和 manifest/lock 语义中一致。
- 当前仓库、package templates 和 ai-sync metadata 同步通过。
- Stage 1 Review 能以本文件和任务 context files 作为 architecture truth source 给出 PASS。
- Stage 2 Review 能看到对应测试、doctor、refresh CheckOnly 或 verify 证据。
- 完成声明必须列出默认安装语义、兼容入口、迁移入口、验证命令和剩余风险。
