@aipper/aiws-spec 0.0.1

package/templates/workspace/changes/README.md

@@ -0,0 +1,55 @@
+# changes/（变更工件目录）
+
+本目录用于保存每一次“需求交付 / 问题修复”的可审计产物，避免关键约定只存在于聊天记录。
+
+真值文件仍然是：
+- `AI_PROJECT.md`（约束真值）
+- `AI_WORKSPACE.md`（运行/测试真值）
+- `REQUIREMENTS.md`（需求/验收真值）
+
+建议结构：
+```
+changes/
+  README.md
+  <change-id>/
+    proposal.md
+    design.md        # 可选
+    tasks.md
+    .ws-change.json
+  archive/
+    YYYY-MM-DD-<change-id>/
+```
+
+常用命令（推荐使用 `aiws`；不依赖 dotfiles）：
+- `aiws change start <change-id>`（推荐：自动切到 `change/<change-id>` 并初始化工件目录）
+- `aiws change new <change-id>`
+- `aiws change list`
+- `aiws change status <change-id>`
+- `aiws change next <change-id>`
+- `aiws change validate <change-id>`
+- `aiws change sync <change-id>`
+- `aiws change archive <change-id>`
+
+Active change（推荐，团队共享）：
+- 使用分支名声明当前变更：`change/<change-id>`（也支持 `changes/`、`ws/`、`ws-change/`）
+- 切到该分支后，可省略 `<change-id>` 执行：`aiws change status|next|validate|sync|archive`
+
+模板覆盖（可选）：
+- 在工作区创建 `changes/templates/` 可覆盖默认模板：
+  - `changes/templates/proposal.md`
+  - `changes/templates/tasks.md`
+  - `changes/templates/design.md`
+- 快速初始化模板：`aiws change templates init`
+- 查看模板来源：`aiws change templates which`
+
+注意：
+- 不要把任何 secrets 写进 proposal/design/tasks（账号、token、内网地址等用本地私有文件/环境变量）。
+- 若真值文件（`AI_PROJECT.md` / `AI_WORKSPACE.md` / `REQUIREMENTS.md`）在变更期间发生变化，严格校验/归档会要求先运行 `aiws change sync <change-id>` 确认基线。
+
+Hooks/CI（推荐，硬约束）：
+- 工作区会安装 `.githooks/{pre-commit,pre-push}`（默认执行 `aiws validate .`）与门禁脚本（`tools/ws_change_check.py`、`tools/requirements_contract.py`）。
+- **启用 hooks 需要本地配置**（不会自动提交到 git）：
+  - 直接启用：`git config core.hooksPath .githooks`
+  - 或使用：`aiws hooks install .`（等价）
+- CI 建议增加一步（对 PR 分支执行）：`aiws validate .`。
+- 紧急跳过（不推荐）：`WS_CHANGE_HOOK_BYPASS=1 ...`（CI 不应允许跳过）。

package/templates/workspace/changes/templates/design.md

@@ -0,0 +1,29 @@
+# Design: {{CHANGE_ID}}
+
+> Title: {{TITLE}}
+>
+> Created: {{CREATED_AT}}
+
+## Context
+
+- <!-- WS:TODO 背景、现状、约束（语言/框架/部署/性能/安全） -->
+
+## Goals / Non-Goals
+
+**Goals:**
+- <!-- WS:TODO -->
+
+**Non-Goals:**
+- <!-- WS:TODO -->
+
+## Decisions
+
+- <!-- WS:TODO 关键技术决策 + 为什么 -->
+
+## Risks / Trade-offs
+
+- <!-- WS:TODO 风险 → 缓解 -->
+
+## Migration / Rollback
+
+- <!-- WS:TODO 如涉及数据/接口迁移，写步骤；必须含回滚路径 -->

package/templates/workspace/changes/templates/proposal.md

