software-engineering-workflow-skill

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Software Engineering Workflow Skill

软件工程工作流 Skill

Overview

概述

Produce a structured planning workflow for software changes: triage scope, build future-state runtime call stacks per use case, verify those call stacks with a dedicated review artifact, and drive implementation with plan + real-time progress tracking. For medium/large scope, include a full proposed design document organized by architecture direction plus separation of concerns. This workflow is stage-gated. Do not batch-generate all artifacts by default. In this skill, future-state runtime call stacks are future-state (

to-be

) execution models. They are not traces of current (

as-is

) implementation behavior.

为软件变更生成结构化规划工作流：判定范围，基于每个用例构建目标态运行时调用栈，使用专门的评审产物验证这些调用栈，并通过计划与实时进度跟踪推动实现。对于 Medium/Large 范围，包含一份完整的设计文档，按架构方向与关注点分离组织。此工作流采用阶段门禁。默认不得一次性批量生成所有产物。在本 Skill 中，目标态运行时调用栈是目标态（

to-be

）执行模型，而不是当前态（

as-is

）实现行为的追踪记录。

Workflow

工作流

Ticket Folder Convention (Project-Local)

Ticket 目录约定（项目本地）

For each task, create/use one ticket folder under
```
tickets/in-progress/
```
.
Folder naming: use a clear, short kebab-case name (no date prefix required).
Write all task planning artifacts into the
```
in-progress
```
ticket folder while work is active.

Standard states:

active work path:
```
tickets/in-progress/<ticket-name>/
```
completed archive path:
```
tickets/done/<ticket-name>/
```

Move rule (mandatory): move a ticket from
```
in-progress
```
to
```
done
```
only when the user explicitly confirms completion (for example: "done", "finished", or "verified") or explicitly asks to move it.
Final archive ordering rule (mandatory): when explicit user completion/verification also triggers repository finalization, move the ticket folder to
```
tickets/done/<ticket-name>/
```
before the final commit so the committed state includes the archived ticket path.
Reopen rule (mandatory): if the user asks to continue/reopen a completed ticket, move it from
```
tickets/done/<ticket-name>/
```
back to
```
tickets/in-progress/<ticket-name>/
```
before making new updates.
Never auto-move a ticket to
```
done
```
based only on internal assessment.
If the user specifies a different location, follow the user-specified path.

每个任务在
```
tickets/in-progress/
```
下创建或使用一个 ticket 目录。
目录命名：使用清晰、简短的 kebab-case 名称（无需日期前缀）。
工作进行期间，将所有任务规划产物写入
```
in-progress
```
ticket 目录。

标准状态：

活跃工作路径：
```
tickets/in-progress/<ticket-name>/
```
完成归档路径：
```
tickets/done/<ticket-name>/
```

移动规则（强制）：只有在用户明确确认完成（例如：「done」「finished」或「verified」），或明确要求移动时，才能将 ticket 从
```
in-progress
```
移至
```
done
```
。
最终归档顺序规则（强制）：当用户明确确认完成或验证，同时触发仓库最终化时，必须先将 ticket 目录移至
```
tickets/done/<ticket-name>/
```
，再执行最终提交，以确保提交后的状态包含归档后的 ticket 路径。
重新打开规则（强制）：如果用户要求继续或重新打开已完成的 ticket，必须先将其从
```
tickets/done/<ticket-name>/
```
移回
```
tickets/in-progress/<ticket-name>/
```
，然后再进行任何新更新。
不得仅根据内部评估自动将 ticket 移至
```
done
```
。
如果用户指定了其他位置，则遵循用户指定的路径。

Ticket + Worktree Bootstrap (Mandatory First Action)

Ticket 与 Worktree 初始化（强制首要操作）

Before investigation, bootstrap work context in this order:
- create/use
```
tickets/in-progress/<ticket-name>/
```
  ,
- if the project is a git repository, create/switch to a dedicated worktree/branch for the ticket before writing artifacts (
```
codex/<ticket-name>
```
  branch naming),
- create/update
```
requirements.md
```
  with status
```
Draft
```
  from user-provided requirement intent.
Investigation must not start before the ticket bootstrap and
```
requirements.md
```
```
Draft
```
are physically written.
If a dedicated worktree already exists for the ticket, reuse it instead of creating a new one.
If the environment is not a git repository, continue without worktree setup and still enforce ticket-folder +
```
Draft
```
requirement capture.

调查开始前，按以下顺序初始化工作上下文：
- 创建或使用
```
tickets/in-progress/<ticket-name>/
```
  ；
- 如果项目是 git 仓库，在写入产物前，为该 ticket 创建或切换到专用 worktree/分支（分支命名为
```
codex/<ticket-name>
```
  ）；
- 根据用户提供的需求意图创建或更新
```
requirements.md
```
  ，状态设为
```
Draft
```
  。
在 ticket 初始化完成且
```
requirements.md
```
的
```
Draft
```
状态实际写入之前，不得开始调查。
如果该 ticket 已存在专用 worktree，应直接复用，而不是创建新的 worktree。
如果当前环境不是 git 仓库，则无需设置 worktree，但仍然必须执行 ticket 目录与
```
Draft
```
需求捕获要求。

Workflow State File (Mandatory Enforcement Artifact)

工作流状态文件（强制执行产物）

Create and maintain
```
tickets/in-progress/<ticket-name>/workflow-state.md
```
as the canonical stage-control artifact.
Initialize it during Stage 0 immediately after ticket bootstrap with:
- ```
Current Stage = 0
```
  ,
- ```
Code Edit Permission = Locked
```
  ,
- stage gate rows in
```
Not Started
```
  /
```
In Progress
```
  state.
Update model (mandatory):
- rewrite
```
Current Snapshot
```
  in place on every stage transition,
- append one row to
```
Transition Log
```
  for every transition/re-entry,
- keep
```
Stage Gates
```
  rows current with evidence links/paths.
Source-code edit lock (hard rule):
- no source code edits are allowed unless
```
workflow-state.md
```
  explicitly shows
```
Code Edit Permission = Unlocked
```
  ,
- default state is
```
Locked
```
  ; unlock source-code edits only when Stage 6 prerequisites are satisfied.
Re-entry lock rule:
- on any Stage 7/8 failure, set
```
Code Edit Permission = Locked
```
  before re-entry actions,
- record trigger/classification/return path in
```
workflow-state.md
```
  before proceeding.
Violation protocol:
- if source code is edited while
```
Code Edit Permission = Locked
```
  , record a violation entry in
```
workflow-state.md
```
  ,
- pause further source edits, declare re-entry, and return to the required upstream stage path.

创建并维护
```
tickets/in-progress/<ticket-name>/workflow-state.md
```
，将其作为规范的阶段控制产物。
在 ticket 初始化后立即于 Stage 0 初始化该文件，包括：
- ```
Current Stage = 0
```
  ；
- ```
Code Edit Permission = Locked
```
  ；
- 状态为
```
Not Started
```
  或
```
In Progress
```
  的阶段门禁行。
更新模型（强制）：
- 每次阶段转换时原地重写
```
Current Snapshot
```
  ；
- 每次转换或重新进入时，向
```
Transition Log
```
  追加一行；
- 持续更新
```
Stage Gates
```
  各行，并附证据链接或路径。
源代码编辑锁（硬性规则）：
- 除非
```
workflow-state.md
```
  明确显示
```
Code Edit Permission = Unlocked
```
  ，否则不得编辑源代码；
- 默认状态为
```
Locked
```
  ；仅在满足 Stage 6 前置条件后解锁源代码编辑。
重新进入锁定规则：
- Stage 7/8 发生任何失败时，必须在执行重新进入操作前将
```
Code Edit Permission = Locked
```
  ；
- 继续执行前，在
```
workflow-state.md
```
  中记录触发原因、分类和返回路径。
违规处理协议：
- 如果在
```
Code Edit Permission = Locked
```
  时编辑了源代码，在
```
workflow-state.md
```
  中记录违规条目；
- 暂停后续源代码编辑，声明重新进入，并返回规定的上游阶段路径。

Audible Notifications (Speak Tool, Required)

语音通知（Speak 工具，强制）

Use the
```
Speak
```
tool for workflow-state transition updates so the user can follow where execution is and what is next.
Playback rule (mandatory): for required audible notifications, call
```
Speak
```
with
```
play=true
```
explicitly.
Do not set
```
play=false
```
by default for required transition notifications.
Exception: set
```
play=false
```
only when the user explicitly requests silent mode.
Transition-driven speak rule (mandatory):
- speak only when
```
workflow-state.md
```
  is updated for a stage transition, gate decision, re-entry decision, or code-edit lock/unlock change,
- do not speak for low-level command execution, intermediate analysis notes, or partial drafts.
Required audible events:
- workflow kickoff (
```
task accepted
```
  ,
```
next stage
```
  ),
- every stage transition (
```
From Stage -> To Stage
```
  ) after
```
workflow-state.md
```
  transition log is appended,
- every gate decision (
```
Pass
```
  /
```
Fail
```
  /
```
Blocked
```
  ) after gate evidence is written,
- every re-entry declaration (classification + return path) after
```
workflow-state.md
```
  re-entry section is updated,
- every
```
Code Edit Permission
```
  change (
```
Locked
```
  /
```
Unlocked
```
  ) after snapshot update.
Speak ordering rule:
- update
```
workflow-state.md
```
  first,
- then emit audible notification reflecting the persisted state.
Spoken message content (mandatory):
- current stage,
- what just completed/changed (transition or gate result),
- next stage/action,
- code-edit lock state when it changed.
If multiple transitions happen close together, batch them into one short message after the final persisted update.
Keep each spoken message short (1-2 sentences), status-first, and action-oriented.
If the
```
Speak
```
tool fails or is unavailable, continue the workflow and provide the same update in text.
Do not speak secrets, tokens, or full sensitive payloads.

使用
```
Speak
```
工具发布工作流状态转换通知，让用户了解当前执行阶段及后续操作。
播放规则（强制）：对于强制语音通知，必须显式使用
```
play=true
```
调用
```
Speak
```
。
不得默认将
```
play=false
```
用于强制的阶段转换通知。
例外：仅当用户明确要求静音时，才可设置
```
play=false
```
。
转换驱动通知规则（强制）：
- 仅在因阶段转换、门禁决策、重新进入决策或代码编辑锁定状态变更而更新
```
workflow-state.md
```
  时进行播报；
- 不为底层命令执行、中间分析说明或部分草稿进行播报。
强制语音事件：
- 工作流启动（
```
task accepted
```
  、
```
next stage
```
  ）；
- 每次阶段转换（
```
From Stage -> To Stage
```
  ），且必须在
```
workflow-state.md
```
  的转换日志追加记录之后播报；
- 每次门禁决策（
```
Pass
```
  /
```
Fail
```
  /
```
Blocked
```
  ），且必须在门禁证据写入之后播报；
- 每次重新进入声明（分类与返回路径），且必须在
```
workflow-state.md
```
  的重新进入部分更新之后播报；
- 每次
```
Code Edit Permission
```
  变更（
```
Locked
```
  /
```
Unlocked
```
  ），且必须在快照更新之后播报。
Speak 顺序规则：
- 先更新
```
workflow-state.md
```
  ；
- 然后发出与已持久化状态一致的语音通知。
语音消息内容（强制）：
- 当前阶段；
- 刚刚完成或变更的内容（转换或门禁结果）；
- 下一阶段或操作；
- 代码编辑锁定状态发生变化时，还需说明该状态。
如果多个转换紧密连续发生，可在最终持久化更新后合并为一条简短消息。
每条语音消息应保持简短（1 至 2 句），以状态为先，并突出下一步操作。
如果
```
Speak
```
工具执行失败或不可用，则继续工作流，并以文本形式提供相同更新。
不得播报密钥、令牌或完整的敏感载荷。

Execution Model (Strict Stage Gates)

执行模型（严格阶段门禁）

Work in explicit stages and complete each gate before producing downstream artifacts.
Before every stage transition, update
```
workflow-state.md
```
first (snapshot + transition log + gate statuses), then proceed.
Treat
```
workflow-state.md
```
as an execution lock controller, not optional documentation.
Transition authority rule (mandatory): stage movement is controlled by the Stage Transition Contract + Transition Matrix. When a trigger condition is met, transition immediately to the mapped path; do not continue in the current stage by preference.
Requirements can start as rough
```
Draft
```
from user input/bug report artifacts before deep analysis.
Do not start investigation until ticket/worktree bootstrap is complete and
```
requirements.md
```
status
```
Draft
```
is physically written.
Do not mark understanding pass complete until
```
investigation-notes.md
```
is physically written and current for the ticket.
Do not draft design artifacts (
```
proposed-design.md
```
or small-scope design basis in
```
implementation-plan.md
```
) until deep understanding pass is complete and
```
requirements.md
```
reaches
```
Design-ready
```
.
Do not finalize
```
implementation-plan.md
```
or generate
```
implementation-progress.md
```
until the future-state runtime call stack review gate is fully satisfied for the current scope.
Do not start implementation execution until
```
implementation-plan.md
```
is finalized and
```
implementation-progress.md
```
is initialized.
Do not start source-code edits until all of the following are true in
```
workflow-state.md
```
:
- ```
Current Stage = 6
```
  ,
- ```
Code Edit Permission = Unlocked
```
  ,
- Stage 5 gate is
```
Go Confirmed
```
  ,
- required upstream artifacts are marked
```
Pass
```
  with evidence.
