git:20260831.e1e1453 to git:20260906.b53a8e9

50 added, 54 removed. Audit A to A.

---

name: add-execute

description: Pha 4–5 ADD — thực thi task theo Architecture Profile, governance và verification command đã approved

user-invocable: true

---

# ADD Phase 4–5 — Agentic Execution và Validation (`/add-execute`)

**Output language:** All output mirrors the language of the invoking prompt. Vietnamese prompt → Vietnamese output; English prompt → English output. Canonical tokens (`PENDING HUMAN REVIEW`, `APPROVED`, `SHADOW PLAN`, `BLOCKED`), rule codes, `@ears` references, file paths, and CLI commands are language-invariant.

Dùng để thực thi task trong `.sdd/features/{feature-slug}/TASKS.md`, theo **Fix the Spec, not the Code**, `CONSTITUTION.md` và Architecture Profile.

## Tham số

- `--feature=<feature-slug>`: Feature identifier.

- - `--task=<task-id>`: Tùy chọn; task cụ thể, ví dụ `T001`.

+ - `--task=<task-id>`: Tùy chọn; task cụ thể.

+ - `--dispatch-record=<reference>`: Required reference to a valid Dispatch Record created by `/sdd-dispatch`; with `orchestrated`, it also binds the immutable worker packet.

+ - `--dispatch-grant=<grant-id>`: Required ID của task execution grant trong Dispatch Record.

+ - `--dispatch-consumer=<consumer-ref>`: Required opaque consumer reference allocated by `/sdd-dispatch` for the matching grant.

- `--strict-checkpoint`: Tùy chọn; project opt-in yêu cầu Human checkpoint trước mọi task. Không phải baseline.

+ ## Execution resolver (BLOCKING)

+ Đọc `.sdd/shared_context.md` trước execution. Canonical settings chỉ hợp lệ khi mỗi `# Project Ownership: solo|team` và `# Agent Execution: direct|orchestrated` tồn tại đúng một lần. Thiếu, trùng hoặc malformed canonical header là `BLOCKED`. Khi cả hai canonical header vắng mặt, legacy path chỉ hợp lệ với đúng một nguồn: đúng một `# Collaboration Mode: solo|team` hoặc đúng một `--team-size=solo|team`; header legacy thiếu, trùng hoặc malformed; alias lặp, malformed; hoặc cả header và alias cùng tồn tại là `BLOCKED`. `--team-size` không được kết hợp với canonical axis flag. Không fallback legacy khi canonical state invalid.

+ `/add-execute` không phải route discovery hoặc preflight. Mọi invocation phải có `--dispatch-record=<reference>`, `--dispatch-grant=<grant-id>` và `--dispatch-consumer=<consumer-ref>` do `/sdd-dispatch` tạo sau preflight. Thiếu hoặc không xác minh được record/grant/consumer là `BLOCKED`. Resolve record chỉ từ `TASKS.md` của `--feature`; `Feature` trong record phải bằng `--feature`. Grant phải xuất hiện đúng một lần, có task ID bằng `--task`, route bằng effective `Agent execution`, opaque consumer reference bằng `--dispatch-consumer`, và immutable boundary/frozen contract/profile/exact command/checkpoint khớp task approved. Markdown grant state không atomic; nó là cooperative evidence và không host-enforce replay prevention khi runtime enforcement là `UNVERIFIED`. Consumer reference là preallocated cooperative binding, không chứng minh host đã ngăn session khác replay reference. Nếu record có host-controlled execution claim, claim phải bound đúng feature/task/grant/route/consumer; stale hoặc mismatch là `BLOCKED`. Chỉ `task grant state=DISPATCHED` cùng `consumption state=UNCONSUMED` được bắt đầu. Với cả `direct` và `orchestrated`, trước Shadow Plan, command, edit hoặc action khác, persist transition matching grant sang `RUNNING`/`CONSUMED`, ghi consumer và consumption evidence. Grant consumed, non-`DISPATCHED`, missing, mismatched consumer, cross-feature, cross-task, cross-record hoặc replay là `BLOCKED`; `/add-execute` không allocate/reset grant hoặc authorize retry.