@@ -0,0 +1,59 @@
+# Change Proposal: {{CHANGE_ID}}
+
+> Title: {{TITLE}}
+>
+> Created: {{CREATED_AT}}
+
+## 目标与非目标
+
+**目标：**
+- <!-- WS:TODO 填写本次变更的目标（可验收） -->
+
+**非目标：**
+- <!-- WS:TODO 填写明确“不做什么”，防止 scope creep -->
+
+## 变更归因（强制二选一）
+
+- 需求交付：`Req_ID` = <!-- WS:TODO -->
+- 问题修复：`Problem_ID` = <!-- WS:TODO -->
+
+> 备注：若“问题阻塞需求”，两边都要在各自 CSV 的 `Notes` 字段互相引用对方 ID。
+
+## 现状与问题
+
+- <!-- WS:TODO 现状是什么、痛点是什么；必要时给证据（日志/截图/issue 链接） -->
+
+## 方案概述（What changes）
+
+- <!-- WS:TODO 逐条写清要改什么（行为/接口/数据/配置）；BREAKING 请标注 -->
+
+## 影响范围（Scope）
+
+- 影响的服务/模块/目录：
+  - <!-- WS:TODO -->
+- 可能影响的外部接口/使用方：
+  - <!-- WS:TODO -->
+
+## 风险与回滚
+
+- 风险：
+  - <!-- WS:TODO -->
+- 回滚方案（必须可执行）：
+  - <!-- WS:TODO -->
+
+## 验证计划（必须可复现）
+
+> 从 `AI_WORKSPACE.md` 选择最贴近本变更的验证入口，写成可直接复制执行的命令。
+
+- 命令：
+  - <!-- WS:TODO 例如：`uv run tools/server_test_runner.py --workspace .` -->
+- 期望结果：
+  - <!-- WS:TODO 例如：所有相关用例 DONE；无新增错误日志 -->
+
+## 真值文件/合同更新清单
+
+- `REQUIREMENTS.md`：<!-- WS:TODO 需要/不需要；如需要，写明新增/修改的验收条款 -->
+- `requirements/CHANGELOG.md`：<!-- WS:TODO 需要/不需要 -->
+- `requirements/requirements-issues.csv`：<!-- WS:TODO 需要/不需要 -->
+- `issues/problem-issues.csv`：<!-- WS:TODO 需要/不需要 -->
+- 证据落盘（`.agentdocs/tmp/...`）：<!-- WS:TODO 计划输出哪些报告/日志 -->

package/templates/workspace/changes/templates/tasks.md

@@ -0,0 +1,33 @@
+# Tasks: {{CHANGE_ID}}
+
+> Title: {{TITLE}}
+>
+> Created: {{CREATED_AT}}
+
+## 0. Preflight
+
+- [ ] 0.1 阅读并遵守 `AI_PROJECT.md` / `AI_WORKSPACE.md` / `REQUIREMENTS.md`
+- [ ] 0.2 运行门禁校验：`aiws validate .`（或 `npx -y @aipper/aiws validate .`）
+- [ ] 0.3 若真值文件发生变化（例如你更新了 REQUIREMENTS.md），同步基线：`aiws change sync {{CHANGE_ID}}`
+
+## 1. 需求/问题合同（如适用）
+
+- [ ] 1.1 需求交付：补齐/更新 `REQUIREMENTS.md` 验收条款（或确认不需要）
+- [ ] 1.2 同步 `requirements/requirements-issues.csv`（或更新 `issues/problem-issues.csv`）
+- [ ] 1.3 记录到 `requirements/CHANGELOG.md`（如需求发生变化）
+
+## 2. 实现
+
+- [ ] 2.1 <!-- WS:TODO -->
+- [ ] 2.2 <!-- WS:TODO -->
+
+## 3. 验证（必须可复现）
+
+- [ ] 3.1 <!-- WS:TODO 写具体命令（来自 AI_WORKSPACE.md） -->
+- [ ] 3.2 <!-- WS:TODO 写期望结果（可判断 DONE/FAIL） -->
+
+## 4. 交付与归档
+
+- [ ] 4.1 证据落盘到 `.agentdocs/tmp/...`（报告/日志/请求响应等）
+- [ ] 4.2 交叉审计（可选但推荐）：在 AI 工具内运行 `/ws-review`（或按 `AI_PROJECT.md` 手工审计）
+- [ ] 4.3 归档：`aiws change archive {{CHANGE_ID}}`

package/templates/workspace/issues/problem-issues.csv