Do not start API/E2E test implementation and execution until implementation execution is complete with required unit/integration verification and Stage 6 modernization/decoupling checks are satisfied.
Do not start code review until API/E2E test gate is
```
Pass
```
.
Do not start post-testing
```
docs/
```
synchronization until code review is complete (for infeasible acceptance criteria in Stage 7, explicit user waiver + constraints + compensating evidence + residual risk must be recorded).
Do not close the task until post-testing
```
docs/
```
synchronization is completed (or explicit no-impact decision is recorded with rationale), and do not mark final completion until any required Stage 10 user-verification/archive/finalization work is complete.
User-verification hold rule (mandatory): after Stage 9 passes, persist the handoff summary and keep Stage 10 open until the user explicitly confirms completion/verification (for example after manual testing). Do not commit, push, merge, release, or move the ticket to
```
done
```
before that user signal.
Release-notes artifact rule (mandatory when applicable): if the ticket leads to a user-facing app release or any GitHub Release body, Stage 10 must also persist
```
release-notes.md
```
with short functional user-facing notes before final release. If not applicable, record an explicit
```
release-notes not required
```
rationale in the handoff summary.
Git finalization rule (mandatory for git repositories): after the explicit user completion/verification signal is received and before Stage 10 is marked complete, first move the ticket folder to
```
tickets/done/<ticket-name>/
```
, then commit all in-scope changes on the ticket branch (including the moved ticket files), push the ticket branch to remote, update the latest personal branch from remote, merge the ticket branch into that personal branch, push the updated personal branch, and use the release script to release a new version.
Release publication handoff rule (mandatory when release notes are required): during repository finalization, pass the ticket
```
release-notes.md
```
artifact into the project release path (for example via the release script or the repo's release-body source file) before the release tag is created so the tagged revision contains the curated notes.
Personal-branch resolution rule (mandatory): determine the latest personal branch from repository context or explicit user instruction; if it cannot be derived with high confidence, pause Stage 10 and ask once before merge/release instead of guessing.
Stage 10 blockage rule (mandatory): if the move to
```
tickets/done/
```
, commit, push, personal-branch update, merge, or release fails after user confirmation, keep Stage 10
```
In Progress
```
/
```
Blocked
```
, record the blocker in
```
workflow-state.md
```
, and do not mark final handoff complete.
Keep the ticket folder under
```
tickets/in-progress/
```
until explicit user completion confirmation is received.
Treat engineering completion, user verification, and ticket archival as separate gates: engineering completion ends at implementation + API/E2E test gate + code review + docs sync; after that, wait for explicit user completion/verification; only then move the ticket to
```
tickets/done/
```
and run required Stage 10 git finalization/release work when the project is a git repository.
```
Small
```
scope exception: drafting
```
implementation-plan.md
```
(solution sketch only) before review is allowed as design input, but this draft does not unlock implementation kickoff.
Future-state runtime call stack review must run as iterative deep-review rounds (not one-pass review).
```
Go Confirmed
```
cannot be declared immediately after required upstream artifact updates from a blocking round.
Stability rule (mandatory): unlock
```
Go Confirmed
```
only after two consecutive deep-review rounds report no blockers, no required persisted artifact updates, and no newly discovered use cases.
First clean round is provisional (
```
Candidate Go
```
), second consecutive clean round is confirmation (
```
Go Confirmed
```
).
Missing-use-case discovery rule (mandatory): every Stage 5 round must run a dedicated missing-use-case discovery sweep (requirement coverage, boundary crossings, fallback/error branches, and design-risk scenarios).
A Stage 5 round is not clean if it discovers new use cases, requires persisted artifact updates, or finds blockers.
Any review finding with a required design/call-stack update is blocking; regenerate affected artifacts and re-review before proceeding.
If design/review reveals missing understanding or requirement ambiguity, return to understanding + requirements stages, update
```
requirements.md
```
, then continue design/review.
Stage 5 classified re-entry mapping (mandatory):
- ```
Design Impact
```
  (clear boundary/layer/naming/architecture issue with high confidence): return to
```
Stage 3 -> Stage 4 -> Stage 5
```
  .
- ```
Requirement Gap
```
  (missing/ambiguous requirement or acceptance criterion): return to
```
Stage 2 -> Stage 3 -> Stage 4 -> Stage 5
```
  .
- ```
Unclear
```
  (cross-cutting scope or low root-cause confidence): return to
```
Stage 1 -> Stage 2 -> Stage 3 -> Stage 4 -> Stage 5
```
  .
For any Stage 5 blocking round, record classification + return path in
```
future-state-runtime-call-stack-review.md
```
and
```
workflow-state.md
```
before starting the next round.
Stage 6 non-local re-entry rule (mandatory): if a Stage 6 issue is classified as
```
Design Impact
```
,
```
Requirement Gap
```
, or
```
Unclear
```
, record classification + return path in
```
workflow-state.md
```
, set
```
Code Edit Permission = Locked
```
, and transition to the mapped upstream stage path before further source edits.
Re-entry declaration rule (mandatory): when a post-implementation gate (
```
Stage 7
```
API/E2E testing or
```
Stage 8
```
code review) finds issues, explicitly record:
- trigger stage (
```
7
```
  /
```
8
```
  ),
- classification (
```
Local Fix
```
  /
```
Design Impact
```
  /
```
Requirement Gap
```
  /
```
Unclear
```
  ),
- required return stage path before any code edit.
Re-entry declaration must be recorded in
```
workflow-state.md
```
before any artifact/code update work begins.
No-direct-patch rule (mandatory): for post-implementation gate findings, do not edit source code first. Update required upstream artifacts first based on classification path.

Re-entry mapping (mandatory):

```
Local Fix
```
: update implementation artifacts (
```
implementation-plan.md
```
/
```
implementation-progress.md
```
/
```
api-e2e-testing.md
```
/
```
code-review.md
```
as applicable), then implement fix, then rerun
```
Stage 6 -> Stage 7
```
; once Stage 7 passes, continue to
```
Stage 8
```
.

Design Impact

: return to

Stage 1 -> Stage 3 -> Stage 4 -> Stage 5 -> Stage 6 -> Stage 7

; once Stage 7 passes, continue to

Stage 8

Requirement Gap

: return to

Stage 2 -> Stage 3 -> Stage 4 -> Stage 5 -> Stage 6 -> Stage 7

; once Stage 7 passes, continue to

Stage 8

Unclear

(or cross-cutting root cause): return to

Stage 0 -> Stage 1 -> Stage 2 -> Stage 3 -> Stage 4 -> Stage 5 -> Stage 6 -> Stage 7

; once Stage 7 passes, continue to

Stage 8

Stage 0 in a re-entry path means re-open bootstrap controls in the same ticket/worktree (
```
workflow-state.md
```
, lock state, artifact baselines); do not create a new ticket folder.
If the user asks for all artifacts in one turn, still enforce stage gates within that turn (iterate review rounds first; only then produce implementation artifacts).
Stage-first persistence rule: if a Stage 5 round finds issues, first record classification + return path and transition to the required upstream stage in
```
workflow-state.md
```
, then persist required artifact updates in that stage.
No mental-only review refinements: do not carry unresolved updates in memory across rounds.
For each review round, record explicit persisted artifact updates in
```
future-state-runtime-call-stack-review.md
```
:
- updated files,
- new artifact versions,
- changed sections,
- which findings were resolved.
A review round cannot be considered complete until its required file updates are physically written.
If announcing review-round status, do it only after the round record + required staged artifact updates are physically written and the related Stage 5 gate status is persisted in
```
workflow-state.md
```
.

按明确阶段执行工作，并在生成下游产物前完成相应门禁。
每次阶段转换前，先更新
```
workflow-state.md
```
（快照、转换日志和门禁状态），然后再继续执行。
将
```
workflow-state.md
```
视为执行锁控制器，而不是可选文档。
转换权限规则（强制）：阶段移动由 Stage Transition Contract 与 Transition Matrix 控制。触发条件满足时，必须立即转换到映射路径；不得凭偏好继续停留在当前阶段。
在深入分析前，需求可以根据用户输入或缺陷报告产物以粗略的
```
Draft
```
状态开始。
在 ticket/worktree 初始化完成且
```
requirements.md
```
的
```
Draft
```
状态实际写入之前，不得开始调查。
在
```
investigation-notes.md
```
已实际写入且保持最新之前，不得将理解环节标记为通过。
在深入理解环节完成且
```
requirements.md
```
达到
```
Design-ready
```
之前，不得起草设计产物（
```
proposed-design.md
```
，或
```
implementation-plan.md
```
中小范围任务的设计依据）。
在当前范围的未来态运行时调用栈评审门禁完全满足之前，不得最终确定
```
implementation-plan.md
```
或生成
```
implementation-progress.md
```
。
在
```
implementation-plan.md
```
已最终确定且
```
implementation-progress.md
```
已初始化之前，不得开始执行实现。
只有
```
workflow-state.md
```
中以下条件全部为真时，才能开始源代码编辑：
- ```
Current Stage = 6
```
  ；
- ```
Code Edit Permission = Unlocked
```
  ；
- Stage 5 门禁为
```
Go Confirmed
```
  ；
- 所需上游产物均标记为
```
Pass
```
  并附有证据。
在实现执行完成、必要的单元测试与集成测试验证通过，且 Stage 6 的现代化与解耦检查均满足之前，不得开始 API/E2E 测试的实现与执行。
在 API/E2E 测试门禁为
```
Pass
```
之前，不得开始代码评审。
在代码评审完成之前，不得开始测试后的
```
docs/
```
同步（对于 Stage 7 中不可行的验收标准，必须记录用户明确豁免、约束、补偿性证据和剩余风险）。
在测试后的
```
docs/
```
同步完成，或已记录明确的无影响决策及理由之前，不得关闭任务；在任何必要的 Stage 10 用户验证、归档和最终化工作完成之前，不得标记最终完成。
用户验证暂停规则（强制）：Stage 9 通过后，持久化交接摘要，并保持 Stage 10 开启，直到用户明确确认完成或验证（例如在手动测试后）。在收到该用户信号之前，不得提交、推送、合并、发布或将 ticket 移至
```
done
```
。
Release notes 产物规则（适用时强制）：如果 ticket 会产生面向用户的应用版本或任何 GitHub Release 正文，Stage 10 还必须在最终发布前持久化
```
release-notes.md
```
，其中包含简短的功能性用户说明。如果不适用，则必须在交接摘要中记录明确的「release notes not required」理由。
Git 最终化规则（git 仓库强制）：收到用户明确的完成或验证信号后、标记 Stage 10 完成前，依次执行：先将 ticket 目录移至
```
tickets/done/<ticket-name>/
```
；然后在 ticket 分支上提交所有范围内变更（包括移动后的 ticket 文件）；推送 ticket 分支；从远程更新最新的个人分支；将 ticket 分支合并至该个人分支；推送更新后的个人分支；最后使用发布脚本发布新版本。
Release 发布交接规则（需要 release notes 时强制）：在仓库最终化期间，必须在创建发布 tag 之前，将 ticket 的
```
release-notes.md
```
产物传入项目发布路径（例如通过发布脚本或仓库的 release-body 源文件），确保 tag 对应的修订版本包含整理后的说明。
个人分支解析规则（强制）：根据仓库上下文或用户明确指示确定最新的个人分支；如果无法高置信度地确定，则暂停 Stage 10，并在合并或发布前询问一次，而不是进行猜测。
Stage 10 阻塞规则（强制）：用户确认后，如果移动至
```
tickets/done/
```
、提交、推送、个人分支更新、合并或发布中的任一步骤失败，则保持 Stage 10 为
```
In Progress
```
/
```
Blocked
```
，在
```
workflow-state.md
```
中记录阻塞项，并且不得标记最终交接完成。
默认情况下，将 ticket 目录保留在
```
tickets/in-progress/
```
，直到收到用户明确的完成确认。
将工程完成、用户验证和 ticket 归档视为彼此独立的门禁：工程完成结束于实现、API/E2E 测试门禁、代码评审和文档同步；之后等待用户明确完成或验证；只有在此之后，才能将 ticket 移至
```
done/
```
，并在项目为 git 仓库时执行必要的 Stage 10 Git 最终化与发布工作。
```
Small
```
范围例外：允许在评审前起草
```
implementation-plan.md
```
（仅包含方案概要）作为设计输入，但该草稿不得解锁实现启动。
目标态运行时调用栈评审必须以迭代式深度评审轮次执行，不得采用单轮评审。
在完成某轮阻塞性评审所要求的上游产物更新后，不得立即声明
```
Go Confirmed
```
。
稳定性规则（强制）：仅当连续两轮深度评审均未发现阻塞项、无需持久化更新产物且未发现新用例时，才能解锁
```
Go Confirmed
```
。
第一轮无问题结果为暂定状态（
```
Candidate Go
```
），第二轮连续无问题结果才为确认状态（
```
Go Confirmed
```
）。
缺失用例发现规则（强制）：每个 Stage 5 轮次都必须执行专门的缺失用例扫描，涵盖需求覆盖、边界穿越、fallback/错误分支以及设计风险场景。
如果某轮 Stage 5 评审发现新用例、需要持久化更新产物或发现阻塞项，则该轮不能视为无问题轮次。
任何要求更新设计或调用栈的评审发现都属于阻塞项；必须重新生成受影响的产物并再次评审，然后才能继续。
如果设计或评审暴露出理解不足或需求歧义，则返回理解与需求阶段，更新
```
requirements.md
```
，然后继续设计与评审。
Stage 5 分类后的重新进入映射（强制）：
- ```
Design Impact
```
  （明确存在高置信度的边界、层级、命名或架构问题）：返回
```
Stage 3 -> Stage 4 -> Stage 5
```
  。
- ```
Requirement Gap
```
  （缺少或存在歧义的需求或验收标准）：返回
```
Stage 2 -> Stage 3 -> Stage 4 -> Stage 5
```
  。
- ```
Unclear
```
  （跨范围问题或根因置信度低）：返回
```
Stage 1 -> Stage 2 -> Stage 3 -> Stage 4 -> Stage 5
```
  。
对任何阻塞性的 Stage 5 轮次，必须在开始下一轮前，将分类与返回路径记录到
```
future-state-runtime-call-stack-review.md
```
和
```
workflow-state.md
```
。
Stage 6 非局部重新进入规则（强制）：如果 Stage 6 问题被分类为
```
Design Impact
```
、
```
Requirement Gap
```
或
```
Unclear
```
，必须先在
```
workflow-state.md
```
中记录分类与返回路径，将
```
Code Edit Permission = Locked
```
，然后在进一步编辑源代码前转换至映射的上游阶段路径。
重新进入声明规则（强制）：当实现后门禁（Stage 7 API/E2E 测试或 Stage 8 代码评审）发现问题时，必须明确记录：
- 触发阶段（
```
7
```
  /
```
8
```
  ）；
- 分类（
```
Local Fix
```
  /
```
Design Impact
```
  /
```
Requirement Gap
```
  /
```
Unclear
```
  ）；
- 在任何代码编辑前必须遵循的返回阶段路径。
在开始任何产物或代码更新工作之前，必须先在
```
workflow-state.md
```
中记录重新进入声明。
禁止直接修补规则（强制）：对于实现后门禁发现的问题，不得先编辑源代码。必须先根据分类路径更新所需的上游产物。

重新进入映射（强制）：

```
Local Fix
```
：按需更新实现产物（
```
implementation-plan.md
```
/
```
implementation-progress.md
```
/
```
api-e2e-testing.md
```
/
```
code-review.md
```
），然后实施修复，再重新运行
```
Stage 6 -> Stage 7
```
；Stage 7 通过后继续进入 Stage 8。

Design Impact

：返回

Stage 1 -> Stage 3 -> Stage 4 -> Stage 5 -> Stage 6 -> Stage 7

；Stage 7 通过后继续进入 Stage 8。

Requirement Gap

：返回

Stage 2 -> Stage 3 -> Stage 4 -> Stage 5 -> Stage 6 -> Stage 7

；Stage 7 通过后继续进入 Stage 8。

Unclear

（或跨范围根因）：返回

Stage 0 -> Stage 1 -> Stage 2 -> Stage 3 -> Stage 4 -> Stage 5 -> Stage 6 -> Stage 7

；Stage 7 通过后继续进入 Stage 8。

重新进入路径中的 Stage 0 表示在同一 ticket/worktree 中重新打开初始化控制项（
```
workflow-state.md
```
、锁定状态和产物基线）；不得创建新的 ticket 目录。
即使用户要求在一个回合中生成所有产物，仍必须在该回合内执行阶段门禁（先迭代完成评审轮次；仅在此之后生成实现产物）。
阶段优先持久化规则：如果某轮 Stage 5 评审发现问题，必须先在
```
workflow-state.md
```
中记录分类与返回路径并转换至所需的上游阶段，然后在对应阶段持久化必要的产物更新。
禁止仅在内存中进行评审细化：不得跨轮次在内存中保留尚未解决的更新。
对于每个评审轮次，必须在
```
future-state-runtime-call-stack-review.md
```
中记录明确的持久化产物更新：
- 已更新文件；
- 新的产物版本；
- 变更章节；
- 已解决的发现。
只有当该轮要求的文件更新已实际写入后，评审轮次才算完成。
如果要宣布评审轮次状态，只能在该轮记录、必要的分阶段产物更新实际写入，并且相关 Stage 5 门禁状态已持久化到
```
workflow-state.md
```
之后进行。

Canonical Stage Sequence (Quick Map)

标准阶段顺序（快速映射）

Stage	Name	Core Deliverable/Gate	Code Edit Permission
0	Bootstrap + Draft Requirement	Ticket/worktree bootstrap complete + `requirements.md` = `Draft`	Locked
1	Investigation + Triage	`investigation-notes.md` current + scope triage complete	Locked
2	Requirements Refinement	`requirements.md` reaches `Design-ready` / `Refined`	Locked
3	Design Basis	`implementation-plan.md` sketch ( `Small` ) or `proposed-design.md` ( `Medium/Large` )	Locked
4	Runtime Modeling	`future-state-runtime-call-stack.md` current	Locked
5	Runtime Review Gate	`Go Confirmed` (two consecutive clean rounds with no blockers/persisted updates/new use cases)	Locked
6	Source Implementation + Unit/Integration	Source code + required unit/integration checks complete + no backward-compat/legacy retention + decoupling preserved + touched files correctly placed	Unlocked
7	API/E2E Test Implementation + Gate	API/E2E scenarios implemented and acceptance criteria closure complete	Unlocked
8	Code Review Gate	Code review decision recorded ( `Pass` / `Fail` ) with `<=500` effective-line hard-limit + required `>220` delta-gate assessments + shared-principles/layering + decoupling + module/file placement + no-backward-compat/no-legacy checks	Locked
9	Docs Sync	`docs/` updates complete or no-impact rationale recorded	Locked
10	Final Handoff	Delivery summary ready + explicit user verification -> move ticket to `done` -> git finalization/release (when git repo) + ticket state decision recorded	Locked

阶段	名称	核心产物/门禁	代码编辑权限
0	初始化 + 需求草稿	Ticket/worktree 初始化完成，且 `requirements.md` = `Draft`	Locked
1	调查 + 分流	`investigation-notes.md` 保持最新，且完成范围分流	Locked
2	需求细化	`requirements.md` 达到 `Design-ready` / `Refined`	Locked
3	设计依据	`implementation-plan.md` 概要（ `Small` ）或 `proposed-design.md` （ `Medium/Large` ）	Locked
4	运行时建模	`future-state-runtime-call-stack.md` 保持最新	Locked
5	运行时评审门禁	`Go Confirmed` （连续两轮无问题，且无阻塞项、无持久化更新、无新用例）	Locked
6	源代码实现 + 单元/集成测试	源代码完成，必要的单元/集成测试通过，无向后兼容或遗留保留，解耦得到保持，变更文件位置正确	Unlocked
7	API/E2E 测试实现 + 门禁	API/E2E 场景已实现，验收标准完成闭环	Unlocked
8	代码评审门禁	记录代码评审决策（ `Pass` / `Fail` ），并满足 `<=500` 有效行硬限制、必需的 `>220` 增量门禁评估、共享原则/分层、解耦、模块/文件位置以及无向后兼容/无遗留检查	Locked
9	文档同步	`docs/` 更新完成，或已记录无影响理由	Locked
10	最终交接	交付摘要已准备完成 + 用户明确验证 -> 移动 ticket 至 `done` -> Git 最终化/发布（git 仓库）+ 记录 ticket 状态决策	Locked

Stage Transition Contract (Enforcement)

阶段转换契约（执行要求）

Stage	Exit Condition (Must Be True To Transition)	On Fail/Blocked	Next Stage On Pass
0 Bootstrap + Draft Requirement	Ticket/worktree bootstrap complete and `requirements.md` status is `Draft`	Stay in `0` until bootstrap is complete	`1`
1 Investigation + Triage	`investigation-notes.md` is current and scope triage ( `Small` / `Medium` / `Large` ) is recorded	Stay in `1` until investigation evidence is complete	`2`
2 Requirements	`requirements.md` is `Design-ready` (or `Refined` ) with requirement/acceptance-criteria coverage maps	Stay in `2` until requirements are design-ready	`3`
3 Design Basis	Design basis artifact is current ( `implementation-plan.md` sketch for `Small` , `proposed-design.md` for `Medium/Large` )	Stay in `3` and revise design basis	`4`
4 Runtime Modeling	`future-state-runtime-call-stack.md` is current for in-scope use cases	Stay in `4` and regenerate runtime model	`5`
5 Review Gate	Runtime review reaches `Go Confirmed` (two consecutive clean rounds with no blockers, no required persisted artifact updates, and no newly discovered use cases)	Classified re-entry before next review round ( `Design Impact` : `3 -> 4 -> 5` , `Requirement Gap` : `2 -> 3 -> 4 -> 5` , `Unclear` : `1 -> 2 -> 3 -> 4 -> 5` )	`6`
6 Source + Unit/Integration	Source implementation complete, required unit/integration checks pass, no backward-compatibility/legacy-retention paths remain in scope, decoupling boundaries stay intact (no new unjustified cycles/tight coupling), and touched files have correct module/file placement	Local issues: stay in `6` ; classified re-entry for non-local issues ( `Design Impact` : `1 -> 3 -> 4 -> 5 -> 6` , `Requirement Gap` : `2 -> 3 -> 4 -> 5 -> 6` , `Unclear` : `0 -> 1 -> 2 -> 3 -> 4 -> 5 -> 6` )	`7`
7 API/E2E Gate	API/E2E scenarios implemented and all executable mapped acceptance criteria are `Passed` (or explicitly `Waived` by user for infeasible cases)	`Blocked` on infeasible/no waiver; otherwise re-enter by classification ( `Local Fix` : `6 -> 7` , `Design Impact` : `1 -> 3 -> 4 -> 5 -> 6 -> 7` , `Requirement Gap` : `2 -> 3 -> 4 -> 5 -> 6 -> 7` , `Unclear` : `0 -> 1 -> 2 -> 3 -> 4 -> 5 -> 6 -> 7` )	`8`
8 Code Review Gate	Code review decision is `Pass` with all mandatory review checks satisfied (including `<=500` effective-line hard-limit + required `>220` delta-gate assessments + shared-principles/layering + decoupling + module/file placement + no-backward-compat/no-legacy)	Re-enter by classification ( `Local Fix` : `6 -> 7 -> 8` , `Design Impact` : `1 -> 3 -> 4 -> 5 -> 6 -> 7 -> 8` , `Requirement Gap` : `2 -> 3 -> 4 -> 5 -> 6 -> 7 -> 8` , `Unclear` : `0 -> 1 -> 2 -> 3 -> 4 -> 5 -> 6 -> 7 -> 8` )	`9`
9 Docs Sync	Docs updates are completed, or explicit no-impact rationale is recorded	Stay in `9` until docs gate is satisfied	`10`
10 Final Handoff	Handoff summary is complete, explicit user completion/verification instruction is received, the ticket has been moved to `tickets/done/<ticket-name>/` , and, when in a git repository, ticket-branch commit/push + latest-personal-branch update + merge + push + release are complete	Stay in `Stage 10` until the user verifies completion and Stage 10 archival/finalization is complete	End

阶段	退出条件（必须为真才能转换）	失败/阻塞时	通过后的下一阶段
0 初始化 + 需求草稿	Ticket/worktree 初始化完成，且 `requirements.md` 状态为 `Draft`	初始化完成前保持在 `0`	`1`
1 调查 + 分流	`investigation-notes.md` 保持最新，且已记录范围分流（ `Small` / `Medium` / `Large` ）	调查证据完整前保持在 `1`	`2`
2 需求	`requirements.md` 达到 `Design-ready` （或 `Refined` ），并包含需求/验收标准覆盖映射	需求达到设计就绪前保持在 `2`	`3`
3 设计依据	设计依据产物保持最新（ `Small` 使用 `implementation-plan.md` 概要， `Medium/Large` 使用 `proposed-design.md` ）	保持在 `3` 并修订设计依据	`4`
4 运行时建模	`future-state-runtime-call-stack.md` 对范围内用例保持最新	保持在 `4` 并重新生成运行时模型	`5`
5 评审门禁	运行时评审达到 `Go Confirmed` （连续两轮无阻塞项、无需持久化更新产物且未发现新用例）	下一轮评审前执行分类后的重新进入（ `Design Impact` ： `3 -> 4 -> 5` ， `Requirement Gap` ： `2 -> 3 -> 4 -> 5` ， `Unclear` ： `1 -> 2 -> 3 -> 4 -> 5` ）	`6`
6 源代码 + 单元/集成测试	源代码实现完成，必要的单元/集成测试通过，范围内不存在向后兼容或遗留保留路径，解耦边界保持有效（未引入无合理依据的新循环或紧密耦合），且变更文件位于正确的模块/文件位置	局部问题：保持在 `6` ；非局部问题执行分类后的重新进入（ `Design Impact` ： `1 -> 3 -> 4 -> 5 -> 6` ， `Requirement Gap` ： `2 -> 3 -> 4 -> 5 -> 6` ， `Unclear` ： `0 -> 1 -> 2 -> 3 -> 4 -> 5 -> 6` ）	`7`
7 API/E2E 门禁	API/E2E 场景已实现，所有可执行的已映射验收标准均为 `Passed` （或不可执行场景已由用户明确标记为 `Waived` ）	不可执行且未豁免时为 `Blocked` ；否则按分类重新进入（ `Local Fix` ： `6 -> 7` ， `Design Impact` ： `1 -> 3 -> 4 -> 5 -> 6 -> 7` ， `Requirement Gap` ： `2 -> 3 -> 4 -> 5 -> 6 -> 7` ， `Unclear` ： `0 -> 1 -> 2 -> 3 -> 4 -> 5 -> 6 -> 7` ）	`8`
8 代码评审门禁	代码评审决策为 `Pass` ，且所有强制评审检查均通过（包括 `<=500` 有效行硬限制、必需的 `>220` 增量门禁评估、共享原则/分层、解耦、模块/文件位置以及无向后兼容/无遗留检查）	按分类重新进入（ `Local Fix` ： `6 -> 7 -> 8` ， `Design Impact` ： `1 -> 3 -> 4 -> 5 -> 6 -> 7 -> 8` ， `Requirement Gap` ： `2 -> 3 -> 4 -> 5 -> 6 -> 7 -> 8` ， `Unclear` ： `0 -> 1 -> 2 -> 3 -> 4 -> 5 -> 6 -> 7 -> 8` ）	`9`
9 文档同步	文档更新完成，或已记录明确的无影响理由	文档门禁满足前保持在 `9`	`10`
10 最终交接	交接摘要已完成，已收到用户明确的完成或验证指示，ticket 已移至 `tickets/done/<ticket-name>/` ；如果处于 git 仓库，还必须完成 ticket 分支提交/推送、最新个人分支更新、合并、推送和发布	用户验证且 Stage 10 归档/最终化完成前保持在 `Stage 10`	结束

Transition Matrix (Pass/Fail/Blocked)

转换矩阵（通过/失败/阻塞）

Trigger	Required Transition Path	Notes
Normal forward pass	`0 -> 1 -> 2 -> 3 -> 4 -> 5 -> 6 -> 7 -> 8 -> 9 -> 10`	Use only when each stage gate is `Pass` .
Stage 5 blocker classified `Design Impact`	`3 -> 4 -> 5`	Use when issue is clearly in architecture/layering/boundary/naming decisions.
Stage 5 blocker classified `Requirement Gap`	`2 -> 3 -> 4 -> 5`	Use when missing/ambiguous requirement or acceptance criteria is discovered.
Stage 5 blocker classified `Unclear`	`1 -> 2 -> 3 -> 4 -> 5`	Use when root cause is uncertain or cross-cutting and investigation must be refreshed first.
Stage 6 failure classified `Local Fix`	stay in `Stage 6`	Fix implementation/tests within Stage 6; do not advance to Stage 7.
Stage 6 failure classified `Design Impact`	`1 -> 3 -> 4 -> 5 -> 6`	Re-open investigation checkpoint, then re-enter design/runtime chain before continuing implementation.
Stage 6 failure classified `Requirement Gap`	`2 -> 3 -> 4 -> 5 -> 6`	Update requirements first, then rerun downstream chain before continuing implementation.
Stage 6 failure ( `Unclear` /cross-cutting root cause)	`0 -> 1 -> 2 -> 3 -> 4 -> 5 -> 6`	Re-open Stage 0 controls in the same ticket context, then rerun full chain before continuing implementation.
Stage 7 failure classified `Local Fix`	`6 -> 7`	Update artifacts first, then code fix, then rerun Stage 7 scenarios.
Stage 7 failure classified `Design Impact`	`1 -> 3 -> 4 -> 5 -> 6 -> 7`	Re-open investigation, then re-enter design/runtime chain before retrying Stage 7.
Stage 7 failure classified `Requirement Gap`	`2 -> 3 -> 4 -> 5 -> 6 -> 7`	Update requirements first, then rerun downstream chain.
Stage 7 failure ( `Unclear` /cross-cutting root cause)	`0 -> 1 -> 2 -> 3 -> 4 -> 5 -> 6 -> 7`	Re-open Stage 0 controls in the same ticket context, then rerun full chain.
Stage 7 infeasible scenario without user waiver	stay in `Stage 7 (Blocked)`	Record constraints + compensating evidence; wait for explicit user waiver or environment fix.
Stage 8 fail classified `Local Fix`	`6 -> 7 -> 8`	Apply fix and rerun test gate before re-review.
Stage 8 fail classified `Design Impact`	`1 -> 3 -> 4 -> 5 -> 6 -> 7 -> 8`	Re-open investigation, then return to design chain before re-review.
Stage 8 fail classified `Requirement Gap`	`2 -> 3 -> 4 -> 5 -> 6 -> 7 -> 8`	Return to requirements then rerun full downstream chain.
Stage 8 failure ( `Unclear` /cross-cutting root cause)	`0 -> 1 -> 2 -> 3 -> 4 -> 5 -> 6 -> 7 -> 8`	Re-open Stage 0 controls in the same ticket context, then rerun full chain before re-review.
Stage 10 awaiting explicit user verification	stay in `Stage 10 (In Progress)`	Wait for explicit user completion/verification before moving the ticket to `done` and starting repository finalization.
Stage 10 archival/repository finalization blocked	stay in `Stage 10 (Blocked)`	Record the move/commit/git/release blocker, resolve it, then finish handoff.

触发条件	必需转换路径	说明
正常向前通过	`0 -> 1 -> 2 -> 3 -> 4 -> 5 -> 6 -> 7 -> 8 -> 9 -> 10`	仅当每个阶段门禁均为 `Pass` 时使用。
Stage 5 阻塞项分类为 `Design Impact`	`3 -> 4 -> 5`	当问题明确涉及架构、层级、边界或命名决策时使用。
Stage 5 阻塞项分类为 `Requirement Gap`	`2 -> 3 -> 4 -> 5`	当发现缺少或存在歧义的需求或验收标准时使用。
Stage 5 阻塞项分类为 `Unclear`	`1 -> 2 -> 3 -> 4 -> 5`	当根因不确定或跨范围，且必须刷新调查时使用。
Stage 6 失败分类为 `Local Fix`	保持在 `Stage 6`	在 Stage 6 内修复实现和测试；不得进入 Stage 7。
Stage 6 失败分类为 `Design Impact`	`1 -> 3 -> 4 -> 5 -> 6`	重新打开调查检查点，然后重新进入设计/运行时链，再继续实现。
Stage 6 失败分类为 `Requirement Gap`	`2 -> 3 -> 4 -> 5 -> 6`	先更新需求，再重新运行下游链，然后继续实现。
Stage 6 失败（ `Unclear` /跨范围根因）	`0 -> 1 -> 2 -> 3 -> 4 -> 5 -> 6`	在同一 ticket 上下文中重新打开 Stage 0 控制项，然后重新运行完整链，再继续实现。
Stage 7 失败分类为 `Local Fix`	`6 -> 7`	先更新产物，然后修复代码，再重新运行 Stage 7 场景。
Stage 7 失败分类为 `Design Impact`	`1 -> 3 -> 4 -> 5 -> 6 -> 7`	重新打开调查，然后重新进入设计链，再重试 Stage 7。
Stage 7 失败分类为 `Requirement Gap`	`2 -> 3 -> 4 -> 5 -> 6 -> 7`	先更新需求，再重新运行下游链。
Stage 7 失败（ `Unclear` /跨范围根因）	`0 -> 1 -> 2 -> 3 -> 4 -> 5 -> 6 -> 7`	重新打开 Stage 0 控制项，然后重新运行完整链。
Stage 7 场景不可执行且无用户豁免	保持在 `Stage 7 (Blocked)`	记录约束与补偿性证据；等待用户明确豁免或环境修复。
Stage 8 失败分类为 `Local Fix`	`6 -> 7 -> 8`	应用修复，并在重新评审前重新运行测试门禁。
Stage 8 失败分类为 `Design Impact`	`1 -> 3 -> 4 -> 5 -> 6 -> 7 -> 8`	重新打开调查，然后返回设计链，再重新评审。
Stage 8 失败分类为 `Requirement Gap`	`2 -> 3 -> 4 -> 5 -> 6 -> 7 -> 8`	返回需求阶段，再重新运行完整下游链。
Stage 8 失败（ `Unclear` /跨范围根因）	`0 -> 1 -> 2 -> 3 -> 4 -> 5 -> 6 -> 7 -> 8`	重新打开 Stage 0 控制项，然后重新运行完整链，再重新评审。
Stage 10 等待用户明确验证	保持在 `Stage 10 (In Progress)`	在将 ticket 移至 `done` 并启动仓库最终化前，等待用户明确完成或验证。
Stage 10 归档/仓库最终化被阻塞	保持在 `Stage 10 (Blocked)`	记录移动、提交、Git 或发布阻塞项，解决后完成交接。

0) Bootstrap Ticket + Capture Draft Requirement

