apcp-web-api-self-review

apcp-web-api Self Review

Purpose

This is the dedicated backend self-review stage. It owns workflow self-review, self-review.md, and the final backend gate/next decision before plugin work, not package-level entry routing and not standalone Java compliance fallback. It exists to separate implementation from final backend release gating.

This stage reads:

• tasks/<task-name>/requirement.md
• tasks/<task-name>/feasibility.md
• tasks/<task-name>/plan.md
• implemented backend code in apcp-web-api

This stage writes:

• backend fixes that are required to resolve review findings
• tasks/<task-name>/self-review.md

If self-review.md already exists from a previous failed review, reopen and replace it for the current review pass. It does not modify requirement.md or feasibility.md. It may update plan.md only to synchronize the runtime visibility sections ## 当前状态, ## 执行计划, and ## 实施任务, or when the review finds that an upstream stage really must be reopened.

Preconditions

Before starting, confirm all of the following:

• requirement.md exists and has gate: requirement-confirmed
• feasibility.md exists and has gate: ready-for-plan
• plan.md exists and has gate: ready-for-implementation
• the implementation stage has already reached its own completion rule and explicitly handed off to review
• backend implementation has already been completed against plan.md

This review handoff is a stage transition condition. It is not a separate task document written before self-review.md exists.

If any precondition fails, refuse this stage and return to the only legal upstream stage.

Refusal Rule

If any precondition fails, refuse this stage and return to the only legal upstream stage. Do not use this stage to bypass unfinished implementation or upstream gate handling.

Document Contract

self-review.md must contain at least:

• ## 范围核对
• ## 实现符合度
• ## 偏差说明
• ## 剩余问题
• ## 修复记录
• ## 阶段状态

The ## 阶段状态 block must contain:

• gate: ready-for-plugin or gate: review-failed
• next: apcp-plugin-implementation or next: apcp-web-api-implementation or next: apcp-web-api-plan

CodeLaw Integration

codelaw-self-review is the adjacent Java review and compliance helper skill. It may be invoked from this workflow stage to perform the detailed Java review, but it does not own self-review.md, plugin unlock, or upstream recovery routing.

1. First complete this stage's existing precondition checks.
2. Read requirement.md, feasibility.md, plan.md, and the implemented backend code.
3. Immediately invoke codelaw-self-review.
4. If review findings can be corrected within backend implementation scope, repair them in this stage before finalizing the review result.
5. Use the final review result and any repairs performed in this stage to write self-review.md, including:
   • ## 实现符合度
   • ## 偏差说明
   • ## 剩余问题
   • ## 修复记录
   • ## 阶段状态
6. If unresolved review findings still remain after reasonable in-stage repair, write gate: review-failed and return next to apcp-web-api-implementation or apcp-web-api-plan.
7. If the CodeLaw review passes and the whole contract also passes after any needed repairs, write gate: ready-for-plugin and next: apcp-plugin-implementation.

This stage is review-and-fix. Do not duplicate detailed CodeLaw MCP procedures here. Do not drift into unrelated feature work while repairing review findings.

Review Scope

Review against the whole contract, not only spot code. Check:

• whether implemented backend behavior still matches requirement.md
• whether implementation still respects the feasibility conclusion and known limits
• whether implementation follows plan.md without silent drift
• whether naming, structure, ownership, validation, and shared contracts remain internally consistent
• whether any missing or incorrect part still blocks plugin verification
• whether implementation truly reached review handoff instead of arriving early from an unfinished implementation stage
• whether plan.md ## 当前状态, ## 执行计划, and ## 实施任务 still reflect the real workflow state and need final closure updates

Decision Rules

Pass

Use this only when backend work is stable enough for plugin verification:

• gate: ready-for-plugin
• next: apcp-plugin-implementation

ready-for-plugin means the plugin stage is now legally unlocked. It does not mean this stage may enter plugin work automatically. User confirmation is still required before apcp-plugin-implementation begins.

Fail

If the implementation no longer matches the plan, or the plan itself is no longer sufficient, first repair what can be repaired directly in this stage. Only when unresolved issues still remain after that repair pass:

• use gate: review-failed
• send next back to the only correct recovery stage:
  • apcp-web-api-implementation when more implementation work is still required
  • apcp-web-api-plan when the design itself must change

Within this stage's own review result, review-failed normally means unresolved review findings still remain after repair. At the workflow level, the same gate may also be used later as a forced invalidation state when backend changes resume after a previously passed review; that invalidation path must say explicitly that the old pass became stale, not that this stage just found a new unresolved review defect. Do not allow plugin work after a failed review.

Completion Rule

This stage completes only when self-review.md contains an explicit ## 阶段状态 block with one of these outcomes:

• gate: ready-for-plugin with next: apcp-plugin-implementation
• gate: review-failed with next: apcp-web-api-implementation or next: apcp-web-api-plan

Before finalizing either result, also close the visibility state in plan.md so its ## 当前状态, ## 执行计划, and ## 实施任务 reflect the real review outcome or rollback target.

Then apply the stage-specific transition rule:

• if the result is ready-for-plugin, stop and wait for user confirmation before entering apcp-plugin-implementation
• if the result is review-failed, continue automatically into the upstream stage named by next

The review-failed branch auto-enters only the immediate upstream recovery stage named by next. After that recovery pass finishes, routing resumes from the newly completed upstream state, and implementation may later hand off into this stage again. This stage may then replace the previous self-review.md. Record both findings and fixes in self-review.md. The document decides the next legal stage, and only the review-failed branch may auto-enter it immediately.

Do Not Do

• do not rewrite plan.md inside self-review.md
• do not treat implementation-local spot checks as the final review
• do not skip writing self-review.md
• do not allow plugin entry without gate: ready-for-plugin
• do not use review findings as an excuse for unrelated refactoring or feature expansion