@@ -0,0 +1,2 @@
+Problem_ID,Type,Severity,Title,Symptom,Repro,Root_Cause,Fix_Plan,Files,Tests,Evidence,Status,Owner,Created_At,Updated_At,Notes
+PROB-000,BUG,P2,示例：/api/system/menu/routes 返回 500,"访问 routes 接口报 500；日志提示参数解析错误","curl -sS -H 'Authorization: Bearer <token>' 'http://localhost:8080/api/system/menu/routes?x=1'","Controller 入参类型与前端实际 query 不一致","对齐入参定义并补充单测；复测 runner 端点状态更新为 DONE","server/src/...","uv run tools/server_test_runner.py --workspace . --service backend --max-endpoints 10",".agentdocs/tmp/server-test/report.json",TODO,ab,YYYY-MM-DDTHH:MM:SSZ,YYYY-MM-DDTHH:MM:SSZ,"若该问题阻塞某个需求交付，在 requirements/requirements-issues.csv 的 Notes 里关联 Problem_ID"

package/templates/workspace/manifest.json

@@ -0,0 +1,205 @@
+{
+  "template_id": "workspace",
+  "template_version": 2,
+  "defaults": {
+    "include_optional": true,
+    "tools": ["claude", "opencode", "codex", "iflow"]
+  },
+  "required": [
+    "AGENTS.md",
+    "AI_PROJECT.md",
+    "AI_WORKSPACE.md",
+    "REQUIREMENTS.md",
+    ".gitignore",
+    ".aiws/manifest.json",
+    ".githooks/pre-commit",
+    ".githooks/pre-push",
+    "changes/README.md",
+    "requirements/CHANGELOG.md",
+    "requirements/requirements-issues.csv",
+    "issues/problem-issues.csv",
+    ".agents/skills/**",
+    "tools/ws_change_check.py",
+    "tools/requirements_contract.py",
+    ".claude/commands/aiws-init.md",
+    ".claude/commands/aiws-update.md",
+    ".claude/commands/aiws-validate.md",
+    ".claude/commands/aiws-rollback.md",
+    ".claude/commands/ws-preflight.md",
+    ".claude/commands/ws-migrate.md",
+    ".claude/commands/ws-dev.md",
+    ".claude/commands/ws-analyze.md",
+    ".claude/commands/ws-review.md",
+    ".claude/commands/ws-rule.md",
+    ".claude/commands/ws-req-review.md",
+    ".claude/commands/ws-req-change.md",
+    ".claude/commands/ws-req-contract-sync.md",
+    ".claude/commands/ws-req-contract-validate.md",
+    ".claude/commands/ws-req-flow-sync.md",
+    ".opencode/command/aiws-init.md",
+    ".opencode/command/aiws-update.md",
+    ".opencode/command/aiws-validate.md",
+    ".opencode/command/aiws-rollback.md",
+    ".opencode/command/ws-preflight.md",
+    ".opencode/command/ws-migrate.md",
+    ".opencode/command/ws-dev.md",
+    ".opencode/command/ws-analyze.md",
+    ".opencode/command/ws-review.md",
+    ".opencode/command/ws-rule.md",
+    ".opencode/command/ws-req-review.md",
+    ".opencode/command/ws-req-change.md",
+    ".opencode/command/ws-req-contract-sync.md",
+    ".opencode/command/ws-req-contract-validate.md",
+    ".opencode/command/ws-req-flow-sync.md",
+    ".iflow/commands/aiws-init.toml",
+    ".iflow/commands/aiws-update.toml",
+    ".iflow/commands/aiws-validate.toml",
+    ".iflow/commands/aiws-rollback.toml",
+    ".iflow/commands/server-test-plan.toml",
+    ".iflow/commands/server-test.toml",
+    ".iflow/commands/server-triage.toml",
+    ".iflow/commands/server-fix.toml",
+    ".iflow/commands/server-fix-and-commit.toml",
+    ".iflow/commands/server-drain.toml",
+    ".iflow/commands/server-commit.toml",
+    ".iflow/commands/server_test-plan.toml",
+    ".iflow/commands/server_test.toml",
+    ".iflow/commands/ws-preflight.toml",
+    ".iflow/commands/ws-migrate.toml",
+    ".iflow/commands/ws-dev.toml",
+    ".iflow/commands/ws-analyze.toml",
+    ".iflow/commands/ws-review.toml",
+    ".iflow/commands/ws-rule.toml",
+    ".iflow/commands/ws-contract-check.toml",
+    ".iflow/commands/ws-doctor.toml",
+    ".iflow/commands/ws-env-doctor.toml",
+    ".iflow/commands/ws-init.toml",
+    ".iflow/commands/ws-memory-bank-init.toml",
+    ".iflow/commands/ws-feature-plan.toml",
+    ".iflow/commands/ws-feature-deliver.toml",
+    ".iflow/commands/ws-req-review.toml",
+    ".iflow/commands/ws-req-change.toml",
+    ".iflow/commands/ws-req-contract-sync.toml",
+    ".iflow/commands/ws-req-contract-validate.toml",
+    ".iflow/commands/ws-req-flow-sync.toml"
+  ],
+  "optional": [
+    ".iflow/agents/**",
+    "memory-bank/**",
+    "secrets/test-accounts.example.json",
+    "changes/templates/proposal.md",
+    "changes/templates/tasks.md",
+    "changes/templates/design.md",
+    "tools/requirements_contract_sync.py",
+    "tools/requirements_flow_gen.py",
+    "tools/server_test_runner.py",
+    "tools/iflow_watchdog.sh",
+    "tools/install_iflow_watchdog_systemd_user.sh"
+  ],
+  "update": {
+    "replace_file": [
+      ".aiws/manifest.json",
+      ".githooks/pre-commit",
+      ".githooks/pre-push",
+      "tools/ws_change_check.py",
+      "tools/requirements_contract.py",
+      ".agents/skills/aiws-init/SKILL.md",
+      ".agents/skills/aiws-rollback/SKILL.md",
+      ".agents/skills/aiws-update/SKILL.md",
+      ".agents/skills/aiws-validate/SKILL.md",
+      ".agents/skills/aiws-hooks-install/SKILL.md",
+      ".agents/skills/aiws-hooks-status/SKILL.md",
+      ".agents/skills/aiws-change-list/SKILL.md",
+      ".agents/skills/aiws-change-new/SKILL.md",
+      ".agents/skills/aiws-change-start/SKILL.md",
+      ".agents/skills/aiws-change-status/SKILL.md",
+      ".agents/skills/aiws-change-next/SKILL.md",
+      ".agents/skills/aiws-change-sync/SKILL.md",
+      ".agents/skills/aiws-change-validate/SKILL.md",
+      ".agents/skills/aiws-change-archive/SKILL.md",
+      ".agents/skills/aiws-change-templates-which/SKILL.md",
+      ".agents/skills/aiws-change-templates-init/SKILL.md",
+      ".agents/skills/ws-analyze/SKILL.md",
+      ".agents/skills/ws-commit/SKILL.md",
+      ".agents/skills/ws-dev/SKILL.md",
+      ".agents/skills/ws-migrate/SKILL.md",
+      ".agents/skills/ws-plan/SKILL.md",
+      ".agents/skills/ws-preflight/SKILL.md",
+      ".agents/skills/ws-req-change/SKILL.md",
+      ".agents/skills/ws-req-contract-sync/SKILL.md",
+      ".agents/skills/ws-req-contract-validate/SKILL.md",
+      ".agents/skills/ws-req-flow-sync/SKILL.md",
+      ".agents/skills/ws-req-review/SKILL.md",
+      ".agents/skills/ws-review/SKILL.md",
+      ".agents/skills/ws-rule/SKILL.md",
+      ".iflow/commands/aiws-init.toml",
+      ".iflow/commands/aiws-update.toml",
+      ".iflow/commands/aiws-validate.toml",
+      ".iflow/commands/aiws-rollback.toml",
+      ".iflow/commands/server-test-plan.toml",
+      ".iflow/commands/server-test.toml",
+      ".iflow/commands/server-triage.toml",
+      ".iflow/commands/server-fix.toml",
+      ".iflow/commands/server-fix-and-commit.toml",
+      ".iflow/commands/server-drain.toml",
+      ".iflow/commands/server-commit.toml",
+      ".iflow/commands/server_test-plan.toml",
+      ".iflow/commands/server_test.toml",
+      ".iflow/commands/ws-preflight.toml",
+      ".iflow/commands/ws-migrate.toml",
+      ".iflow/commands/ws-dev.toml",
+      ".iflow/commands/ws-analyze.toml",
+      ".iflow/commands/ws-review.toml",
+      ".iflow/commands/ws-rule.toml",
+      ".iflow/commands/ws-contract-check.toml",
+      ".iflow/commands/ws-doctor.toml",
+      ".iflow/commands/ws-env-doctor.toml",
+      ".iflow/commands/ws-init.toml",
+      ".iflow/commands/ws-memory-bank-init.toml",
+      ".iflow/commands/ws-feature-plan.toml",
+      ".iflow/commands/ws-feature-deliver.toml",
+      ".iflow/commands/ws-req-review.toml",
+      ".iflow/commands/ws-req-change.toml",
+      ".iflow/commands/ws-req-contract-sync.toml",
+      ".iflow/commands/ws-req-contract-validate.toml",
+      ".iflow/commands/ws-req-flow-sync.toml"
+    ],
+    "managed_blocks": {
+      "AGENTS.md": ["agents"],
+      "AI_PROJECT.md": ["ai-project:core"],
+      "AI_WORKSPACE.md": ["ai-workspace:core"],
+      "REQUIREMENTS.md": ["requirements:contract"],
+      ".gitignore": ["gitignore"],
+      ".claude/commands/aiws-init.md": ["claude:aiws-init"],
+      ".claude/commands/aiws-update.md": ["claude:aiws-update"],
+      ".claude/commands/aiws-validate.md": ["claude:aiws-validate"],
+      ".claude/commands/aiws-rollback.md": ["claude:aiws-rollback"],
+      ".claude/commands/ws-preflight.md": ["claude:ws-preflight"],
+      ".claude/commands/ws-migrate.md": ["claude:ws-migrate"],
+      ".claude/commands/ws-dev.md": ["claude:ws-dev"],
+      ".claude/commands/ws-analyze.md": ["claude:ws-analyze"],
+      ".claude/commands/ws-review.md": ["claude:ws-review"],
+      ".claude/commands/ws-rule.md": ["claude:ws-rule"],
+      ".claude/commands/ws-req-review.md": ["claude:ws-req-review"],
+      ".claude/commands/ws-req-change.md": ["claude:ws-req-change"],
+      ".claude/commands/ws-req-contract-sync.md": ["claude:ws-req-contract-sync"],
+      ".claude/commands/ws-req-contract-validate.md": ["claude:ws-req-contract-validate"],
+      ".claude/commands/ws-req-flow-sync.md": ["claude:ws-req-flow-sync"],
+      ".opencode/command/aiws-init.md": ["opencode:aiws-init"],
+      ".opencode/command/aiws-update.md": ["opencode:aiws-update"],
+      ".opencode/command/aiws-validate.md": ["opencode:aiws-validate"],
+      ".opencode/command/aiws-rollback.md": ["opencode:aiws-rollback"],
+      ".opencode/command/ws-preflight.md": ["opencode:ws-preflight"],
+      ".opencode/command/ws-migrate.md": ["opencode:ws-migrate"],
+      ".opencode/command/ws-dev.md": ["opencode:ws-dev"],
+      ".opencode/command/ws-analyze.md": ["opencode:ws-analyze"],
+      ".opencode/command/ws-review.md": ["opencode:ws-review"],
+      ".opencode/command/ws-rule.md": ["opencode:ws-rule"],
+      ".opencode/command/ws-req-review.md": ["opencode:ws-req-review"],
+      ".opencode/command/ws-req-change.md": ["opencode:ws-req-change"],
+      ".opencode/command/ws-req-contract-sync.md": ["opencode:ws-req-contract-sync"],
+      ".opencode/command/ws-req-contract-validate.md": ["opencode:ws-req-contract-validate"],
+      ".opencode/command/ws-req-flow-sync.md": ["opencode:ws-req-flow-sync"]
+    }
+  }
+}