0）初始化 Ticket 并捕获需求草稿

Run mandatory first-action sequence:
- create/use
```
tickets/in-progress/<ticket-name>/
```
  ,
- if git repo, create/switch ticket worktree/branch,
- create/update
```
tickets/in-progress/<ticket-name>/workflow-state.md
```
  from
```
assets/workflow-state-template.md
```
  and set
```
Current Stage = 0
```
  ,
```
Code Edit Permission = Locked
```
  ,
- capture initial requirement snapshot (
```
requirements.md
```
  status
```
Draft
```
  ) from user input/bug report evidence first (text, images, logs, repro notes, constraints).
Do not run deep investigation before Stage 0 bootstrap and
```
requirements.md
```
```
Draft
```
are physically written.
Before transitioning to Stage 1, update
```
workflow-state.md
```
snapshot + transition log + stage gate evidence.

执行强制首要操作序列：
- 创建或使用
```
tickets/in-progress/<ticket-name>/
```
  ；
- 如果是 git 仓库，创建或切换 ticket worktree/分支；
- 根据
```
assets/workflow-state-template.md
```
  创建或更新
```
tickets/in-progress/<ticket-name>/workflow-state.md
```
  ，并设置
```
Current Stage = 0
```
  、
```
Code Edit Permission = Locked
```
  ；
- 首先根据用户输入或缺陷报告证据捕获初始需求快照（文本、图片、日志、复现说明、约束），写入状态为
```
Draft
```
  的
```
requirements.md
```
  。
在 Stage 0 初始化完成且
```
requirements.md
```
的
```
Draft
```
状态实际写入之前，不得进行深入调查。
转换至 Stage 1 前，更新
```
workflow-state.md
```
快照、转换日志和阶段门禁证据。

1) Investigation + Understanding Pass + Triage

1）调查 + 理解环节 + 分流

Create/update
```
tickets/in-progress/<ticket-name>/investigation-notes.md
```
continuously during investigation. Do not keep investigation results only in memory.
Minimum codebase understanding pass before design:
- identify entrypoints and execution boundaries for in-scope flows,
- identify touched modules/files and owning concerns,
- identify expected canonical file locations/folder owners for touched concerns (for example: platform-specific vs shared),
- identify current naming conventions (file/module/API style),
- identify unknowns that could invalidate design assumptions.
In
```
investigation-notes.md
```
, record at minimum:
- sources consulted (
```
local file paths
```
  ,
```
web links
```
  ,
```
open-source references
```
  ,
```
papers
```
  when used),
- key findings and constraints,
- module/file placement observations (which files are already under the right owning folder, which are misplaced, and what the canonical location should be),
- open unknowns/questions,
- implications for requirements/design.
Re-entry rule: when later implementation/testing uncovers large or unclear issues, reopen this understanding stage and append new evidence, unknowns, and implications before changing requirements/design artifacts.
Do not draft design artifacts or runtime call stacks until this understanding pass is complete and
```
requirements.md
```
reaches
```
Design-ready
```
.
Classify as
```
Small
```
,
```
Medium
```
, or
```
Large
```
using practical signals:
- Estimated files touched (roughly <= 3 is usually
```
Small
```
  if not cross-cutting).
- New/changed public APIs, schema/storage changes, or cross-cutting behavior.
- Multi-layer impact (API + service + persistence + runtime flow) or architectural impact.
Choose workflow depth:
- ```
Small
```
  : create a draft implementation plan (with a short solution sketch), build per-use-case future-state runtime call stacks from that plan, review them, then refine until stability gate
```
Go Confirmed
```
  and track progress in real time.
- ```
Medium
```
  : create proposed design doc first, build future-state runtime call stacks from the proposed design doc, run iterative deep-review rounds until stability gate
```
Go Confirmed
```
  , and only then create implementation plan and track progress in real time.
- ```
Large
```
  : create proposed design doc first, build future-state runtime call stacks from the proposed design doc, run iterative deep-review rounds until stability gate
```
Go Confirmed
```
  , and only then create implementation plan and track progress in real time.
Re-evaluate during implementation; if scope expands or smells appear, escalate from
```
Small
```
to full workflow.
Before transitioning to Stage 2, update
```
workflow-state.md
```
snapshot + transition log + stage gate evidence.
After triage depth is finalized (
```
Small
```
/
```
Medium
```
/
```
Large
```
) and
```
investigation-notes.md
```
is current, announce only with the persisted
```
workflow-state.md
```
transition/gate update.

调查期间持续创建或更新
```
tickets/in-progress/<ticket-name>/investigation-notes.md
```
。不得仅在内存中保存调查结果。
设计前必须完成以下最低限度代码库理解环节：
- 确定范围内流程的入口点和执行边界；
- 确定受影响的模块/文件及其所属关注点；
- 确定受变更关注点的预期规范文件位置或目录所有者（例如：平台特定内容与共享内容）；
- 确定当前命名约定（文件、模块、API 风格）；
- 确定可能使设计假设失效的未知因素。
在
```
investigation-notes.md
```
中至少记录：
- 已查阅的信息来源（
```
local file paths
```
  、
```
web links
```
  、
```
open-source references
```
  、使用时的
```
papers
```
  ）；
- 关键发现与约束；
- 模块/文件位置观察（哪些文件已位于正确的所属目录，哪些文件位置不当，以及规范位置应是什么）；
- 未解决的未知项或问题；
- 对需求和设计的影响。
重新进入规则：后续实现或测试暴露出重大或不明确的问题时，重新打开此理解环节，并在更改需求或设计产物前追加新证据、未知项和影响。
在理解环节完成且
```
requirements.md
```
达到
```
Design-ready
```
之前，不得起草设计产物或运行时调用栈。
使用实际信号将范围分类为
```
Small
```
、
```
Medium
```
或
```
Large
```
：
- 预计受影响文件数量（如果不属于跨范围变更，通常约
```
<= 3
```
  个文件即为
```
Small
```
  ）；
- 新增或变更的公共 API、schema/存储结构或跨范围行为；
- 多层影响（API + service + persistence + runtime flow）或架构影响。
选择工作流深度：
- ```
Small
```
  ：先创建实施计划草稿（包含简短方案概要），基于该计划构建每个用例的目标态运行时调用栈，评审调用栈，并持续细化，直到达到稳定性门禁
```
Go Confirmed
```
  ，然后实时跟踪进度。
- ```
Medium
```
  ：先创建建议设计文档，基于该设计文档构建目标态运行时调用栈，执行迭代式深度评审轮次，直到达到稳定性门禁
```
Go Confirmed
```
  ，仅在此之后创建实施计划并实时跟踪进度。
- ```
Large
```
  ：先创建建议设计文档，基于该设计文档构建目标态运行时调用栈，执行迭代式深度评审轮次，直到达到稳定性门禁
```
Go Confirmed
```
  ，仅在此之后创建实施计划并实时跟踪进度。
实现期间重新评估；如果范围扩大或出现异味，则从
```
Small
```
升级为完整工作流。
转换至 Stage 2 前，更新
```
workflow-state.md
```
快照、转换日志和阶段门禁证据。
仅在
```
workflow-state.md
```
持久化相应的转换或门禁更新后，才可在分流深度（
```
Small
```
/
```
Medium
```
/
```
Large
```
）最终确定且
```
investigation-notes.md
```
保持最新时进行宣布。

2) Refine Requirements Document To Design-Ready (Mandatory)