+ Record phải có `Governance resolution: canonical | legacy-header | legacy-alias` và `invocation axis overrides`. Record `canonical` không được chứa `legacy-alias` hoặc `--team-size`; có một canonical header cùng alias là `BLOCKED`. Với `canonical`, re-resolve canonical shared-context pair rồi áp dụng đúng override đã record. Với `legacy-header`, canonical headers phải vắng mặt và đúng một header legacy hợp lệ phải map về pair trong record. Với `legacy-alias`, canonical và legacy headers phải vắng mặt; alias chỉ được tin cậy từ immutable Dispatch Record. Mọi source/override invalid, override không hợp lệ hoặc effective `Project ownership`/`Agent execution` không bằng record là `BLOCKED`. Không nhận override mới trong `/add-execute`.

+ - `direct`: current Agent thực thi sau khi `/sdd-dispatch --agent-execution=direct` đã tạo Dispatch Record và matching unconsumed grant. Record phải có effective `Agent execution: direct` và preallocated consumer reference bằng `--dispatch-consumer`; không cần worker packet. Action Record phải echo consumed grant, consumer reference và consumption evidence.

+ - `orchestrated`: `/add-execute` chỉ chạy trong worker packet được `/sdd-dispatch` tạo. Record phải có effective `Agent execution: orchestrated`; `DISPATCH ID`, `FEATURE`, `TASK ID`, `DISPATCH GRANT ID`, `GRANT ATTEMPT`, `GRANT STATE: DISPATCHED`, `CONSUMPTION STATE: UNCONSUMED`, `CONSUMER`, task/boundary/frozen contract/profile/exact command/checkpoint phải khớp packet, `--dispatch-consumer` và record. Thiếu hoặc mismatch là `BLOCKED`.

## Shared methodology contract

- Đọc [AI Review Protocol](../_shared/ai-review-protocol.md) trước execution. Mọi task cần Shadow Plan và Action Record. Human checkpoint persisted chỉ bắt buộc trước material state change: shared/public contract; persistence schema/business-data mutation; permission, security, dependency/runtime configuration; external/irreversible side effect. `--strict-checkpoint` tăng gate cho mọi task nhưng không thay baseline mặc định.

+ Đọc [AI Review Protocol](../_shared/ai-review-protocol.md) trước execution. Mọi task cần Shadow Plan và Action Record. Human checkpoint persisted chỉ bắt buộc trước material state change. `--strict-checkpoint` tăng gate cho mọi task nhưng không thay baseline mặc định.

## Architecture Profile gate (BLOCKING)

- 1. Đọc `AGENTS.md`, `CONSTITUTION.md`, `CLAUDE.md`, Architecture Profile, constraints, `CONTEXT.md`, `SPEC.md`, `PLAN.md`, `TASKS.md`, shared contract record và review block liên quan.

+ 1. Đọc `AGENTS.md`, `CONSTITUTION.md`, `CLAUDE.md`, Architecture Profile, constraints, feature artifacts, shared contract record và review block liên quan.

2. Xác minh profile binding bằng manifest/config/source evidence; mọi prerequisite review phải `APPROVED` cùng decision, reviewer và timestamp.

3. Chỉ tạo/sửa adapter, package usage, migration, config, command và test đã có trong profile/Plan/Tasks approved.

- 4. Task cần HTTP, persistence, validation, cache, messaging hoặc test/build/lint command chưa selected/evidenced thì dừng, lưu `PENDING HUMAN REVIEW`; không sinh adapter code hoặc chạy placeholder command.

- 5. Profile/evidence mâu thuẫn, contract version drift hoặc task lệch Shadow Plan thì dừng, nêu conflict và yêu cầu Human Director quyết định.

+ 4. Task cần binding hoặc test/build/lint command chưa selected/evidenced thì dừng, lưu `PENDING HUMAN REVIEW`; không sinh code hoặc chạy placeholder command.

+ 5. Profile/evidence mâu thuẫn, contract version drift hoặc task lệch Shadow Plan thì dừng.

## Quy trình

### 1. Atomic session và Shadow Plan bắt buộc

- Trong team mode, `/sdd-dispatch` là coordinator; worker chỉ bắt đầu `/add-execute` sau khi validate immutable dispatch packet: dispatch ID, role, task/DoD, exclusive file boundary, frozen contract, profile evidence, exact commands, checkpoint và policy evidence. Packet thiếu, contract drift, boundary mismatch hoặc host-enforcement claim không có observed evidence là `BLOCKED`.

- Mỗi session chỉ load task-scoped context: Intent Packet, locked `REQ-XXX`, applicable Plan/task records, profile binding/exact command, shared contract version và review evidence. Không absorb cleanup hoặc scope ngoài task.