package/templates/workspace/memory-bank/README.md

@@ -0,0 +1,14 @@
+# Memory Bank（工作区上下文）
+
+目的：给 iFlow/Codex/Claude 一个“固定且可持续更新”的上下文集合，避免每次会话重新讲一遍导致跑偏。
+
+在你的工作区中：
+- `REQUIREMENTS.md` 仍是**需求真值**（不要复制到这里）。
+- `AI_PROJECT.md` / `AI_WORKSPACE.md` 是**边界与运行真值**。
+- 本目录补齐的是“实现过程中的稳定上下文”（更偏工程视角）。
+
+建议规则：
+- 改代码前：先看 `REQUIREMENTS.md` + `AI_PROJECT.md` + `AI_WORKSPACE.md`，再结合本目录的 `architecture.md`/`progress.md`。
+- 每次完成一个可验证的小步：更新 `progress.md`（写清：做了什么、证据路径、下一步）。
+- 发生重大结构变化：更新 `architecture.md`（只写高层关系，不要堆细节）。
+

package/templates/workspace/memory-bank/architecture.md

@@ -0,0 +1,9 @@
+# Architecture
+
+目标：记录“模块关系与关键边界”，让新的会话可以快速对齐代码布局。
+
+建议包含：
+- 目录/模块分层（例如 server/web/app）
+- 核心数据流（请求入口 → service → repo → DB）
+- 关键约束（鉴权、request-id、幂等、事务）
+