2）将需求文档细化为设计就绪（强制）

Create/update

tickets/in-progress/<ticket-name>/requirements.md

for all sizes (

Small

Medium

Large

Requirement writing is mandatory even for small tasks (small can be concise).
Use one canonical file path only: update
```
requirements.md
```
in place. Do not create versioned duplicates such as
```
requirements-v2.md
```
.
Requirements maturity flow:
- ```
Draft
```
  : rough capture from report/input evidence,
- ```
Design-ready
```
  : refined after deep understanding pass,
- ```
Refined
```
  : further updates when design/review/implementation feedback reveals gaps.
Minimum required sections in
```
requirements.md
```
:
- status (
```
Draft
```
  /
```
Design-ready
```
  /
```
Refined
```
  ),
- goal/problem statement,
- in-scope use cases,
- acceptance criteria,
- constraints/dependencies,
- assumptions,
- open questions/risks.
Requirements quality rule (mandatory): requirements must be verifiable behavior specifications, not only descriptive narratives.
For each requirement, include a stable
```
requirement_id
```
and explicit expected outcome.
For each acceptance criterion, include a stable
```
acceptance_criteria_id
```
(for example:
```
AC-001
```
) and an explicit measurable expected outcome.
Acceptance criteria must be testable and cover primary behavior plus relevant edge/error behavior.
Include a requirement coverage map to call-stack use cases (all requirements must map to at least one use case).
Include an acceptance-criteria coverage map to Stage 7 scenarios (all acceptance criteria must map to at least one API/E2E scenario).
Confirm the triage result (
```
Small
```
vs
```
Medium
```
vs
```
Large
```
) and rationale in the requirements doc.
Refine requirements from the latest
```
investigation-notes.md
```
; do not derive requirements from memory-only investigation.
Design-ready requirement gate must make expected behavior clear enough to draft design and runtime call stacks.
If understanding is not sufficient to reach
```
Design-ready
```
, continue understanding pass and refine requirements first.
After
```
requirements.md
```
reaches
```
Design-ready
```
and is confirmed as design input, announce only with the persisted
```
workflow-state.md
```
transition/gate update.

对所有范围（

Small

、

Medium

、

Large

）创建或更新

tickets/in-progress/<ticket-name>/requirements.md

。

即使是小任务也必须编写需求（小任务可以简洁）。
只使用一个规范文件路径：原地更新
```
requirements.md
```
。不得创建
```
requirements-v2.md
```
等版本化副本。
需求成熟度流程：
- ```
Draft
```
  ：根据报告或输入证据进行粗略捕获；
- ```
Design-ready
```
  ：深入理解环节后完成细化；
- ```
Refined
```
  ：设计、评审或实现反馈暴露缺口后进一步更新。
```
requirements.md
```
的最低必需章节：
- 状态（
```
Draft
```
  /
```
Design-ready
```
  /
```
Refined
```
  ）；
- 目标或问题陈述；
- 范围内用例；
- 验收标准；
- 约束与依赖；
- 假设；
- 未解决问题与风险。
需求质量规则（强制）：需求必须是可验证的行为规范，而不能只有描述性叙述。
每项需求都必须包含稳定的
```
requirement_id
```
和明确的预期结果。
每项验收标准都必须包含稳定的
```
acceptance_criteria_id
```
（例如：
```
AC-001
```
）和明确、可度量的预期结果。
验收标准必须可测试，并覆盖主要行为以及相关边界/错误行为。
包含需求到调用栈用例的覆盖映射（所有需求至少映射到一个用例）。
包含验收标准到 Stage 7 场景的覆盖映射（所有验收标准至少映射到一个 API/E2E 场景）。
在需求文档中确认分流结果（
```
Small
```
、
```
Medium
```
或
```
Large
```
）及其理由。
根据最新的
```
investigation-notes.md
```
细化需求；不得根据仅存在于内存中的调查生成需求。
设计就绪需求门禁必须使预期行为足够明确，以便起草设计和运行时调用栈。
如果理解程度不足以达到
```
Design-ready
```
，则继续理解环节并先细化需求。
仅在
```
requirements.md
```
达到
```
Design-ready
```
并被确认为设计输入后，才可在持久化的
```
workflow-state.md
```
转换或门禁更新中进行宣布。

Core Modernization Policy (Mandatory)

核心现代化策略（强制）

Mandatory stance: no backward compatibility and no legacy code retention.
Do not preserve legacy behavior, legacy APIs, compatibility wrappers, dual-write paths, or fallback branches kept only for old flows.
Prefer clean replacement and explicit deletion of obsolete code, files, tests, flags, and adapters in the same ticket.
Do not add compatibility exceptions in this workflow.

强制立场：不提供向后兼容，也不保留遗留代码。
不得保留遗留行为、遗留 API、兼容性包装器、双写路径，或仅为旧流程保留的 fallback 分支。
优先采用干净替换，并在同一 ticket 中明确删除过时代码、文件、测试、标志和适配器。
此工作流不允许添加兼容性例外。

Shared Architecture Principles (Design + Review, Mandatory)

共享架构原则（设计与评审，强制）

Design and review must use the same principles and vocabulary. Review is a check of design quality, not a different rule system.
Separation of concerns (SoC) is the cause: responsibilities are split so each module/file/component owns one clear concern.
Layering is usually an emergent result of strong SoC plus clear dependency direction; layering is not a fixed tier taxonomy by default.
Decoupling is the dependency-quality rule: boundaries are replaceable, dependencies stay one-way, and unjustified cycles are rejected.
Module/file placement is the physical-code-organization rule: each file lives in the folder/boundary/platform that owns its concern; if ownership changes, rename/move/split the file instead of leaving it in an arbitrary location.
Layering/extraction trigger rule (mandatory): if coordination policy is repeated across callers (provider selection, fallback, retry, aggregation, routing, fan-out), extract that policy into an orchestration/registry/manager boundary.
Responsibility-overload trigger rule (mandatory): if one file/module starts owning multiple concerns, split concerns and lift coordination into a higher-order boundary.
Anti-overlayering rule (mandatory): do not add a layer that only pass-throughs and owns no coordination policy or boundary concern.
Shared-folder rule (mandatory): place code in a shared/common folder only when it is genuinely cross-cutting and concern-agnostic; do not hide platform-specific code in shared or unrelated directories.
```
Keep
```
is valid when current layers/boundaries are already coherent for in-scope behavior and expected evolution.

设计与评审必须使用相同的原则和术语体系。评审是对设计质量的检查，不得采用另一套规则体系。
关注点分离（SoC）是原因：划分职责，使每个模块、文件或组件只负责一个明确的关注点。
分层通常是强 SoC 与清晰依赖方向共同产生的结果；默认情况下，分层并非固定的层级分类体系。
解耦是依赖质量规则：边界可替换，依赖保持单向，并拒绝无合理依据的循环依赖。
模块/文件位置是物理代码组织规则：每个文件都应位于负责其关注点的目录、边界或平台中；如果所有权发生变化，应重命名、移动或拆分文件，而不是将其留在任意位置。
分层/提取触发规则（强制）：如果协调策略在多个调用方之间重复出现（provider 选择、fallback、重试、聚合、路由、fan-out），应将该策略提取到 orchestration、registry 或 manager 边界中。
职责过载触发规则（强制）：如果一个文件或模块开始负责多个关注点，应拆分关注点，并将协调职责提升到更高阶的边界。
反对过度分层规则（强制）：不得添加仅负责透传且不拥有任何协调策略或边界关注点的层。
共享目录规则（强制）：仅当代码真正属于跨范围且与具体关注点无关时，才将其放入 shared/common 目录；不得将平台特定代码隐藏在共享或无关目录中。
当当前层和边界对于范围内行为及预期演进已经保持一致时，
```
Keep
```
是有效结论。

3) Draft The Proposed Design Document

3）起草建议设计文档

Required for
```
Medium/Large
```
. Optional for
```
Small
```
.
Prerequisite:
```
requirements.md
```
is
```
Design-ready
```
(or
```
Refined
```
) and current for this ticket.
For
```
Small
```
, do not require a full proposed design doc; use the draft implementation plan solution sketch as the lightweight design basis for runtime call stacks.
Architecture-first rule: define the target architecture shape before mapping work onto existing files.
Do not anchor design to current file layout when the layout is structurally wrong for the target behavior.
Module/file placement rule (mandatory): target file paths must match owning concern/boundary/platform; if a file is codex-specific, cloud-specific, UI-specific, infra-specific, or otherwise scope-bound, place it in that canonical area instead of near whichever caller currently imports it.
Layering fitness check (mandatory): assess whether current layering and cross-layer interactions are coherent for the target behavior; treat layering as emergent architecture structure, not fixed tier labels.
Explicitly evaluate whether new layers, modules, boundary interfaces, or orchestration shells should be introduced.
Explicitly evaluate whether existing layers/modules should be split, merged, moved, or removed.
Apply layering/extraction trigger checks explicitly: when provider choice/fallback/retry/aggregation/routing logic repeats across callers, extract orchestration/registry/manager responsibilities into a higher-order boundary.
Reject overlayering: if a proposed layer is only a pass-through with no owned policy/boundary, keep structure flatter.
Record the architecture direction decision and rationale (
```
complexity
```
,
```
testability
```
,
```
operability
```
,
```
evolution cost
```
).
For straightforward local changes, one concise decision is enough; alternatives are optional.
For non-trivial or uncertain architecture changes, include a small alternatives comparison before deciding.
Choose the proper structural change for the problem (
```
Keep
```
,
```
Add
```
,
```
Split
```
,
```
Merge
```
,
```
Move
```
,
```
Remove
```
) without bias toward minimal edits.
```
Keep
```
is a valid outcome when layering and boundary interactions are already coherent.
If a file's concern and folder disagree,
```
Keep
```
is usually invalid; prefer explicit
```
Move
```
,
```
Split
```
, or justified
```
Promote Shared
```
.
Functional/local correctness is not sufficient: if a bug fix "works" but degrades layering or responsibility boundaries, redesign the structure instead of accepting the patch.
Reject patch-on-patch hacks that bypass clear boundaries just to make a local change compile.
Follow separation of concerns after the target architecture direction is chosen: each file/module owns a clear responsibility.
Explicit decoupling rule (mandatory): define and preserve clear module/service/component boundaries so dependencies are one-directional and replaceable.
For
```
Small
```
, the solution sketch in
```
implementation-plan.md
```
must still include a concise architecture sketch (target layers/boundaries and any new modules/files).
Apply separation-of-concerns at the correct technical boundary for the stack:
- frontend/UI scope: evaluate responsibility at view/component level (each component should own a clear concern),
- non-UI scope (backend/service/worker/domain): evaluate responsibility at file/module/service level,
- integration/infrastructure scope: each adapter/module should own one integration concern with clear contracts.
Make the proposed design doc delta-aware, not only target-state:
- include current-state summary (as-is),
- include target-state summary (to-be),
- include explicit change inventory rows for
```
Add
```
  ,
```
Modify
```
  ,
```
Rename/Move
```
  ,
```
Remove
```
  .
List files/modules and their public APIs.
For each file/module, state target layer/boundary placement, responsibility, key APIs, inputs/outputs, dependencies, and change type.
For each file/module, state whether its target path matches the owning concern and record the move/split rationale when placement changes are required.
Include a naming decisions section:
- proposed file/module/API names,
- rationale for each naming choice,
- mapping from old names to new names when renaming.
Use natural, unsurprising, implementation-friendly names; naming choices should be understandable without domain-specific insider context.
Add a naming-drift check section in the design doc:
- verify each file/module name still matches its current responsibility after scope expansion,
- identify drifted names (name no longer represents real behavior),
- choose corrective action per drifted item (
```
Rename
```
  ,
```
Split
```
  ,
```
Move
```
  , or
```
N/A
```
  with rationale),
- map each corrective action to change inventory rows and implementation tasks.
Document dependency flow and cross-reference risk explicitly (including how cycles are avoided or temporarily tolerated).
Document allowed dependency directions between layers/boundaries and note any temporary violations with removal plan.
For
```
Rename/Move
```
and
```
Remove
```
, include decommission/cleanup intent (import cleanup and dead-code removal).
Capture data models and error-handling expectations if relevant.
Add a use-case coverage matrix in the design doc with at least:
- ```
use_case_id
```
  ,
- primary path covered (
```
Yes
```
  /
```
No
```
  ),
- fallback path covered (
```
Yes
```
  /
```
No
```
  /
```
N/A
```
  ),
- error path covered (
```
Yes
```
  /
```
No
```
  /
```
N/A
```
  ),
- mapped sections in runtime call stack doc.
Version the design during review loops (
```
v1
```
,
```
v2
```
, ...) and record what changed between rounds.
Use the template in
```
assets/proposed-design-template.md
```
as a starting point.
No-backward-compat design gate (mandatory): proposed design must not introduce compatibility wrappers, dual-read/dual-write flows, legacy adapters, or fallback branches kept only for old behavior.
If backward-compatibility or legacy-retention mechanisms are required to make the design work, classify as
```
Fail
```
and redesign the architecture direction before continuing.
Do not speak solely because
```
proposed-design.md
```
changed; announce only when the related
```
workflow-state.md
```
transition/gate update is persisted.

```
Medium/Large
```
必需，
```
Small
```
可选。
前置条件：
```
requirements.md
```
对当前 ticket 达到
```
Design-ready
```
（或
```
Refined
```
）并保持最新。
对于
```
Small
```
，不要求完整的建议设计文档；使用
```
implementation-plan.md
```
中的方案概要作为轻量设计依据。
架构优先规则：在将工作映射到现有文件之前，先定义目标架构形态。
当现有文件布局在结构上不适合目标行为时，不得以现有布局为设计锚点。
模块/文件位置规则（强制）：目标文件路径必须与负责的关注点、边界或平台一致；如果文件是 codex 特定、云特定、UI 特定、基础设施特定或其他范围绑定内容，应将其放在相应规范区域，而不是靠近当前导入它的调用方。
分层适配性检查（强制）：评估当前分层和跨层交互是否适合目标行为；将分层视为涌现式架构结构，而不是固定层级标签。
明确评估是否应引入新的层、模块、边界接口或 orchestration 壳层。
明确评估是否应拆分、合并、移动或删除现有层或模块。
明确应用分层/提取触发检查：当 provider 选择、fallback、重试、聚合或路由逻辑在多个调用方之间重复时，将 orchestration、registry 或 manager 职责提取到更高阶边界。
拒绝过度分层：如果建议的层仅负责透传且不拥有任何策略或边界，则保持结构扁平。
记录架构方向决策及其理由（
```
complexity
```
、
```
testability
```
、
```
operability
```
、
```
evolution cost
```
）。
对于直接且局部的变更，一个简洁决策即可；可选项为备选方案。
对于非平凡或不确定的架构变更，在决策前提供小型备选方案比较。
针对问题选择适当的结构变更（
```
Keep
```
、
```
Add
```
、
```
Split
```
、
```
Merge
```
、
```
Move
```
、
```
Remove
```
），不得偏向最小化编辑。
当范围内行为及预期演进的层和边界已经保持一致时，
```
Keep
```
是有效结论。
如果文件关注点与目录不一致，
```
Keep
```
通常无效；应优先采用明确的
```
Move
```
、
```
Split
```
，或经过论证的
```
Promote Shared
```
。
仅保证功能或局部正确性并不充分：如果某个缺陷修复虽然可以运行，却降低了分层质量或职责边界，则应重新设计结构，而不是接受该补丁。
拒绝为使局部变更通过编译而绕过清晰边界的层层打补丁做法。
确定目标架构方向后，在正确的技术边界应用关注点分离：每个文件或模块负责明确的职责。
明确解耦规则（强制）：定义并保持清晰的模块、service 或 component 边界，使依赖保持单向且可替换。
对于
```
Small
```
，
```
implementation-plan.md
```
中的方案概要仍必须包含简洁的架构概要（目标层/边界以及任何新模块/文件）。
在技术栈正确的边界应用关注点分离：
- frontend/UI 范围：在 view/component 层级评估职责（每个 component 应负责明确关注点）；
- 非 UI 范围（backend/service/worker/domain）：在 file/module/service 层级评估职责；
- integration/infrastructure 范围：每个 adapter/module 应负责一个集成关注点，并具有清晰契约。
建议设计文档必须感知差异，而不能只描述目标状态：
- 包含当前状态摘要（as-is）；
- 包含目标状态摘要（to-be）；
- 包含
```
Add
```
  、
```
Modify
```
  、
```
Rename/Move
```
  、
```
Remove
```
  类型的明确变更清单行。
列出文件/模块及其公共 API。
对每个文件/模块说明目标层/边界位置、职责、关键 API、输入/输出、依赖关系和变更类型。
对每个文件/模块说明其目标路径是否与负责的关注点一致；如果需要调整位置，则记录移动/拆分理由。
包含命名决策章节：
- 建议的文件、模块和 API 名称；
- 每个命名选择的理由；
- 重命名时从旧名称到新名称的映射。
使用自然、不令人意外且便于实现的名称；命名选择不得依赖只有领域内部人员才能理解的背景知识。
在设计文档中添加命名漂移检查章节：
- 验证范围扩展后每个文件/模块名称是否仍与其当前职责一致；
- 识别名称已无法代表实际行为的漂移项；
- 为每个漂移项选择纠正措施（
```
Rename
```
  、
```
Split
```
  、
```
Move
```
  ，或带理由的
```
N/A
```
  ）；
- 将每项纠正措施映射到变更清单行和实施任务。
明确记录依赖流和交叉引用风险，包括如何避免循环依赖或如何暂时容忍循环依赖。
记录各层或边界之间允许的依赖方向，并说明任何临时违规及其移除计划。
对于
```
Rename/Move
```
和
```
Remove
```
，包含退役与清理意图（import 清理和死代码移除）。
在相关情况下记录数据模型和错误处理预期。
在设计文档中添加用例覆盖矩阵，至少包含：
- ```
use_case_id
```
  ；
- 是否覆盖主要路径（
```
Yes
```
  /
```
No
```
  ）；
- 是否覆盖 fallback 路径（
```
Yes
```
  /
```
No
```
  /
```
N/A
```
  ）；
- 是否覆盖错误路径（
```
Yes
```
  /
```
No
```
  /
```
N/A
```
  ）；