- Trước mỗi task, xuất Shadow Plan:

- ```text

- SHADOW PLAN — Task {T00X}: {Task title}

- INTENT AND DONE

- - WHAT/DoD: {locked Intent Packet and REQ-XXX outcome}

- - Scope/file boundary: {approved paths only}

- ARCHITECTURE PROFILE

- - Version/status: {approved profile version/status}

- - Bindings and evidence: {only relevant approved bindings}

- - Exact commands: {approved test/lint/typecheck/build or N/A reason}

- STATE AND CONTRACT

- - State-change category: {none or category list}

- - Human checkpoint: {required persisted evidence | N/A}

- - Shared contract/version: {record and owner | N/A}

- - Sync-back: {/sdd-trace, /sdd-sync, or N/A}

+ Với `Agent Execution: orchestrated`, `/sdd-dispatch` là coordinator; worker chỉ bắt đầu `/add-execute` sau immutable dispatch packet và matching `DISPATCHED`/`UNCONSUMED` grant hợp lệ. Với cả hai route, `/add-execute` persist consumption của matching grant trước khi thực thi cùng Shadow Plan, Action Record, checkpoint và boundary. Mỗi session chỉ load task-scoped context và không absorb cleanup/scope ngoài task.

- RISKS

- - {risk and mitigation}

- ```

+ Trước mỗi task, xuất Shadow Plan gồm Intent/DoD, scope/file boundary, profile binding/evidence, exact command, state-change/checkpoint, shared contract/version, risks, trace/sync decision và post-code review trigger.

- Nếu task có material state change hoặc `--strict-checkpoint`, dừng trước edit đến khi Human checkpoint persisted `APPROVED`. Read-only/low-risk task vẫn cần Shadow Plan và Action Record, nhưng không cần checkpoint mặc định. Không tự nối test filter/option theo framework khi profile không có feature-scoped command.

+ Nếu task có material state change hoặc `--strict-checkpoint`, dừng trước edit đến khi Human checkpoint persisted `APPROVED`. Read-only/low-risk task vẫn cần Shadow Plan và Action Record.

### 2. Thực thi theo boundary đã approved

- Domain: TypeScript thuần, không external dependency hoặc adapter import.

- Usecase: business workflow và port; mọi business method có `@ears .sdd/features/{slug}/SPEC.md#REQ-XXX`.

- - Interface: chỉ dùng approved transport/validation/authentication adapter; chỉ gọi usecase.

- - Infrastructure: chỉ dùng approved DB/ORM/cache/external adapter; tuân thủ `DATA-01`, `SEC-01`.

- - Shared: error, logging và security utility bám binding approved.

+ - Interface/Infrastructure/Shared: chỉ dùng adapter, config và utility đã approved.

- Dừng và handoff khi scope expansion, blocker, contract drift, material decision mới hoặc requirement/Spec gap xuất hiện. Không tiếp tục bằng cleanup không liên quan hoặc assumed contract change.

+ Dừng và handoff khi scope expansion, blocker, contract drift, material decision mới hoặc requirement/Spec gap xuất hiện.

### 3. Self-check và verification

- [ ] Không hardcode secret (`SEC-01`).

- - [ ] Feature cần access control có identity, authorization ownership và unauthorized behavior khớp Spec (`SEC-02`).

- - [ ] Feature đổi core business data có retention, recovery, authorization, audit và deletion policy khớp Spec; soft-delete chỉ dùng khi binding/review đã xác định (`DATA-01`).

- - [ ] Dependency direction khớp `ARCH-01`; async/reliability behavior khớp `ARCH-02`.

- - [ ] Business method có `@ears`; error contract không leak sensitive detail và HTTP mapping, nếu có, khớp `ENG-02`.

+ - [ ] Access control, data, dependency direction và error contract khớp Spec/constraints.

- [ ] Chỉ chạy exact approved verification command đã nêu trong Task/Shadow Plan hoặc ghi `N/A` với lý do hợp lệ (`ENG-03`).

- Command thiếu, không tồn tại hoặc profile mismatch là blocker. Không thay bằng `npm`, `pnpm`, `yarn` hoặc command suy đoán.

+ Command thiếu, không tồn tại hoặc profile mismatch là blocker. Không thay bằng command suy đoán.

- ### 4. Action Record và sync-back

+ ### 4. Validation route, Action Record và sync-back

- Sau execution, ghi Action Record trong `## Current Handoff State`, execution evidence hoặc review report. Record phải nêu approved scope/file boundary, profile binding/exact command, checkpoint, actions/result, residual blocker và sync-back decision.