package/templates/workspace/memory-bank/implementation-plan.md

@@ -0,0 +1,11 @@
+# Implementation Plan
+
+目标：把需求拆成可验证的小步（每步都有验证命令与期望结果）。
+
+模板（示例字段）：
+- Step 1: …
+  - Scope:
+  - Files:
+  - Verify: `...`
+  - Expected:
+

package/templates/workspace/memory-bank/progress.md

@@ -0,0 +1,10 @@
+# Progress
+
+每次完成一个可验证小步就追加一条：
+
+- YYYY-MM-DD HH:MM: 做了什么（关联 Issue_ID/验收项）
+  - Changed: `path/to/file`
+  - Verify: `command`
+  - Evidence: `path/to/log_or_report`
+  - Next:
+

package/templates/workspace/memory-bank/tech-stack.md

@@ -0,0 +1,11 @@
+# Tech Stack
+
+填写原则：只写“确实在用且影响决策”的信息，避免长篇大论。
+
+建议包含：
+- 语言/运行时版本（例如 Java/Node/Python）
+- 构建工具链（Gradle/Maven、pnpm、uv 等）
+- 关键框架与约束（Spring Boot、Ktor、Vue、React 等）
+- 数据层（DB/Redis/MQ）与迁移方式
+- 本地/测试环境切换方式（引用 `AI_WORKSPACE.md` 的命令即可）
+