- 在运行时调用栈文档中映射的章节。
在评审循环中对设计进行版本管理（
```
v1
```
、
```
v2
```
……），并记录各轮之间发生的变更。
使用
```
assets/proposed-design-template.md
```
作为起点。
无向后兼容设计门禁（强制）：建议设计不得引入兼容性包装器、双读/双写流程、遗留适配器，或仅为旧行为保留的 fallback 分支。
如果必须使用向后兼容或遗留保留机制才能使设计成立，则将其分类为
```
Fail
```
，并在继续前重新设计架构方向。
不得仅因
```
proposed-design.md
```
发生变化就进行播报；仅在相关
```
workflow-state.md
```
转换或门禁更新已持久化时进行播报。

4) Build Future-State Runtime Call Stacks Per Use Case

4）为每个用例构建目标态运行时调用栈

Required for all sizes (
```
Small
```
,
```
Medium
```
,
```
Large
```
).
For
```
Small
```
, keep it concise but still cover each in-scope use case with primary path plus key fallback/error branch when relevant.
Basis by scope:
- ```
Small
```
  : use the draft implementation plan solution sketch as the design basis.
- ```
Medium/Large
```
  : use the proposed design document as the design basis.
For each use case, write a future-state runtime call stack from entry point to completion in a debug-trace format.
Use stable
```
use_case_id
```
values and ensure IDs match the design coverage matrix and review artifact.
Use two allowed use-case source types:
- ```
Requirement
```
  : derived from explicit requirement behavior.
- ```
Design-Risk
```
  : derived from architecture or technical risk that must be validated.
Coverage rule (mandatory): every in-scope requirement must be covered by at least one
```
Requirement
```
use case.
For each
```
Design-Risk
```
use case, record the technical objective/risk justification and expected observable outcome.
Treat this artifact as
```
to-be
```
architecture behavior derived from the proposed design (or small-scope solution sketch), not as-is code tracing.
If current code differs from target design, model the target design behavior and record migration/transition notes separately.
Include file and function names at every frame using
```
path/to/file.ts:functionName(...)
```
.
Show architectural boundaries explicitly (e.g., controller -> service -> repository -> external API).
Include primary path and fallback/error paths, not only happy path.
Include explicit use-case coverage status per use case (primary/fallback/error) and mark intentional
```
N/A
```
branches.
Mark async/event boundaries (
```
await
```
, queue enqueue/dequeue, worker loop handoff).
Mark state mutations and persistence points (
```
in-memory state
```
,
```
cache write
```
,
```
DB/file write
```
).
Capture decision gates and conditions that choose one branch over another.
Note key data transformations (input schema -> domain model -> output payload).
Version call stacks to match design revisions from review loops (
```
v1
```
,
```
v2
```
, ...).

Use the template in

assets/future-state-runtime-call-stack-template.md

Do not speak solely because
```
future-state-runtime-call-stack.md
```
changed; announce only when the related
```
workflow-state.md
```
transition/gate update is persisted.

所有范围（
```
Small
```
、
```
Medium
```
、
```
Large
```
）均必需。
对于
```
Small
```
，内容可以简洁，但仍需覆盖每个范围内用例的主要路径，以及相关场景中的关键 fallback/错误分支。
不同范围的设计依据：
- ```
Small
```
  ：使用实施计划草稿中的方案概要作为设计依据。
- ```
Medium/Large
```
  ：使用建议设计文档作为设计依据。
对每个用例，编写从入口点到完成的目标态运行时调用栈，并采用 debug-trace 格式。
使用稳定的
```
use_case_id
```
值，并确保 ID 与设计覆盖矩阵和评审产物一致。
仅允许两种用例来源类型：
- ```
Requirement
```
  ：根据明确的需求行为推导。
- ```
Design-Risk
```
  ：根据必须验证的架构或技术风险推导。
覆盖规则（强制）：每项范围内需求至少由一个
```
Requirement
```
用例覆盖。
对每个
```
Design-Risk
```
用例，记录技术目标或风险理由，以及预期可观察结果。
将该产物视为基于建议设计（或小范围方案概要）的
```
to-be
```
架构行为，而不是 as-is 代码追踪。
如果当前代码与目标设计不同，应建模目标设计行为，并单独记录迁移或转换说明。
每一帧都包含文件与函数名称，格式为
```
path/to/file.ts:functionName(...)
```
。
明确展示架构边界，例如 controller -> service -> repository -> external API。
包含主要路径与 fallback/错误路径，而不只是 happy path。
为每个用例明确记录覆盖状态（主要/fallback/错误），并将有意不适用的分支标记为
```
N/A
```
。
标记异步或事件边界（
```
await
```
、queue enqueue/dequeue、worker loop handoff）。
标记状态变更和持久化点（
```
in-memory state
```
、
```
cache write
```
、
```
DB/file write
```
）。
捕获选择不同分支的决策门和条件。
注明关键数据转换（input schema -> domain model -> output payload）。
对调用栈进行版本管理，以匹配评审循环中的设计修订（
```
v1
```
、
```
v2
```
……）。

使用

assets/future-state-runtime-call-stack-template.md

。

不得仅因
```
future-state-runtime-call-stack.md
```
发生变化就进行播报；仅在相关
```
workflow-state.md
```
转换或门禁更新已持久化时进行播报。

5) Review Future-State Runtime Call Stacks (Future-State + Architecture + Naming + Cleanliness Gate)

5）评审目标态运行时调用栈（目标态 + 架构 + 命名 + 整洁性门禁）

Create

future-state-runtime-call-stack-review.md

as a mandatory review artifact.

Review focus is future-state correctness and implementability against the target design basis (
```
proposed-design.md
```
for
```
Medium/Large
```
, small-scope solution sketch in
```
implementation-plan.md
```
for
```
Small
```
), not parity with current code structure.
Review must challenge architecture choice itself (layering/boundaries/allocation), not only file-level separation of concerns.
Review must explicitly evaluate decoupling quality, not only local correctness.
Review must reuse the same shared architecture principles from Stage 3 (SoC cause, layering emergent result, decoupling dependency quality); do not apply a different principle set in review.
Review must explicitly verify module/file placement against the Stage 3 design basis; wrong folder placement is a structural defect, not a cosmetic nit.
Run review in explicit rounds and record each round in the same review artifact.
In every round, run a dedicated missing-use-case discovery sweep before verdicting the round.
Review each use case against these criteria:
- architecture fit check (
```
Pass
```
  /
```
Fail
```
  ): chosen architecture shape is appropriate for this use case and expected growth,
- shared-principles alignment check (
```
Pass
```
  /
```
Fail
```
  ): SoC is treated as cause, layering as emergent result, and decoupling directionality is preserved consistently with Stage 3 design basis,
- layering fitness check (
```
Pass
```
  /
```
Fail
```
  ): layering and interactions are logical and maintainable, with layering treated as emergent from SoC/coordination needs (no fixed-tier requirement, no required layer-count change when current layering is already coherent),
- boundary placement check (
```
Pass
```
  /
```
Fail
```
  ): responsibilities are assigned to the right layer/module boundary,
- decoupling check (
```
Pass
```
  /
```
Fail
```
  ): dependency directions stay one-way, avoid tight cross-module coupling, and avoid cyclic cross-references,
- module/file placement alignment check (
```
Pass
```
  /
```
Fail
```
  ): file/module path matches owning concern/boundary/platform, and any shared placement is explicitly justified,
- existing-structure bias check (
```
Pass
```
  /
```
Fail
```
  ): design is not forced to mirror current files when that harms target architecture,
- anti-hack check (
```
Pass
```
  /
```
Fail
```
  ): no patch-on-patch tricks that hide architecture issues behind local fixes,
- local-fix degradation check (
```
Pass
```
  /
```
Fail
```
  ): a functionally working fix does not degrade architecture or separation of concerns,
- terminology and concept vocabulary is natural and intuitive (
```
Pass
```
  /
```
Fail
```
  ),
- file/API naming is clear and unsurprising for implementation mapping (
```
Pass
```
  /
```
Fail
```
  ),
- name-to-responsibility alignment under scope drift (
```
Pass
```
  /
```
Fail
```
  ),
- future-state alignment with target design basis (
```
Pass
```
  /
```
Fail
```
  ),
- use-case coverage completeness (primary/fallback/error coverage) (
```
Pass
```
  /
```
Fail
```
  ),
- use-case source traceability (
```
Pass
```
  /
```
Fail
```
  ) (
```
Requirement
```
  or
```
Design-Risk
```
  , with source reference),
- requirement coverage closure (
```
Pass
```
  /
```
Fail
```
  ) (all requirements mapped to at least one use case),
- design-risk use-case justification quality (
```
Pass
```
  /
```
Fail
```
  ) (clear objective/risk and expected outcome),
- business flow completeness (
```
Pass
```
  /
```
Fail
```
  ),
- gap findings,
- layer-appropriate structure and separation-of-concerns check (
```
Pass
```
  /
```
Fail
```
  ) (frontend/UI: view/component boundary; non-UI: file/module/service boundary),
- dependency flow smells,
- redundancy/duplication check (
```
Pass
```
  /
```
Fail
```
  ),
- simplification opportunity check (
```
Pass
```
  /
```
Fail
```
  ),
- remove/decommission and obsolete/deprecated/dead-path cleanup completeness for impacted changes (
```
Pass
```
  /
```
Fail
```
  ),
- legacy-retention cleanup check (
```
Pass
```
  /
```
Fail
```
  ) (obsolete old-behavior/deprecated/dead paths are removed for impacted scope),
- backward-compatibility mechanism check (
```
Pass
```
  /
```
Fail
```
  ) (no compatibility wrappers, dual-path behavior, or legacy fallback branches retained),
- overall verdict (
```
Pass
```
  /
```
Fail
```
  ).
Round policy:
- use deep review for every round (challenge assumptions, edge cases, and cleanup quality),
- if a round finds blockers, requires persisted artifact updates, or discovers new use cases, classify the round (
```
Design Impact
```
  /
```
Requirement Gap
```
  /
```
Unclear
```
  ), apply required upstream updates through the classified stage path, and reset clean-review streak to 0,
- if a round finds no blockers, no required persisted artifact updates, and no newly discovered use cases, mark
```
Candidate Go
```
  and increment clean-review streak,
- open
```
Go
```
  only when clean-review streak reaches 2 consecutive deep-review rounds.
Across rounds, track trend quality: issues should decline in count/severity or become more localized; otherwise escalate design refinement before proceeding.
Round staged re-entry discipline (mandatory):
- Step A: run review + missing-use-case discovery and record findings in the current round.
- Step B: classify blockers as exactly one of
```
Design Impact
```
  /
```
Requirement Gap
```
  /
```
Unclear
```
  .
- Step C: if findings require updates, transition to the classified upstream stage path first, then modify required artifacts there and bump versions (
```
vN -> vN+1
```
  ).
- Step D: record an "Applied Updates" entry in the review artifact (what changed, where, and why), including classification + return path.
- Step E: start the next round from updated files only; do not carry unresolved edits in memory.
- Step F: record clean-review streak state in the review artifact (
```
Reset
```
  ,
```
Candidate Go
```
  , or
```
Go Confirmed
```
  ).
Gate
```
Go
```
criteria (all required):
- architecture fit check is
```
Pass
```
  for all in-scope use cases,
- shared-principles alignment check is
```
Pass
```
  for all in-scope use cases,
- layering fitness check is
```
Pass
```
  for all in-scope use cases,
- boundary placement check is
```
Pass
```
  for all in-scope use cases,
- decoupling check is
```
Pass
```
  for all in-scope use cases,
- module/file placement alignment check is
```
Pass
```
  for all in-scope use cases,
- existing-structure bias check is
```
Pass
```
  for all in-scope use cases,
- anti-hack check is
```
Pass
```
  for all in-scope use cases,
- local-fix degradation check is
```
Pass
```
  for all in-scope use cases,
- terminology/concept vocabulary is
```
Pass
```
  for all in-scope use cases,
- file/API naming clarity is
```
Pass
```
  for all in-scope use cases,
- name-to-responsibility alignment under scope drift is
```
Pass
```
  for all in-scope use cases,
- future-state behavior is consistent with target design basis across all in-scope use cases,
- layer-appropriate structure and separation-of-concerns check is
```
Pass
```
  for all in-scope use cases,
- use-case coverage completeness is
```
Pass
```
  for all in-scope use cases,
- use-case source traceability is
```
Pass
```
  for all in-scope use cases,
- requirement coverage closure is
```
Pass
```
  for the full in-scope requirement set,
- design-risk use-case justification quality is
```
Pass
```
  for all design-risk use cases,
- redundancy/duplication check is
```
Pass
```
  for all in-scope use cases,
- simplification opportunity check is
```
Pass
```
  for all in-scope use cases,
- all in-scope use cases have overall verdict
```
Pass
```
  ,
- no unresolved blocking findings (including any required design/call-stack updates),
- for any impacted
```
Add
```
  /
```
Modify
```
  /
```
Rename/Move
```
  /
```
Remove
```
  scope items, decommission/cleanup and obsolete/deprecated/dead-path checks are
```
Pass
```
  ,
- no new use cases are discovered in either of the two clean rounds,
- legacy-retention cleanup check is
```
Pass
```
  for all in-scope use cases,
- backward-compatibility mechanism check is
```
Pass
```
  for all in-scope use cases,
- two consecutive deep-review rounds have no blockers, no required persisted artifact updates, and no newly discovered use cases.
If issues are found:
- classify each blocking round as exactly one of
```
Design Impact
```
  /
```
Requirement Gap
```
  /
```
Unclear
```
  and record it in
```
future-state-runtime-call-stack-review.md
```
  and
```
workflow-state.md
```
  .
- ```
Design Impact
```
  (clear and high-confidence design issue): update design basis in Stage 3 (
```
Medium/Large
```
  :
```
proposed-design.md
```
  ;
```
Small
```
  : design section in
```
implementation-plan.md
```
  ), regenerate call stacks in Stage 4, then return to Stage 5.
- ```
Requirement Gap
```
  : update
```
requirements.md
```
  first in Stage 2 (status
```
Refined
```
  ), then update design basis in Stage 3, regenerate call stacks in Stage 4, then return to Stage 5.
- ```
Unclear
```
  (cross-cutting/low-confidence): update
```
investigation-notes.md
```
  in Stage 1 first, then proceed through
```
2 -> 3 -> 4 -> 5
```
  .
If naming drift is found, prefer explicit rename/split/move updates in the same review loop instead of carrying stale names forward.
Even when a round reports no findings, still complete the round record in-file and run another deep-review round until the two-consecutive-clean stability rule is satisfied.
Repeat until all gate
```
Go Confirmed
```
criteria are satisfied.

Use the template in

assets/future-state-runtime-call-stack-review-template.md

创建

future-state-runtime-call-stack-review.md

作为强制评审产物。

评审重点是目标态的正确性与可实现性，并对照目标设计依据（
```
Medium/Large
```
使用
```
proposed-design.md
```
，
```
Small
```
使用
```
implementation-plan.md
```
中的方案概要），而不是要求与当前代码结构保持一致。
评审必须挑战架构选择本身（分层、边界和职责分配），而不能只检查文件级关注点分离。
评审必须明确评估解耦质量，而不能只检查局部正确性。
评审必须复用 Stage 3 的同一套共享架构原则（SoC 是原因，分层是涌现结果，解耦是依赖质量）；不得采用不同的原则体系。
评审必须根据 Stage 3 设计依据明确验证模块/文件位置；目录位置错误属于结构性缺陷，而不是表面问题。
以明确的轮次执行评审，并在同一评审产物中记录每一轮。
每一轮在给出结论前，都必须执行专门的缺失用例扫描。
根据以下标准评审每个用例：
- 架构适配检查（
```
Pass
```
  /
```
Fail
```
  ）：所选架构形态适合该用例及预期增长；
- 共享原则一致性检查（
```
Pass
```
  /
```
Fail
```
  ）：始终将 SoC 视为原因、将分层视为涌现结果，并按照 Stage 3 设计依据保持解耦方向性；
- 分层适配性检查（
```
Pass
```
  /
```
Fail
```
  ）：分层和交互逻辑清晰且可维护，将分层视为从 SoC 与协调需求中涌现，不要求固定层级，也不要求在当前分层已保持一致时改变层级数量；
- 边界位置检查（
```
Pass
```
  /
```
Fail
```
  ）：职责被分配到正确的层或模块边界；
- 解耦检查（
```
Pass
```
  /
```
Fail
```
  ）：依赖方向保持单向，避免紧密的跨模块耦合和循环交叉引用；
- 模块/文件位置一致性检查（
```
Pass
```
  /
```
Fail
```
  ）：文件或模块路径符合负责的关注点、边界或平台，任何共享位置均有明确理由；
- 现有结构偏差检查（
```
Pass
```
  /
```
Fail
```
  ）：设计未被迫镜像会损害目标架构的现有文件；
- 反对临时修补检查（
```
Pass
```
  /
```
Fail
```
  ）：不存在通过局部修复掩盖架构问题的层层打补丁做法；
- 局部修复降级检查（
```
Pass
```
  /
```
Fail
```
  ）：功能可用的修复没有降低架构质量或关注点分离程度；
- 术语和概念词汇自然且直观（
```
Pass
```
  /
```
Fail
```
  ）；
- 文件/API 命名清晰且不令人意外，便于映射到实现（
```
Pass
```
  /
```
Fail
```
  ）；
- 范围漂移后名称与职责保持一致（
```
Pass
```
  /
```
Fail
```
  ）；
- 目标态与目标设计依据一致（
```
Pass
```
  /
```
Fail
```
  ）；
- 用例覆盖完整性（主要/fallback/错误覆盖）（
```
Pass
```
  /
```
Fail
```
  ）；
- 用例来源可追溯性（
```
Pass
```
  /
```
Fail
```
  ）（
```
Requirement
```
  或
```
Design-Risk
```
  ，并包含来源引用）；
- 需求覆盖闭环（
```
Pass
```
  /
```
Fail
```
  ）（所有需求至少映射到一个用例）；
- 设计风险用例论证质量（
```
Pass
```
  /
```
Fail
```
  ）（目标/风险和预期结果清晰）；
- 业务流程完整性（
```
Pass
```
  /
```
Fail
```
  ）；
- 缺口发现；
- 层级适配结构与关注点分离检查（
```
Pass
```
  /
```
Fail
```
  ）（frontend/UI：view/component 边界；非 UI：file/module/service 边界）；
- 依赖流异味；
- 冗余/重复检查（
```
Pass
```
  /
```
Fail
```
  ）；
- 简化机会检查（
```
Pass
```
  /
```
Fail
```
  ）；
- 受影响变更的 remove/decommission 以及 obsolete/deprecated/dead-path 清理完整性（
```
Pass
```
  /
```
Fail
```
  ）；
- 遗留保留清理检查（
```
Pass
```
  /