+ Sau execution, ghi Action Record trong `## Current Handoff State`, execution evidence hoặc review report. Theo trigger, route delivery là:

- - Chạy hoặc yêu cầu `/sdd-trace --feature=<slug> --diff` khi requirement/code/test evidence thay đổi.

- - Chạy hoặc yêu cầu `/sdd-sync --feature=<slug> --reason="..."` khi shared contract/state thay đổi.

- - Không đánh dấu task complete nếu required checkpoint, verification evidence hoặc sync-back thiếu.

+ 1. Chạy exact approved command của task.

+ 2. Chạy hoặc yêu cầu `/sdd-lint --feature=<slug>` khi Spec/artifact liên quan thay đổi.

+ 3. Chạy hoặc yêu cầu `/sdd-audit --feature=<slug>` khi source hoặc governance thay đổi.

+ 4. Chạy hoặc yêu cầu `/sdd-trace --feature=<slug> --diff` khi requirement, code hoặc tests thay đổi.

+ 5. Chạy hoặc yêu cầu `/sdd-sync --feature=<slug> --reason="..."` khi shared state/contract thay đổi.

+ 6. Chạy `/git-validate --scope=commit --feature=<slug>` trước commit hoặc PR.

- ### 5. Test failure và Spec gap

+ Action Record phải echo task execution grant ID, route, dispatcher-issued consumer reference, observed host-controlled atomic claim reference, consumer/consumption evidence, command/result, validation route, residual blocker, sync-back decision và post-code review reference hoặc `N/A` có lý do. Không đánh dấu task complete nếu required checkpoint, verification evidence, post-code review hoặc sync-back thiếu.

- Nếu test fail do requirement mơ hồ/thiếu edge case:

+ ### 5. Post-code Human review

- 1. Không vá behavior trực tiếp.

- 2. Phân loại failure: implementation defect, Spec gap, profile/configuration gap, hoặc prohibited/high-risk mutation.

- 3. Với Spec gap hoặc profile/configuration gap, dừng, đề xuất `/sdd-update` hoặc Architecture Profile review và chờ Human.

- 4. Chỉ bounded recovery cho implementation defect trong approved task/file scope; không auto-retry mutation thuộc prohibited/high-risk category.

- 5. Khi dispatcher đang điều phối, worker trả Action Record-compatible payload gồm changed paths, exact command/result, requirement coverage, residual blocker và sync-back decision. Dispatcher chỉ retry khi packet immutable không đổi; maximum 5 consecutive failures trước `ESCALATED`.

+ Tạo post-code review tại `.sdd/reviews/post-code-<feature>-<delivery-or-timestamp>.md` và dùng `/sdd-review` khi delivery thay đổi implementation behavior, tests, API/public/shared contract, runtime/dependency/security configuration, persistence schema hoặc business state. Report cần changed boundary, `REQ-XXX` coverage, exact command/result, validation states, residual risk và required Human decision.

+ Docs-only artifact work không cần post-code review chỉ vì thay Markdown. `REVISE`, `REJECTED` hoặc thiếu report required block delivery; Agent không tự complete, commit hoặc push.

+ ### 6. Test failure và Spec gap

+ Nếu test fail, phân loại implementation defect, Spec gap, profile/configuration gap hoặc prohibited/high-risk mutation.

+ - Spec/profile gap: dừng, đề xuất `/sdd-update` hoặc Architecture Profile review và chờ Human.

+ - Implementation defect: chỉ bounded recovery trong approved task/file scope; không auto-retry mutation prohibited/high-risk.

+ - Dispatcher chỉ retry packet immutable không đổi; maximum 5 consecutive failures trước `ESCALATED`.

+ Không tạo repair loop, không retry chung chung, không để validation failure tự mở rộng scope.

## AI Recommendation và Human Final Review

- Trước execution, lưu canonical recommendation với Intent/DoD, profile evidence, approach, file boundary, exact command, state-change category, checkpoint, risk và sync-back. Sau execution, tạo completion recommendation với Action Record. Agent không tự complete, commit hoặc push.

+ Trước execution, lưu canonical recommendation với Intent/DoD, profile evidence, approach, file boundary, exact command, state-change category, checkpoint, risk và sync-back. Sau execution, tạo completion recommendation với Action Record và delivery/post-code review evidence. Agent không tự complete, commit hoặc push.