package/templates/workspace/requirements/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Requirements Changelog
+
+本文件记录“需求变更历史”。`REQUIREMENTS.md` 始终表示“当前有效需求”，变更过程在此追踪。
+
+规则：
+- 任何需求变更必须追加一条记录（不要覆盖历史）。
+- 记录应可审计：说明变更内容、原因、影响范围、关联 issues/PR。
+- 不要写入 secrets。
+
+| 日期 | 变更内容 | 原因/背景 | 影响范围（模块/接口） | 关联 issues/PR | 记录人 |
+|---|---|---|---|---|---|
+| YYYY-MM-DD | | | | | |
+

package/templates/workspace/requirements/requirements-issues.csv

@@ -0,0 +1,2 @@
+Req_ID,Title,Change_Type,Module,CRUD,Actor,Scenario,Preconditions,Inputs,Outputs,Data_Model,Business_Logic,API_Impact,NonFunctional,Spec_Status,Impl_Status,Tests,Evidence,Owner,Created_At,Updated_At,Notes
+REQ-000,示例：用户列表分页支持按部门筛选,ADD,system/user,R,admin,管理员在用户管理页按部门筛选列表,已登录且有 system:user:list 权限,"deptId=10&page=1&pageSize=20",返回包含 deptId=10 的用户列表,"user,dept 表（字段：dept_id）","查询条件增加 deptId；默认不传不筛选；分页参数边界：page>=1&pageSize<=100",GET /api/system/user/list 新增 query 参数 deptId（可选），响应字段不变,性能：分页查询需走索引；安全：权限不变,READY,TODO,"uv run tools/server_test_runner.py --workspace . --service demo-spring --max-endpoints 10",.agentdocs/tmp/server-test/report.json,ab,YYYY-MM-DDTHH:MM:SSZ,YYYY-MM-DDTHH:MM:SSZ,