```
Fail
```
  ）（受影响范围内已删除过时的旧行为、已弃用路径和死路径）；
- 向后兼容机制检查（
```
Pass
```
  /
```
Fail
```
  ）（未保留兼容性包装器、双路径行为或遗留 fallback 分支）；
- 总体结论（
```
Pass
```
  /
```
Fail
```
  ）。
轮次策略：
- 每一轮都使用深度评审，挑战假设、边界情况和清理质量；
- 如果某轮发现阻塞项、需要持久化更新产物或发现新用例，则对该轮进行分类（
```
Design Impact
```
  /
```
Requirement Gap
```
  /
```
Unclear
```
  ），沿分类后的阶段路径应用所需的上游更新，并将无问题评审连续计数重置为 0；
- 如果某轮未发现阻塞项、无需持久化更新产物且未发现新用例，则标记为
```
Candidate Go
```
  ，并将无问题评审连续计数加 1；
- 仅当无问题评审连续计数达到连续两轮深度评审时，才开放
```
Go
```
  。
跨轮次跟踪趋势质量：问题的数量或严重程度应持续下降，或变得更加局部化；否则应在继续前进一步强化设计。
轮次分阶段重新进入纪律（强制）：
- 步骤 A：执行评审与缺失用例发现，并在当前轮次中记录发现。
- 步骤 B：将阻塞项准确分类为
```
Design Impact
```
  /
```
Requirement Gap
```
  /
```
Unclear
```
  中的一种。
- 步骤 C：如果发现要求更新产物，先转换至分类后的上游阶段路径，然后在该阶段修改必要产物并提升版本（
```
vN -> vN+1
```
  ）。
- 步骤 D：在评审产物中记录「Applied Updates」条目，包括变更内容、位置、原因、分类和返回路径。
- 步骤 E：仅基于更新后的文件开始下一轮；不得在内存中携带未解决的编辑。
- 步骤 F：在评审产物中记录无问题评审连续计数状态（
```
Reset
```
  、
```
Candidate Go
```
  或
```
Go Confirmed
```
  ）。
```
Go
```
门禁标准（全部必需）：
- 所有范围内用例的架构适配检查均为
```
Pass
```
  ；
- 所有范围内用例的共享原则一致性检查均为
```
Pass
```
  ；
- 所有范围内用例的分层适配性检查均为
```
Pass
```
  ；
- 所有范围内用例的边界位置检查均为
```
Pass
```
  ；
- 所有范围内用例的解耦检查均为
```
Pass
```
  ；
- 所有范围内用例的模块/文件位置一致性检查均为
```
Pass
```
  ；
- 所有范围内用例的现有结构偏差检查均为
```
Pass
```
  ；
- 所有范围内用例的反对临时修补检查均为
```
Pass
```
  ；
- 所有范围内用例的局部修复降级检查均为
```
Pass
```
  ；
- 所有范围内用例的术语/概念词汇检查均为
```
Pass
```
  ；
- 所有范围内用例的文件/API 命名清晰度检查均为
```
Pass
```
  ；
- 所有范围内用例的范围漂移后名称与职责一致性检查均为
```
Pass
```
  ；
- 所有范围内用例的目标态行为与目标设计依据一致；
- 所有范围内用例的层级适配结构与关注点分离检查均为
```
Pass
```
  ；
- 所有范围内用例的用例覆盖完整性检查均为
```
Pass
```
  ；
- 所有范围内用例的用例来源可追溯性检查均为
```
Pass
```
  ；
- 完整范围内需求集的覆盖闭环检查为
```
Pass
```
  ；
- 所有设计风险用例的设计风险用例论证质量检查为
```
Pass
```
  ；
- 所有范围内用例的冗余/重复检查均为
```
Pass
```
  ；
- 所有范围内用例的简化机会检查均为
```
Pass
```
  ；
- 所有范围内用例的总体结论均为
```
Pass
```
  ；
- 不存在未解决的阻塞性发现，包括任何需要更新的设计/调用栈；
- 对任何受影响的
```
Add
```
  /
```
Modify
```
  /
```
Rename/Move
```
  /
```
Remove
```
  范围项，退役/清理及 obsolete/deprecated/dead-path 检查均为
```
Pass
```
  ；
- 两轮无问题评审均未发现新用例；
- 所有范围内用例的遗留保留清理检查均为
```
Pass
```
  ；
- 所有范围内用例的向后兼容机制检查均为
```
Pass
```
  ；
- 连续两轮深度评审均无阻塞项、无需持久化更新产物且未发现新用例。
如果发现问题：
- 将每个阻塞性轮次准确分类为
```
Design Impact
```
  /
```
Requirement Gap
```
  /
```
Unclear
```
  中的一种，并记录到
```
future-state-runtime-call-stack-review.md
```
  和
```
workflow-state.md
```
  。
- ```
Design Impact
```
  （明确且高置信度的设计问题）：在 Stage 3 更新设计依据（
```
Medium/Large
```
  ：
```
proposed-design.md
```
  ；
```
Small
```
  ：
```
implementation-plan.md
```
  中的设计部分），在 Stage 4 重新生成调用栈，然后返回 Stage 5。
- ```
Requirement Gap
```
  ：先在 Stage 2 更新
```
requirements.md
```
  （状态设为
```
Refined
```
  ），然后在 Stage 3 更新设计依据，在 Stage 4 重新生成调用栈，再返回 Stage 5。
- ```
Unclear
```
  （跨范围或低置信度）：先在 Stage 1 更新
```
investigation-notes.md
```
  ，然后继续执行
```
2 -> 3 -> 4 -> 5
```
  。
如果发现命名漂移，应优先在同一评审循环中执行明确的 rename/split/move 更新，而不是继续沿用过时名称。
即使某轮未报告任何发现，也必须完成文件内的轮次记录，并继续执行另一轮深度评审，直到满足连续两轮无问题的稳定性规则。
重复执行，直到满足所有
```
Go Confirmed
```
门禁标准。

使用

assets/future-state-runtime-call-stack-review-template.md

。

6) Implement Source + Unit/Integration And Track Progress

6）实现源代码并执行单元/集成测试，同时跟踪进度

Use a bottom-up, test-driven approach: implement foundational dependencies first.
Sequence is mandatory:
- first ensure
```
implementation-plan.md
```
  is finalized,
- then initialize/update
```
implementation-progress.md
```
  ,
- then execute source implementation with required unit/integration verification.
Stage separation rule (mandatory):
- Stage 6 implements source code and verifies file/module/service boundaries with unit/integration tests.
- Stage 7 implements API/E2E tests and runs API/E2E test scenarios against acceptance criteria.
- Stage 8 runs the code review gate after Stage 7 passes.

Include requirement traceability in plan/progress (

requirement -> design section -> call stack/use_case -> implementation tasks/tests

Integration test coverage is required for behavior that crosses module boundaries, process boundaries, storage boundaries, or external API boundaries. If any such behavior is not covered, record a concrete rationale.
Finalize planning artifacts before kickoff:
- ```
Small
```
  : refine the draft implementation plan until future-state runtime call stack review passes final stability gate (
```
Go Confirmed
```
  ).
- ```
Medium/Large
```
  : create implementation plan only after future-state runtime call stack review passes final stability gate (
```
Go Confirmed
```
  ).
Create the implementation progress document at implementation kickoff, after required pre-implementation artifacts are ready (including the proposed design document for Medium/Large).
Implementation plan + real-time progress tracking are required for all sizes (
```
Small
```
,
```
Medium
```
,
```
Large
```
).
Treat future-state runtime call stack + review as a pre-implementation verification gate: ensure each use case is represented and reviewed before coding starts.
Start implementation only after the review gate says implementation can start and all in-scope use cases are
```
Pass
```
.
Before first source-code edit in Stage 6, update
```
workflow-state.md
```
:
- set
```
Current Stage = 6
```
  ,
- set
```
Code Edit Permission = Unlocked
```
  ,
- record transition evidence that Stage 5 gate is
```
Go Confirmed
```
  and pre-edit checklist is satisfied.
Ensure traceability when a proposed design doc exists: every design change-inventory row (especially
```
Rename/Move
```
and
```
Remove
```
) maps to implementation tasks and verification steps.
Enforce clean-cut implementation: do not keep legacy compatibility paths.
No-backward-compat implementation rule (mandatory): reject compatibility wrappers, dual-path reads/writes, and old-behavior fallback branches even if they make rollout easier.
Decoupling-preservation implementation rule (mandatory): implementation must not introduce new tight coupling or cyclic dependencies across layers/modules.
Module/file placement preservation rule (mandatory): do not leave touched files in the wrong concern folder just to minimize edits; move/split them when the current path no longer matches ownership.
Implementation completeness rule (mandatory): implementation is not complete until obsolete code paths and compatibility shims in scope are removed.
Stage 6 failure classification rule (mandatory):
- ```
Local Fix
```
  : issue is bounded and does not require requirement/design/call-stack updates; remain in Stage 6.
- ```
Design Impact
```
  : issue indicates architecture/decoupling or compatibility-policy breach requiring upstream design/runtime updates; re-enter
```
Stage 1 -> Stage 3 -> Stage 4 -> Stage 5 -> Stage 6
```
  .
- ```
Requirement Gap
```
  : missing/ambiguous requirement or acceptance criteria discovered during implementation; re-enter
```
Stage 2 -> Stage 3 -> Stage 4 -> Stage 5 -> Stage 6
```
  .
- ```
Unclear
```
  : cross-cutting/low-confidence root cause; re-enter
```
Stage 0 -> Stage 1 -> Stage 2 -> Stage 3 -> Stage 4 -> Stage 5 -> Stage 6
```
  .
If a change only "works" by leaving a file in the wrong folder or adding new misplaced files, do not classify it as
```
Local Fix
```
; treat it as
```
Design Impact
```
unless the real issue is missing requirements.
Use "one file at a time" as the default execution strategy, not an absolute rule.
When rare cross-referencing is unavoidable, allow limited parallel/incomplete implementation, but explicitly record:
- the cross-reference smell,
- the blocked dependency edge,
- the condition to unblock,
- the required proposed-design-document update.
Update progress in real time during implementation (immediately after file status changes, test runs, blocker discoveries, and design-feedback-loop updates).
Track change IDs and change types in progress (
```
Add
```
/
```
Modify
```
/
```
Rename/Move
```
/
```
Remove
```
) so refactor deltas remain explicit through execution.
Track file build state explicitly (
```
Pending
```
,
```
In Progress
```
,
```
Blocked
```
,
```
Completed
```
,
```
N/A
```
).
Track unit/integration test state separately (
```
Not Started
```
,
```
In Progress
```
,
```
Passed
```
,
```
Failed
```
,
```
Blocked
```
,
```
N/A
```
).
If a file is blocked by unfinished dependencies, mark it
```
Blocked
```
and record the dependency and unblock condition.
Mark a file
```
Completed
```
only when implementation is done and required tests are passing.
Mark Stage 6 complete only when:
- implementation plan scope is delivered (or deviations are explicitly documented),
- required unit/integration tests pass,
- no backward-compatibility shims or legacy old-behavior branches remain in scope,
- decoupling boundaries remain valid (no newly introduced unjustified tight coupling/cyclic dependencies),
- touched files either already have correct placement or are moved/split so their paths match owning concerns.

Use

assets/implementation-plan-template.md

and

assets/implementation-progress-template.md

Do not speak for routine
```
implementation-plan.md
```
/
```
implementation-progress.md
```
edits. Announce only for persisted
```
workflow-state.md
```
events (Stage 6 entry, lock/unlock change, gate/transition outcomes).

采用自底向上的测试驱动方式：先实现基础依赖。
必须遵循以下顺序：
- 首先确保
```
implementation-plan.md
```
  已最终确定；
- 然后初始化或更新
```
implementation-progress.md
```
  ；
- 随后执行源代码实现，并完成必要的单元/集成测试验证。
阶段分离规则（强制）：
- Stage 6 实现源代码，并通过单元/集成测试验证 file/module/service 边界。
- Stage 7 实现 API/E2E 测试，并针对验收标准运行 API/E2E 测试场景。
- Stage 8 在 Stage 7 通过后执行代码评审门禁。

在计划与进度中包含需求可追溯性（

requirement -> design section -> call stack/use_case -> implementation tasks/tests

）。

对跨越模块边界、进程边界、存储边界或外部 API 边界的行为，必须提供集成测试覆盖。如果未覆盖，则记录具体理由。
在启动实现前最终确定规划产物：
- ```
Small
```
  ：细化实施计划草稿，直到目标态运行时调用栈评审通过最终稳定性门禁（
```
Go Confirmed
```
  ）。
- ```
Medium/Large
```
  ：仅在目标态运行时调用栈评审通过最终稳定性门禁（
```
Go Confirmed
```
  ）后创建实施计划。
在实现启动时创建实施进度文档，此时所有必要的实现前产物均已准备完成（包括
```
Medium/Large
```
任务的建议设计文档）。
所有范围（
```
Small
```
、
```
Medium
```
、
```
Large
```
）均必须提供实施计划与实时进度跟踪。
将目标态运行时调用栈及其评审作为实现前验证门禁：确保每个用例在开始编码前均已表示并评审。
仅在评审门禁明确允许开始实现且所有范围内用例均为
```
Pass
```
后，才能开始实现。
在 Stage 6 首次编辑源代码前，更新
```
workflow-state.md
```
：
- 设置
```
Current Stage = 6
```
  ；
- 设置
```
Code Edit Permission = Unlocked
```
  ；
- 记录转换证据，证明 Stage 5 门禁为
```
Go Confirmed
```
  ，且编辑前检查清单已满足。
存在建议设计文档时，确保可追溯性：每个设计变更清单行（尤其是
```
Rename/Move
```
和
```
Remove
```
）都映射到实施任务和验证步骤。
执行干净切换式实现：不得保留遗留兼容路径。
无向后兼容实现规则（强制）：即使兼容包装器、双路径读写和旧行为 fallback 分支能够简化发布，也必须拒绝这些实现。
保持解耦实现规则（强制）：实现不得在各层或模块之间引入新的紧密耦合或循环依赖。
保持模块/文件位置规则（强制）：不得仅为减少编辑而将变更文件留在错误的关注点目录；当现有路径不再匹配所有权时，应移动或拆分文件。
实现完整性规则（强制）：只有在范围内的过时代码路径和兼容 shim 被移除后，实现才算完成。
Stage 6 失败分类规则（强制）：
- ```
Local Fix
```
  ：问题范围受限，不需要更新需求、设计或调用栈；保持在 Stage 6。
- ```
Design Impact
```
  ：问题表明存在架构、解耦或兼容策略违规，需要更新上游设计/运行时内容；重新进入
```
Stage 1 -> Stage 3 -> Stage 4 -> Stage 5 -> Stage 6
```
  。
- ```
Requirement Gap
```
  ：实现期间发现缺少或存在歧义的需求或验收标准；重新进入
```
Stage 2 -> Stage 3 -> Stage 4 -> Stage 5 -> Stage 6
```
  。
- ```
Unclear
```
  ：根因跨范围或置信度低；重新进入
```
Stage 0 -> Stage 1 -> Stage 2 -> Stage 3 -> Stage 4 -> Stage 5 -> Stage 6
```
  。
如果某项变更仅通过将文件留在错误目录或添加位置不当的新文件才得以工作，不得将其分类为
```
Local Fix
```
；除非真正问题是缺少需求，否则应归类为
```
Design Impact
```
。
默认执行策略为「一次处理一个文件」，但这不是绝对规则。
当极少数交叉引用不可避免时，允许有限并行或不完整的实现，但必须明确记录：
- 交叉引用异味；
- 被阻塞的依赖边；
- 解除阻塞的条件；
- 所需的建议设计文档更新。
实现期间实时更新进度（文件状态变化、测试运行、阻塞项发现和设计反馈循环更新后立即更新）。
在进度中跟踪变更 ID 和变更类型（
```
Add
```
/
```
Modify
```
/
```
Rename/Move
```
/
```
Remove
```
），确保重构差异在执行过程中保持明确。
明确跟踪文件构建状态（
```
Pending
```
、
```
In Progress
```
、
```
Blocked
```
、
```
Completed
```
、
```
N/A
```
）。
单独跟踪单元/集成测试状态（
```
Not Started
```
、
```
In Progress
```
、
```
Passed
```
、
```
Failed
```
、
```
Blocked
```
、
```
N/A
```
）。
如果文件被未完成的依赖阻塞，将其标记为
```
Blocked
```
，并记录依赖关系与解除阻塞的条件。
仅当实现完成且必要测试通过时，才可将文件标记为
```
Completed
```
。
仅在以下条件全部满足时，才能将 Stage 6 标记为完成：
- 实施计划范围已交付，或偏差已明确记录；
- 必要的单元/集成测试通过；
- 范围内不存在向后兼容 shim 或遗留旧行为分支；
- 解耦边界仍然有效，未引入新的无合理依据的紧密耦合或循环依赖；
- 变更文件要么已位于正确位置，要么已移动或拆分，使其路径符合负责的关注点。

使用

assets/implementation-plan-template.md

和

assets/implementation-progress-template.md

。

不得为常规
```
implementation-plan.md
```
/
```
implementation-progress.md
```
编辑进行播报。仅在持久化的
```
workflow-state.md
```
发生事件（进入 Stage 6、锁定状态解锁、门禁或转换结果）时播报。

7) Implement API/E2E Tests And Run API/E2E Test Gate (Mandatory)

7）实现 API/E2E 测试并执行 API/E2E 测试门禁（强制）

Run this stage immediately after
```
Stage 6
```
completes.
At Stage 7 entry, update
```
workflow-state.md
```
and keep
```
Code Edit Permission = Unlocked
```
while API/E2E test artifacts are being implemented/executed.
Create/update
```
tickets/in-progress/<ticket-name>/api-e2e-testing.md
```
as the canonical scenario + result artifact.
Stage 7 scope includes:
- implementing API test files/harness as needed,
- implementing E2E test files/harness as needed,
- executing API/E2E scenarios mapped from acceptance criteria.
If Stage 7 failures require source-code changes, declare re-entry and return to Stage 6 first.
Scenario sources (mandatory):
- requirement-driven scenarios (must cover all critical requirements and flows),
- design-risk-driven scenarios (must cover technical risks introduced by architecture/design choices).
Acceptance-criteria closure loop (mandatory):
- build and maintain an explicit Stage 7 acceptance-criteria matrix sourced from
```
requirements.md
```
  (
```
acceptance_criteria_id
```
  -> mapped scenario IDs -> execution status),
- every in-scope acceptance criterion must map to at least one executable API/E2E scenario before execution starts,
- any acceptance criterion with status
```
Unmapped
```
  ,
```
Not Run
```
  ,
```
Failed
```
  , or
```
Blocked
```
  keeps Stage 7 open and requires re-entry unless explicitly marked
```
Waived
```
  by user decision for infeasible cases,
- rerun the required re-entry chain and return to Stage 7 until all in-scope acceptance criteria are
```
Passed
```
  or explicitly
```
Waived
```
  .
For each scenario, record at minimum:
- ```
scenario_id
```
  ,
- mapped
```
acceptance_criteria_id
```
  values,
- mapped
```
requirement_id
```
  and
```
use_case_id
```
  values,
- source type (
```
Requirement
```
  /
```
Design-Risk
```
  ),
- test level (
```
API
```
  /
```
E2E
```
  ),
- expected outcome,
- execution command/harness,
- result (
```
Passed
```
  /
```
Failed
```
  /
```
Blocked
```
  /
```
N/A
```
  ).
API test depth rule (mandatory): when scenario level is
```
API
```
, validate contract-level behavior including required fields/schema shape, status codes, and error payload behavior for mapped acceptance criteria.
Cross-boundary test rule (mandatory): for client/server or multi-service scope, include API/E2E scenarios that validate cross-boundary interaction behavior (request -> boundary handoff -> downstream effect -> returned state).
Manual testing policy: do not include manual testing in the default workflow. If the user performs manual verification outside the workflow, treat the user's explicit completion/verification message as the Stage 10 trigger to move the ticket to
```
done
```
and start repository finalization.
Feasibility policy:
- if a scenario is not executable in current environment (missing secrets/tokens, unavailable partner system, infra limit), record concrete infeasibility reasons and constraints in
```
api-e2e-testing.md
```
  and
```
implementation-progress.md
```
  ,
- record compensating automated evidence and residual risk notes for each infeasible critical scenario,
- mark Stage 7 as
```
Blocked
```
  unless the user explicitly accepts a waiver for the infeasible acceptance criteria.
Test feedback escalation policy (mandatory):
- classify each failing Stage 7 scenario as exactly one of
```
Local Fix
```
  ,
```
Design Impact
```
  ,
```
Requirement Gap
```
  , or
```
Unclear
```
  ,
- before final classification, run an investigation screen:
  - if issue scope is cross-cutting, touches unknown runtime paths, or root-cause confidence is low, mark
```
Investigation Required
```
    and reopen understanding stage first (
```
investigation-notes.md
```
    must be updated before design/requirements artifact updates),
  - if issue is clearly bounded with high root-cause confidence, continue classification directly.
- ```
Local Fix
```
  is allowed only when responsibility boundaries stay intact, no new use case/acceptance criterion is needed, and no requirement/design changes are needed.
- if a fix works functionally but degrades layering/separation-of-concerns, it is not
```
Local Fix
```
  ; classify as
```
Design Impact
```
  .
- if a fix only works by leaving a file in the wrong folder or adding a new misplaced file, it is not
```
Local Fix
```
  ; classify as
```
Design Impact
```
  .
- classify as
```
Requirement Gap
```
  when failing behavior reveals missing functionality/use case or missing/ambiguous acceptance criteria.
- apply re-entry declaration before source code edits when source/design/requirement updates are needed.
- ```
Local Fix
```
  path: update artifacts first, then rerun
```
Stage 6 -> Stage 7
```
  .
- ```
Design Impact
```
  path:
```
Stage 1 -> Stage 3 -> Stage 4 -> Stage 5 -> Stage 6 -> Stage 7
```
  .
- ```
Requirement Gap
```
  path:
```
Stage 2 -> Stage 3 -> Stage 4 -> Stage 5 -> Stage 6 -> Stage 7
```
  .
- ```
Unclear
```
  /cross-cutting root cause path:
```
Stage 0 -> Stage 1 -> Stage 2 -> Stage 3 -> Stage 4 -> Stage 5 -> Stage 6 -> Stage 7
```
  .
Stage completion gate:
- all in-scope acceptance criteria from
```
requirements.md
```
  are mapped to Stage 7 scenarios,
- all executable in-scope acceptance criteria have execution status
```
Passed
```
  ,
- all executable mapped API/E2E scenarios are resolved (
```
Passed
```
  ), with no unresolved failures/blockers,
- if any acceptance criterion is infeasible due to environment constraints, Stage 7 remains
```
Blocked
```
  until explicit user waiver is recorded with constraints + compensating evidence + residual risk.
Before transitioning to Stage 8, update
```
workflow-state.md
```
with Stage 7 gate result and transition evidence.
Use
```
assets/api-e2e-testing-template.md
```
.
Do not speak for
```
api-e2e-testing.md
```
edits alone. Announce when
```
workflow-state.md
```
records Stage 7 entry, gate result, and any re-entry declaration/lock-state change.

Stage 6 完成后立即执行此阶段。
进入 Stage 7 时，更新
```
workflow-state.md
```
，并在实施和执行 API/E2E 测试产物期间保持
```
Code Edit Permission = Unlocked
```
。
创建或更新
```
tickets/in-progress/<ticket-name>/api-e2e-testing.md
```
，作为规范的场景与结果产物。
Stage 7 范围包括：
- 按需实现 API 测试文件或测试 harness；
- 按需实现 E2E 测试文件或测试 harness；
- 执行从验收标准映射而来的 API/E2E 场景。
如果 Stage 7 失败要求修改源代码，必须声明重新进入并首先返回 Stage 6。
场景来源（强制）：
- 需求驱动场景（必须覆盖所有关键需求和流程）；
- 设计风险驱动场景（必须覆盖架构或设计选择引入的技术风险）。
验收标准闭环循环（强制）：
- 基于
```
requirements.md
```
  构建并维护明确的 Stage 7 验收标准矩阵（
```
acceptance_criteria_id
```
  -> 映射场景 ID -> 执行状态）；
- 执行开始前，每个范围内验收标准至少映射到一个可执行 API/E2E 场景；
- 任何状态为
```
Unmapped
```
  、
```
Not Run
```
  、
```
Failed
```
  或
```
Blocked
```
  的验收标准都会使 Stage 7 保持开启，并要求重新进入；对于不可执行场景，只有用户明确决定豁免时才能标记为
```
Waived
```
  ；
- 重新运行所需的重新进入链，并返回 Stage 7，直到所有范围内验收标准均为
```
Passed
```
  或已明确
```
Waived
```
  。
对每个场景至少记录：
- ```
scenario_id
```
  ；
- 映射的
```
acceptance_criteria_id
```
  值；
- 映射的
```
requirement_id
```
  和
```
use_case_id
```
  值；
- 来源类型（
```
Requirement
```
  /
```
Design-Risk
```
  ）；
- 测试级别（
```
API
```
  /
```
E2E
```
  ）；
- 预期结果；
- 执行命令或 harness；
- 结果（
```
Passed
```
  /
```
Failed
```
  /
```
Blocked
```
  /
```
N/A
```
  ）。
API 测试深度规则（强制）：当场景级别为
```
API
```
时，必须针对映射的验收标准验证契约级行为，包括必需字段/schema 形态、状态码和错误载荷行为。
跨边界测试规则（强制）：对于 client/server 或多 service 范围，必须包含用于验证跨边界交互行为的 API/E2E 场景（request -> boundary handoff -> downstream effect -> returned state）。
手动测试策略：默认工作流中不包含手动测试。如果用户在工作流之外执行手动验证，则将用户明确的完成或验证消息视为 Stage 10 触发器，用于将 ticket 移至
```
done
```
并启动仓库最终化。
可执行性策略：
- 如果某场景在当前环境中无法执行（缺少密钥/令牌、合作伙伴系统不可用、基础设施限制），在
```
api-e2e-testing.md
```
  和
```
implementation-progress.md
```
  中记录具体的不可执行原因与约束；
- 为每个不可执行的关键场景记录补偿性自动化证据和剩余风险说明；
- 除非用户明确接受对不可执行验收标准的豁免，否则将 Stage 7 标记为
```
Blocked
```
  。
测试反馈升级策略（强制）：
- 将每个失败的 Stage 7 场景准确分类为
```
Local Fix
```
  、
```
Design Impact
```
  、
```
Requirement Gap
```
  或
```
Unclear
```
  中的一种；
- 最终分类前执行调查筛查：
  - 如果问题范围跨范围、涉及未知运行时路径或根因置信度低，则标记为
```
Investigation Required
```
    ，并首先重新打开理解阶段（必须在更新设计/需求产物前更新
```
investigation-notes.md
```
    ）；
  - 如果问题范围明确且根因置信度高，则直接继续分类。
- 仅当职责边界保持完整、无需新增用例或验收标准且无需修改需求/设计时，才允许使用
```
Local Fix
```
  。
- 如果修复在功能上有效，却降低了分层或关注点分离程度，则不是
```
Local Fix
```
  ；应分类为
```
Design Impact
```
  。
- 如果修复仅通过将文件留在错误目录或添加位置不当的新文件才得以工作，则不是
```
Local Fix
```
  ；应分类为
```
Design Impact
```
  。
- 当失败行为暴露出缺少功能/用例，或缺少或存在歧义的验收标准时，分类为
```
Requirement Gap
```
  。
- 当源代码、设计或需求需要更新时，必须在编辑源代码前执行重新进入声明。
- ```
Local Fix
```
  路径：先更新产物，然后修复代码，再重新运行
```
Stage 6 -> Stage 7
```
  。
- ```
Design Impact
```
  路径：
```
Stage 1 -> Stage 3 -> Stage 4 -> Stage 5 -> Stage 6 -> Stage 7
```
  。
- ```
Requirement Gap
```
  路径：
```
Stage 2 -> Stage 3 -> Stage 4 -> Stage 5 -> Stage 6 -> Stage 7
```
  。
- ```
Unclear
```
  /跨范围根因路径：
```
Stage 0 -> Stage 1 -> Stage 2 -> Stage 3 -> Stage 4 -> Stage 5 -> Stage 6 -> Stage 7
```
  。
阶段完成门禁：
- ```
requirements.md
```
  中所有范围内验收标准均映射到 Stage 7 场景；
- 所有可执行的范围内验收标准执行状态均为
```
Passed
```
  ；
- 所有已映射且可执行的 API/E2E 场景均已解决（
```
Passed
```
  ），不存在未解决的失败或阻塞项；
- 如果任何验收标准因环境约束而不可执行，则 Stage 7 保持
```
Blocked
```
  ，直到记录用户明确豁免、约束、补偿性证据和剩余风险。
转换至 Stage 8 前，更新
```
workflow-state.md
```
，记录 Stage 7 门禁结果和转换证据。
使用
```
assets/api-e2e-testing-template.md
```
。
不得仅因
```
api-e2e-testing.md
```
编辑而播报。当
```
workflow-state.md
```
记录 Stage 7 进入、门禁结果及任何重新进入声明或锁定状态变化时进行播报。

8) Run Code Review Gate (Mandatory, Post-Testing)

8）执行代码评审门禁（强制，测试后执行）

Run this stage only after
```
Stage 7
```
API/E2E test gate is
```
Pass
```
.

At Stage 8 entry, update

workflow-state.md

and set

Code Edit Permission = Locked

Create/update
```
tickets/in-progress/<ticket-name>/code-review.md
```
as the canonical code review artifact.
Scope:
- source files and test files,
- include changed files and directly impacted related files when structural risk exists.
Mandatory review checks:
- separation-of-concerns and responsibility boundaries,
- layering quality under shared principles (layering emerges from SoC and coordination needs; reject both missing orchestration extraction and unjustified pass-through layers),
- explicit decoupling quality (low coupling, clear dependency direction, no unjustified cycles),
- architecture/layer boundary consistency with design basis,
- module/file placement and folder ownership consistency with design basis,
- naming-to-responsibility alignment and drift,
- duplication and patch-on-patch complexity smells,
- no backward-compatibility mechanisms and no legacy code retention,
- test quality and test maintainability.
Source file size policy (mandatory):
- measure line counts explicitly per changed source file:
  - effective non-empty line count command:
```
rg -n "\\S" <file-path> | wc -l
```
  - per-file changed-line delta command:
```
git diff --numstat <base-ref>...HEAD -- <file-path>
```
- enforcement baseline uses effective non-empty line count.
- for changed source files with effective non-empty line count
```
<= 500
```
  , run normal review checks.
- hard limit rule: if any changed source file has effective non-empty line count
```
> 500
```
  , default classification is
```
Design Impact
```
  and Stage 8 decision is
```
Fail
```
  .
- for
```
> 500
```
  hard-limit cases, do not continue by default; trigger re-entry with investigation checkpoint first (
```
Stage 1 -> Stage 3 -> Stage 4 -> Stage 5 -> Stage 6 -> Stage 7 -> Stage 8
```
  ).
- no soft middle band (
```
501-700
```
  ) and no default exception path in this workflow.
- delta gate (mandatory): if a single changed source file has
```
> 220
```
  changed lines in the current diff, record a design-impact assessment even when file size is
```
<= 500
```
  .
Gate decision:
- ```
Pass
```
  : continue to
```
Stage 9
```
  only when all mandatory review checks (including
```
<=500
```
  hard-limit + required
```
>220
```
  delta-gate assessments + shared-principles/layering + decoupling + module/file placement + no-backward-compat/no-legacy checks) are
```
Pass
```
  .
- ```
Fail
```
  : apply re-entry declaration and follow re-entry mapping before any source code edits.
Treat wrong-location files as review failures when the path obscures ownership (for example, platform-specific code outside its platform folder without explicit shared-boundary rationale).
If code review requires source changes, rerun
```
Stage 6 -> Stage 7 -> Stage 8
```
.
Use
```
assets/code-review-template.md
```
.
Do not speak for
```
code-review.md
```
edits alone. Announce when
```
workflow-state.md
```
records Stage 8 entry, gate result, and any re-entry declaration.

仅在 Stage 7 API/E2E 测试门禁为
```
Pass
```
后执行此阶段。

进入 Stage 8 时，更新

workflow-state.md

并设置

Code Edit Permission = Locked

。

创建或更新
```
tickets/in-progress/<ticket-name>/code-review.md
```
作为规范的代码评审产物。
范围：
- 源文件与测试文件；
- 当存在结构风险时，包括变更文件及直接受影响的相关文件。
强制评审检查：
- 关注点分离与职责边界；
- 共享原则下的分层质量（分层从 SoC 与协调需求中涌现；既拒绝缺少 orchestration 提取，也拒绝无合理依据的透传层）；
- 明确的解耦质量（低耦合、清晰依赖方向、无不合理循环依赖）；
- 架构/层边界与设计依据的一致性；
- 模块/文件位置和目录所有权与设计依据的一致性；
- 命名与职责的一致性及命名漂移；
- 重复代码和层层打补丁的复杂度异味；
- 不存在向后兼容机制和遗留代码保留；
- 测试质量和测试可维护性。
源文件大小策略（强制）：
- 明确按每个变更源文件测量行数：
- 有效非空行数命令：
```
rg -n "\\S" <file-path> | wc -l
```
- 单文件变更行增量命令：
```
git diff --numstat <base-ref>...HEAD -- <file-path>
```
- 执行基线使用有效非空行数。
- 对有效非空行数
```
<= 500
```
  的变更源文件执行常规评审检查。
- 硬限制规则：如果任何变更源文件的有效非空行数
```
> 500
```
  ，默认分类为
```
Design Impact
```
  ，且 Stage 8 决策为
```
Fail
```
  。
- 对于
```
> 500
```
  的硬限制场景，不得默认继续；必须首先触发包含调查检查点的重新进入（
```
Stage 1 -> Stage 3 -> Stage 4 -> Stage 5 -> Stage 6 -> Stage 7 -> Stage 8
```
  ）。
- 此工作流不存在
```
501-700
```
  的软性中间区间，也不存在默认例外路径。
- 增量门禁（强制）：如果单个变更源文件在当前 diff 中的变更行数
```
> 220
```
  ，即使文件大小
```
<= 500
```
  ，也必须记录设计影响评估。
门禁决策：
- ```
Pass
```
  ：仅当所有强制评审检查（包括
```
<=500
```
  硬限制、必需的
```
>220
```
  增量门禁评估、共享原则/分层、解耦、模块/文件位置以及无向后兼容/无遗留检查）均为
```
Pass
```
  时，才可继续进入
```
Stage 9
```
  。
- ```
Fail
```
  ：在编辑任何源代码前，执行重新进入声明并遵循重新进入映射。
当文件位置掩盖所有权时，将位置不当的文件视为评审失败，例如平台特定代码位于其平台目录之外，且未提供明确的共享边界理由。
如果代码评审要求修改源代码，则重新运行
```
Stage 6 -> Stage 7 -> Stage 8
```
。
使用
```
assets/code-review-template.md
```
。
不得仅因
```
code-review.md
```
编辑而播报。当
```
workflow-state.md
```
记录 Stage 8 进入、门禁结果及任何重新进入声明时进行播报。

9) Synchronize Project Documentation (Mandatory Post-Testing + Review)

9）同步项目文档（强制，测试与评审后执行）

After Stage 7 API/E2E testing and Stage 8 code review are complete, update project documentation under the project
```
docs/
```
folder (and other canonical architecture docs such as
```
ARCHITECTURE.md
```
when impacted) so docs reflect the latest codebase behavior.
Treat
```
docs/
```
as the long-lived canonical source of truth for the current codebase.
Treat ticket artifacts under
```
tickets/
```
as task-local, time-bound records; they are not the long-term source of truth.
If relevant docs do not exist yet, create new docs in
```
docs/
```
with clear natural names that match current functionality.
If relevant docs already exist, update them in place instead of creating duplicate overlapping docs.
Update docs for:
- new modules/files/APIs,
- changed runtime flows,
- renamed/moved/removed components,
- updated operational or testing procedures when behavior changed.
If there is no docs impact, record an explicit "No docs impact" decision with rationale in
```
implementation-progress.md
```
.
Docs synchronization is complete only when docs content aligns with the final implemented behavior.
After docs synchronization result is recorded (
```
Updated
```
/
```
No impact
```
), announce only with the persisted
```
workflow-state.md
```
transition/gate update.