package/templates/workspace/secrets/test-accounts.example.json

@@ -0,0 +1,32 @@
+{
+  "base_url": "http://127.0.0.1:8080",
+  "services": {
+    "backend": {
+      "base_url": "http://127.0.0.1:8080"
+    }
+  },
+  "test_resource_ids": {
+    "id": "1"
+  },
+  "auth": {
+    "type": "login",
+    "login_path": "/login",
+    "username_field": "username",
+    "password_field": "password",
+    "token_json_path": "token",
+    "header_name": "Authorization",
+    "scheme": "Bearer"
+  },
+  "accounts": [
+    {
+      "name": "smoke-user",
+      "username": "user@example.com",
+      "password": "<password>"
+    }
+  ],
+  "openapi_auth": {
+    "type": "basic",
+    "username": "<doc-user>",
+    "password": "<doc-pass>"
+  }
+}

package/templates/workspace/tools/iflow_watchdog.sh

@@ -0,0 +1,138 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# iFlow unattended watchdog for AI Workspace (Arch Linux/systemd friendly).
+#
+# Goal:
+# - Run /server-drain in a loop (low output, small batches).
+# - If drain reports BLOCKED (exit 3) or crashes, run /server-fix in a fresh iFlow process (bounded).
+# - Keep outputs in .agentdocs/tmp/server-test/ to avoid blowing up interactive sessions.
+#
+# Safety:
+# - Intended for test environments only.
+# - Requires explicit IFLOW_WATCHDOG_YOLO=1 to run with --yolo.
+
+die() { echo "error: $*" >&2; exit 2; }
+need_file() { [[ -f "$1" ]] || die "missing: $1"; }
+have() { command -v "$1" >/dev/null 2>&1; }
+
+root="${IFLOW_WATCHDOG_ROOT:-.}"
+cd "$root"
+
+need_file "AI_WORKSPACE.md"
+need_file "REQUIREMENTS.md"
+need_file "tools/server_test_runner.py"
+need_file "secrets/test-accounts.json"
+
+have iflow || die "missing: iflow"
+have uv || die "missing: uv (runner requires uv)"
+
+csv="issues/server-api-issues.csv"
+workspace_dir="$(pwd)"
+log_dir="${IFLOW_WATCHDOG_LOG_DIR:-$workspace_dir/.agentdocs/tmp/server-test}"
+mkdir -p "$log_dir"
+
+fatal_log="$log_dir/watchdog-fatal.log"
+timestamp() { date +"%Y-%m-%dT%H:%M:%S%z"; }
+say() { printf "[%s] %s\n" "$(timestamp)" "$*"; }
+fatal() { say "fatal: $*" | tee -a "$fatal_log" >&2; exit 2; }
+
+yolo="${IFLOW_WATCHDOG_YOLO:-0}"
+if [[ "$yolo" != "1" ]]; then
+  fatal "unattended mode requires IFLOW_WATCHDOG_YOLO=1 (this will use iflow --yolo; test env only)"
+fi
+
+if ! iflow --version >/dev/null 2>&1; then
+  fatal "iflow command failed (check auth/config/environment)"
+fi
+
+date_suffix="$(date +%Y%m%d)"
+drain_log="${IFLOW_WATCHDOG_DRAIN_LOG:-$log_dir/iflow-drain-$date_suffix.log}"
+fix_log="${IFLOW_WATCHDOG_FIX_LOG:-$log_dir/iflow-fix-$date_suffix.log}"
+find "$log_dir" -maxdepth 1 -type f -name "iflow-*.log" -mtime +7 -delete 2>/dev/null || true
+
+lock_dir="$log_dir/.watchdog.lock"
+pid_file="$lock_dir/pid"
+if ! mkdir "$lock_dir" 2>/dev/null; then
+  other_pid="$(cat "$pid_file" 2>/dev/null || true)"
+  fatal "another watchdog is running (lock: $lock_dir pid=${other_pid:-unknown})"
+fi
+printf "%s\n" "$$" >"$pid_file" 2>/dev/null || true
+
+cleanup() {
+  say "cleanup: stopping child iflow processes (if any)" >>"$fatal_log" 2>/dev/null || true
+  pkill -P $$ iflow 2>/dev/null || true
+  rm -f "$pid_file" 2>/dev/null || true
+  rmdir "$lock_dir" 2>/dev/null || true
+}
+trap cleanup EXIT INT TERM
+
+drain_timeout="${IFLOW_WATCHDOG_DRAIN_TIMEOUT:-7200}"
+fix_timeout="${IFLOW_WATCHDOG_FIX_TIMEOUT:-3600}"
+drain_max_turns="${IFLOW_WATCHDOG_DRAIN_MAX_TURNS:-6}"
+fix_max_turns="${IFLOW_WATCHDOG_FIX_MAX_TURNS:-12}"
+drain_max_tokens="${IFLOW_WATCHDOG_DRAIN_MAX_TOKENS:-15000}"
+fix_max_tokens="${IFLOW_WATCHDOG_FIX_MAX_TOKENS:-30000}"
+
+max_cycles="${IFLOW_WATCHDOG_MAX_CYCLES:-200}"
+sleep_s="${IFLOW_WATCHDOG_SLEEP_S:-10}"
+fix_retry_max="${IFLOW_WATCHDOG_FIX_RETRY_MAX:-3}"
+fix_retry_file="$log_dir/.fix-retry-count"
+
+drain_max_endpoints="${IFLOW_DRAIN_MAX_ENDPOINTS:-30}"
+drain_sleep_s="${IFLOW_DRAIN_SLEEP_S:-0}"
+
+csv_has_blocked() { [[ -f "$csv" ]] && grep -qE ",BLOCKED," "$csv"; }
+
+run_drain() {
+  say "run: /server-drain (max_endpoints=$drain_max_endpoints)"
+  IFLOW_DRAIN_MAX_ENDPOINTS="$drain_max_endpoints" \
+  IFLOW_DRAIN_SLEEP_S="$drain_sleep_s" \
+  iflow --yolo -p "/server-drain" --timeout "$drain_timeout" --max-turns "$drain_max_turns" --max-tokens "$drain_max_tokens" >>"$drain_log" 2>&1
+}
+
+run_fix() {
+  say "run: /server-fix"
+  retry_count="$(cat "$fix_retry_file" 2>/dev/null || echo 0)"
+  if [[ "$retry_count" -ge "$fix_retry_max" ]]; then
+    fatal "fix reached retry limit ($fix_retry_max); check $fix_log"
+  fi
+  if iflow --yolo -p "/server-fix" --timeout "$fix_timeout" --max-turns "$fix_max_turns" --max-tokens "$fix_max_tokens" >>"$fix_log" 2>&1; then
+    rm -f "$fix_retry_file" 2>/dev/null || true
+  else
+    echo $((retry_count + 1)) >"$fix_retry_file" 2>/dev/null || true
+  fi
+}
+
+say "watchdog: start (cycles=$max_cycles sleep_s=$sleep_s)"
+say "logs: drain=$drain_log fix=$fix_log"
+
+cycle=1
+while [[ "$cycle" -le "$max_cycles" ]]; do
+  if csv_has_blocked; then
+    say "state: BLOCKED detected in $csv (trigger fix)"
+    run_fix
+  fi
+
+set +e
+run_drain
+rc=$?
+set -e
+
+if [[ "$rc" == "0" ]]; then
+  say "done: drain finished with all DONE/SKIP"
+  exit 0
+fi
+
+if [[ "$rc" == "3" ]] || csv_has_blocked; then
+  say "blocked: drain reported BLOCKED (rc=$rc), trigger fix"
+  run_fix
+else
+  say "warn: drain exited rc=$rc without BLOCKED; will retry"
+fi
+
+sleep "$sleep_s" || true
+cycle=$((cycle + 1))
+done
+
+fatal "reached max cycles ($max_cycles); check logs under $log_dir"