Stage 7 API/E2E 测试和 Stage 8 代码评审完成后，更新项目
```
docs/
```
目录下的项目文档；如果受到影响，同时更新其他规范架构文档，例如
```
ARCHITECTURE.md
```
，使文档反映最新的代码库行为。
将
```
docs/
```
视为当前代码库的长期规范事实来源。
将
```
tickets/
```
下的 ticket 产物视为任务局部、具有时限的记录，而不是长期事实来源。
如果相关文档尚不存在，则在
```
docs/
```
中使用清晰、自然且与当前功能匹配的名称创建新文档。
如果相关文档已存在，则原地更新，而不是创建重复或重叠的文档。
针对以下内容更新文档：
- 新模块、文件或 API；
- 变更后的运行时流程；
- 重命名、移动或删除的组件；
- 行为发生变化后需要更新的操作或测试流程。
如果不存在文档影响，在
```
implementation-progress.md
```
中记录明确的「No docs impact」决策及理由。
仅当文档内容与最终实现行为一致时，文档同步才算完成。
记录文档同步结果（
```
Updated
```
/
```
No impact
```
）后，仅可在持久化的
```
workflow-state.md
```
转换或门禁更新中进行播报。

10) Final Handoff

10）最终交接

Complete handoff only after implementation execution, Stage 7 API/E2E testing, Stage 8 code review, and docs synchronization are complete.
Handoff summary must include:
- delivered scope vs planned scope,
- verification summary (unit/integration plus API/E2E testing, acceptance-criteria closure status, and for infeasible criteria documented constraints + compensating automated evidence + explicit user waiver reference),
- docs files updated (or explicit no-impact rationale),
- release-note status (
```
created
```
  with artifact path, or explicit
```
not required
```
  rationale).
When release notes are required, create/update
```
release-notes.md
```
in the ticket folder before waiting for user verification.
Release-note content rules (mandatory when release notes are required):
- use short user-facing functional notes only,
- do not include internal refactors, dependency bumps, tests, docs-only changes, or low-level implementation detail,
- target
```
3
```
  to
```
7
```
  bullets total across all sections,
- use the template in
```
assets/release-notes-template.md
```
  ,
- default sections are
```
## What's New
```
  ,
```
## Improvements
```
  , and
```
## Fixes
```
  ,
- omit empty sections instead of writing filler content,
- do not include upgrade steps unless the user explicitly asks for them.
After the handoff summary is written, keep Stage 10 open until the user explicitly confirms completion/verification (for example after manual testing). Before that user signal, do not move the ticket to
```
done
```
, commit, push, merge, or release.
After the explicit user completion/verification signal, move the ticket folder to
```
tickets/done/<ticket-name>/
```
first so the archived ticket path is included in the final committed state.
If the project is a git repository, repository finalization is mandatory after that move and must run in this order before Stage 10 is marked complete:
- commit all in-scope changes on the ticket branch/worktree, including the moved ticket files,
- push the ticket branch to remote,
- update the latest personal branch from remote before merging,
- merge the ticket branch into the updated personal branch,
- push the updated personal branch to remote,
- use the release script to release a new version.
Resolve the latest personal branch from repo context or explicit user instruction. If the branch cannot be identified confidently, stop and ask once before merge/release instead of guessing.
If moving the ticket to
```
done
```
or any repository-finalization step fails (commit/push/merge conflict/remote rejection/release-script failure), record the blocker in
```
workflow-state.md
```
, keep Stage 10 open, and resume only after the blocker is resolved.
Ticket state transition:
- keep ticket under
```
tickets/in-progress/<ticket-name>/
```
  by default after handoff and while waiting for explicit user completion/verification,
- on explicit user confirmation that the ticket is finished/verified (or explicit user move instruction), first move the ticket to
```
tickets/done/<ticket-name>/
```
  , then run repository finalization if applicable.
- if the user reopens a completed ticket, move it back to
```
tickets/in-progress/<ticket-name>/
```
  before any additional artifact updates.
Speak final handoff completion only after all required artifacts/docs outputs are written and the final
```
workflow-state.md
```
transition/gate state is persisted.

仅当实现执行、Stage 7 API/E2E 测试、Stage 8 代码评审和文档同步全部完成后，才可完成交接。
交接摘要必须包括：
- 已交付范围与计划范围；
- 验证摘要（单元/集成测试以及 API/E2E 测试、验收标准闭环状态；对于不可执行的标准，注明约束、补偿性自动化证据和用户明确豁免引用）；
- 已更新的文档文件，或明确的无影响理由；
- Release notes 状态（
```
created
```
  并附产物路径，或明确的
```
not required
```
  理由）。
需要 release notes 时，在等待用户验证前，在 ticket 目录中创建或更新
```
release-notes.md
```
。
Release notes 内容规则（需要时强制）：
- 仅使用简短、面向用户的功能说明；
- 不得包含内部重构、依赖升级、测试、纯文档变更或低层实现细节；
- 所有章节合计使用
```
3
```
  至
```
7
```
  个条目；
- 使用
```
assets/release-notes-template.md
```
  ；
- 默认章节为
```
## What's New
```
  、
```
## Improvements
```
  和
```
## Fixes
```
  ；
- 省略空章节，而不是填充无意义内容；
- 除非用户明确要求，否则不得包含升级步骤。
交接摘要写完后，保持 Stage 10 开启，直到用户明确确认完成或验证（例如在手动测试后）。在收到该用户信号前，不得将 ticket 移至
```
done
```
，也不得提交、推送、合并或发布。
收到用户明确的完成或验证信号后，首先将 ticket 目录移至
```
tickets/done/<ticket-name>/
```
，确保最终提交后的状态包含归档后的 ticket 路径。
如果项目是 git 仓库，收到该信号后必须执行仓库最终化，并按以下顺序操作，然后才能将 Stage 10 标记为完成：
- 在 ticket 分支/worktree 上提交所有范围内变更，包括移动后的 ticket 文件；
- 推送 ticket 分支到远程；
- 合并前先从远程更新最新的个人分支；
- 将 ticket 分支合并至更新后的个人分支；
- 推送更新后的个人分支；
- 使用发布脚本发布新版本。
根据仓库上下文或用户明确指示解析最新个人分支。如果无法高置信度识别分支，则停止操作，在合并或发布前询问一次，而不是进行猜测。
如果移动 ticket 至
```
done
```
或任何仓库最终化步骤失败（提交、推送、合并冲突、远程拒绝、发布脚本失败），在
```
workflow-state.md
```
中记录阻塞项，保持 Stage 10 开启，仅在阻塞项解决后继续。
Ticket 状态转换：
- 交接后及等待用户明确完成或验证期间，默认将 ticket 保留在
```
tickets/in-progress/<ticket-name>/
```
  ；
- 用户明确确认 ticket 已完成或已验证（或明确要求移动）时，先将 ticket 移至
```
tickets/done/<ticket-name>/
```
  ，然后在适用时执行仓库最终化。
- 如果用户重新打开已完成的 ticket，必须先将其移回
```
tickets/in-progress/<ticket-name>/
```
  ，然后再进行任何额外产物更新。
仅当所有必要产物和文档输出均已写入，且最终
```
workflow-state.md
```
转换/门禁状态已持久化后，才可播报最终交接完成。

Output Defaults

输出默认值

If the user does not specify file paths, write to a project-local ticket folder in stage order: These defaults list file-producing stages; gating and handoff rules still follow the full workflow above.

Stage 0 (bootstrap + draft requirement):

create/use
```
tickets/in-progress/<ticket-name>/
```
if git repo, create/switch ticket worktree/branch

create/update

tickets/in-progress/<ticket-name>/workflow-state.md

(

Current Stage = 0

Code Edit Permission = Locked

)

tickets/in-progress/<ticket-name>/requirements.md

(

Draft

)

Stage 1 (investigation + understanding + triage):

update

tickets/in-progress/<ticket-name>/workflow-state.md

transition (

0 -> 1

)

tickets/in-progress/<ticket-name>/investigation-notes.md

Stage 2 (requirements refinement to

Design-ready

update

tickets/in-progress/<ticket-name>/workflow-state.md

transition (

1 -> 2

)

update

tickets/in-progress/<ticket-name>/requirements.md

in place

Stage 3 (design basis):

update

tickets/in-progress/<ticket-name>/workflow-state.md

transition (

2 -> 3

)

```
Small
```
: start/refine
```
tickets/in-progress/<ticket-name>/implementation-plan.md
```
(solution sketch section only for design basis).

Medium/Large

: create/refine

tickets/in-progress/<ticket-name>/proposed-design.md

Stage 4 (runtime modeling):

update

tickets/in-progress/<ticket-name>/workflow-state.md

transition (

3 -> 4

)

tickets/in-progress/<ticket-name>/future-state-runtime-call-stack.md

Stage 5 (review gate, iterative):

update

tickets/in-progress/<ticket-name>/workflow-state.md

transition (

4 -> 5

)

tickets/in-progress/<ticket-name>/future-state-runtime-call-stack-review.md

Stage 6 (only after gate
```
Go Confirmed
```
):
- update
```
tickets/in-progress/<ticket-name>/workflow-state.md
```
  (
```
Current Stage = 6
```
  ,
```
Code Edit Permission = Unlocked
```
  only when pre-edit checklist is
```
Pass
```
  )
- finalize/update
```
tickets/in-progress/<ticket-name>/implementation-plan.md
```
- ```
tickets/in-progress/<ticket-name>/implementation-progress.md
```
- execute source implementation plus required unit/integration verification and log progress in real time
- close Stage 6 only when no backward-compatibility/legacy-retention paths remain in scope, decoupling boundaries remain valid, and touched files have correct module/file placement

Stage 7 (API/E2E test implementation + API/E2E test gate):

update

tickets/in-progress/<ticket-name>/workflow-state.md

(

Current Stage = 7

Code Edit Permission = Unlocked

)

create/update

tickets/in-progress/<ticket-name>/api-e2e-testing.md

maintain acceptance-criteria matrix (
```
acceptance_criteria_id
```
-> scenario coverage -> pass status)
record scenario execution results and any escalation decisions in
```
tickets/in-progress/<ticket-name>/implementation-progress.md
```

Stage 8 (code review gate, only after

Stage 7 = Pass

update

tickets/in-progress/<ticket-name>/workflow-state.md

(

Current Stage = 8

Code Edit Permission = Locked

)

create/update

tickets/in-progress/<ticket-name>/code-review.md

record gate result (
```
Pass
```
/
```
Fail
```
) and any re-entry declaration before
```
Stage 9
```

Stage 9 (post-testing documentation sync):
- update
```
tickets/in-progress/<ticket-name>/workflow-state.md
```
  transition (
```
8 -> 9
```
  )
- update existing impacted docs in place (for example
```
docs/**/*.md
```
  ,
```
ARCHITECTURE.md
```
  )
- create missing relevant docs in
```
docs/
```
  when no existing doc covers the implemented functionality
- record docs sync result in
```
tickets/in-progress/<ticket-name>/implementation-progress.md
```
  (
```
Updated
```
  /
```
No impact
```
  + rationale)
Stage 10 (final handoff + wait for user verification + move ticket to done + repository finalization):
- update
```
tickets/in-progress/<ticket-name>/workflow-state.md
```
  transition (
```
9 -> 10
```
  ) and final state record
- persist the handoff summary and wait for explicit user completion/verification instruction
- when the release is user-facing or publishes a GitHub Release body, create/update
```
tickets/in-progress/<ticket-name>/release-notes.md
```
  using
```
assets/release-notes-template.md
```
  ; otherwise record explicit no-note rationale in the handoff summary
- on explicit user completion/verification instruction, first move the ticket folder to
```
tickets/done/<ticket-name>/
```
- if git repo and the user explicitly confirms completion/verification, commit all in-scope changes on the ticket branch/worktree, including the moved ticket files
- if git repo and the user explicitly confirms completion/verification, push the ticket branch to remote
- if git repo and the user explicitly confirms completion/verification, update the latest personal branch from remote, merge the ticket branch into it, and push the updated personal branch
- if git repo and the user explicitly confirms completion/verification, use the release script to release a new version and feed it the archived ticket release-notes artifact (typically
```
tickets/done/<ticket-name>/release-notes.md
```
  ) when release notes are required
- keep ticket in
```
tickets/in-progress/<ticket-name>/
```
  unless user explicitly confirms completion/verification or asks to move it
- if user reopens later, move it back to
```
tickets/in-progress/<ticket-name>/
```
  before new updates

如果用户未指定文件路径，则按阶段顺序写入项目本地的 ticket 目录：以下默认值仅列出会生成文件的阶段；门禁与交接规则仍遵循上述完整工作流。

Stage 0（初始化 + 需求草稿）：

创建或使用
```
tickets/in-progress/<ticket-name>/
```
如果是 git 仓库，创建或切换 ticket worktree/分支

创建或更新

tickets/in-progress/<ticket-name>/workflow-state.md

（

Current Stage = 0

、

Code Edit Permission = Locked

）

创建或更新

tickets/in-progress/<ticket-name>/requirements.md

（

Draft

）

Stage 1（调查 + 理解 + 分流）：

更新

tickets/in-progress/<ticket-name>/workflow-state.md

的转换（

0 -> 1

）

创建或更新

tickets/in-progress/<ticket-name>/investigation-notes.md

Stage 2（需求细化为

Design-ready

）：

更新

tickets/in-progress/<ticket-name>/workflow-state.md

的转换（

1 -> 2

）

原地更新

tickets/in-progress/<ticket-name>/requirements.md

Stage 3（设计依据）：

更新

tickets/in-progress/<ticket-name>/workflow-state.md

的转换（

2 -> 3

）

```
Small
```
：开始或细化
```
tickets/in-progress/<ticket-name>/implementation-plan.md
```
（作为设计依据时仅包含方案概要部分）。

Medium/Large

：创建或细化

tickets/in-progress/<ticket-name>/proposed-design.md

。

Stage 4（运行时建模）：

更新

tickets/in-progress/<ticket-name>/workflow-state.md

的转换（

3 -> 4

）

创建或更新

tickets/in-progress/<ticket-name>/future-state-runtime-call-stack.md

Stage 5（评审门禁，迭代执行）：

更新

tickets/in-progress/<ticket-name>/workflow-state.md

的转换（

4 -> 5

）

创建或更新

tickets/in-progress/<ticket-name>/future-state-runtime-call-stack-review.md

Stage 6（仅在门禁
```
Go Confirmed
```
后执行）：
- 更新
```
tickets/in-progress/<ticket-name>/workflow-state.md
```
  （
```
Current Stage = 6
```
  ，仅当编辑前检查清单为
```
Pass
```
  时设置
```
Code Edit Permission = Unlocked
```
  ）
- 最终确定或更新
```
tickets/in-progress/<ticket-name>/implementation-plan.md
```
- 创建或更新
```
tickets/in-progress/<ticket-name>/implementation-progress.md
```
- 执行源代码实现及必要的单元/集成测试验证，并实时记录进度
- 仅当范围内不存在向后兼容或遗留保留路径、解耦边界保持有效且变更文件位于正确的模块/文件位置时，才关闭 Stage 6

Stage 7（API/E2E 测试实现 + API/E2E 测试门禁）：

更新

tickets/in-progress/<ticket-name>/workflow-state.md

（

Current Stage = 7

、

Code Edit Permission = Unlocked

）

创建或更新

tickets/in-progress/<ticket-name>/api-e2e-testing.md

维护验收标准矩阵（
```
acceptance_criteria_id
```
-> 场景覆盖 -> 通过状态）

在

tickets/in-progress/<ticket-name>/implementation-progress.md

中记录场景执行结果和升级决策

Stage 8（代码评审门禁，仅在

Stage 7 = Pass

后执行）：

更新

tickets/in-progress/<ticket-name>/workflow-state.md

（

Current Stage = 8

、

Code Edit Permission = Locked

）

创建或更新

tickets/in-progress/<ticket-name>/code-review.md

在进入 Stage 9 前记录门禁结果（
```
Pass
```
/
```
Fail
```
）及任何重新进入声明

Stage 9（测试后文档同步）：
- 更新
```
tickets/in-progress/<ticket-name>/workflow-state.md
```
  的转换（
```
8 -> 9
```
  ）
- 原地更新受影响的现有文档，例如
```
docs/**/*.md
```
  、
```
ARCHITECTURE.md
```
- 当没有现有文档覆盖已实现功能时，在
```
docs/
```
  中创建缺失的相关文档
- 在
```
tickets/in-progress/<ticket-name>/implementation-progress.md
```
  中记录文档同步结果（
```
Updated
```
  /
```
No impact
```
  + 理由）
Stage 10（最终交接 + 等待用户验证 + 移动 ticket 至 done + 仓库最终化）：
- 更新
```
tickets/in-progress/<ticket-name>/workflow-state.md
```
  的转换（
```
9 -> 10
```
  ）和最终状态记录
- 持久化交接摘要，并等待用户明确的完成或验证指示
- 当版本面向用户或需要发布 GitHub Release 正文时，使用
```
assets/release-notes-template.md
```
  创建或更新
```
tickets/in-progress/<ticket-name>/release-notes.md
```
  ；否则在交接摘要中记录明确的无 release notes 理由
- 收到用户明确的完成或验证指示后，首先将 ticket 目录移至
```
tickets/done/<ticket-name>/
```
- 如果是 git 仓库且用户明确确认完成或验证，在 ticket 分支/worktree 上提交所有范围内变更，包括移动后的 ticket 文件
- 如果是 git 仓库且用户明确确认完成或验证，推送 ticket 分支到远程
- 如果是 git 仓库且用户明确确认完成或验证，从远程更新最新的个人分支，将 ticket 分支合并至该分支，并推送更新后的个人分支
- 如果是 git 仓库且用户明确确认完成或验证，使用发布脚本发布新版本；当需要 release notes 时，将已归档的 ticket release-notes 产物传入该流程（通常为
```
tickets/done/<ticket-name>/release-notes.md
```
  ）
- 除非用户明确确认完成或验证或要求移动，否则将 ticket 保留在
```
tickets/in-progress/<ticket-name>/
```
- 如果用户后续重新打开，则在更新前将其移回
```
tickets/in-progress/<ticket-name>/
```

Templates

模板

```
assets/proposed-design-template.md
```

assets/future-state-runtime-call-stack-template.md

assets/future-state-runtime-call-stack-review-template.md

```
assets/implementation-plan-template.md
```

assets/implementation-progress-template.md

```
assets/code-review-template.md
```
```
assets/api-e2e-testing-template.md
```
```
assets/workflow-state-template.md
```
```
assets/release-notes-template.md
```

```
assets/proposed-design-template.md
```

assets/future-state-runtime-call-stack-template.md

assets/future-state-runtime-call-stack-review-template.md

```
assets/implementation-plan-template.md
```

assets/implementation-progress-template.md

```
assets/code-review-template.md
```
```
assets/api-e2e-testing-template.md
```
```
assets/workflow-state-template.md
```
```
assets/release-notes-template.md
```