docs(aidd-dev): simplify implementation rules and require workflow evidence

plugins/aidd-dev/skills/02-implement/SKILL.md

@@ -6,24 +6,43 @@ argument-hint: plan
 
 # Skill: implement
 
-Run an existing plan to write its code, one phase at a time, until every acceptance criterion holds.
+```mermaid
+flowchart LR
+  prepare --> execute --> finalize --> implemented
+  prepare -->|missing plan| stop
+  execute -->|fix, next task or phase| execute
+  execute --> blocked
+  execute --> replan
+  finalize -->|validation fails| finalize
+  finalize --> blocked
+  finalize --> replan
+```
 
 ## Actions
 
-| #   | Action     | Role                                            | Input         |
-| --- | ---------- | ----------------------------------------------- | ------------- |
-| 01  | `prepare`  | Resolve the plan, branch, mark it in-progress   | a plan path   |
-| 02  | `execute`  | Loop the phases, code and assert each           | prepared plan |
-| 03  | `finalize` | Verify and mark the plan implemented            | coded phases  |
+Run actions in order.
+Read each action file in `actions/` before executing it.
 
-Run them in order, `01 → 03`.
-Before running an action, read its file in `actions/`, not only the table or assets.
+| Action   | Does                                  |
+| -------- | ------------------------------------- |
+| prepare  | resolve the plan and branch            |
+| execute  | implement and validate each task       |
+| finalize | validate and mark the plan implemented |
 
 ## Transversal rules
 
-- Status: drive the plan through `pending → in-progress → implemented` (or `blocked`), and each phase through `pending → in-progress → done`. The `in-progress` values are runtime markers; only `done` and `implemented` need to land in a commit.
-- Commits: one commit per phase, its code together with the phase reaching `done`, plus a final commit for the plan reaching `implemented`. Never leave the tree dirty at a phase boundary. Do not scatter separate `in-progress` status commits: one context now owns both code and status, so there is nothing to guard against.
-
-## References
-
-- `references/blocked.md`: the conditions that make a plan `blocked` and need a human.
+- Track the plan through `pending → in-progress → implemented` (or `blocked`).
+  - Track phases through `pending → in-progress → done`.
+  - Treat `in-progress` as a runtime marker.
+  - Never commit `in-progress` alone.
+- Follow user and project commit instructions.
+  - Push only when requested.
+- By default, make one local commit per validated task.
+  - Include all its code, tests and docs together.
+  - Group tasks only when they cannot be validated separately.
+  - Never split a task by step or file.
+  - Exclude unrelated changes.
+- Include `done` in the phase's last task commit.
+- Make a final commit for `implemented`.
+- Use project formatters or hooks.
+  - Never format code manually.

plugins/aidd-dev/skills/02-implement/actions/01-prepare.md

@@ -1,23 +1,19 @@
 # 01 - Prepare
 
-Resolve the plan, put the workspace on a feature branch, and mark the plan in-progress.
-
 ## Input
 
-A plan, passed as arguments as a path or inline content.
+A plan path or inline content.
 
 ## Output
 
-The resolved plan on a feature branch with its frontmatter `status: in-progress`, ready for the phase loop. Or a fail-fast stop when no plan resolves.
+The resolved plan on a feature branch with `status: in-progress`, or a missing-plan report.
 
 ## Process
 
-1. **Resolve.** Resolve the plan from the arguments. A path must exist and be readable. With neither a readable file nor inline content, stop with `plan not found at <path>`. Never fabricate a plan.
-2. **Branch.** On the default branch, create a feature branch and announce it. On a non-default branch, keep it.
-3. **Mark.** Set the plan frontmatter `status: in-progress` as a runtime marker. No separate commit: it rides into the first phase commit, or into the `implemented` commit if there is no phase to code.
+1. **Resolve.** Read the supplied plan.
+2. **Branch.** Create and announce a feature branch on the default branch; otherwise keep the current branch.
+3. **Mark.** Set the plan frontmatter `status: in-progress`.
 
-## Test
+## Rules
 
-- A missing or unreadable plan with no inline content stops with `plan not found at <path>`, and no plan is fabricated.
-- The current branch is not the default branch.
-- The plan frontmatter reads `status: in-progress`.
+- Without a readable plan or inline content, stop with `plan not found at <path>`; never fabricate a plan.

plugins/aidd-dev/skills/02-implement/actions/02-execute.md

@@ -1,26 +1,44 @@
 # 02 - Execute
 
-Loop the plan's phases in order, coding each until every acceptance criterion holds.
-
 ## Input
 
-The prepared plan on its feature branch, from `01-prepare`.
+The prepared plan.
 
 ## Output
 
-Every phase coded, asserted, and its frontmatter marked `status: done`, with the commits on the branch. Or a stop at `status: blocked` when a human is needed, or a `replan needed` report on any drift from the plan.
-
-## Process
+Validated phases marked `done`.
 
-1. **Open.** Walk the phases in order. In a feature folder each is a `phase-<n>.md` next to `plan.md`. Set its `status: in-progress` as a runtime marker; no commit yet.
-2. **Code.** Build the phase scope against its acceptance criteria.
-3. **Assert.** Assert the phase against its acceptance criteria. On failure, repair and repeat. The gate is the assertion passing, not a self-report. Once it passes, set `status: done` and commit the phase as one unit, its code and its status together.
-4. **Guard.** Stop the loop on either condition:
-   - **Blocked** (see [blocked.md](../references/blocked.md)): set the plan `status: blocked`, commit, stop.
-   - **Drift**: any mismatch with the plan, trivial or substantive, stop and report `replan needed: <reason>`. Never rewrite the plan; replanning is the caller's job.
+Or a `blocked` / `replan needed` report.
 
-## Test
+## Process
 
-- A phase reaches `status: done` only after assert passes against its acceptance criteria, in one commit with its code (`git status --short` shows no dangling phase edits).
-- The branch holds one commit per phase; there are no separate `in-progress` status commits.
-- A blocker leaves the plan `status: blocked` with no later phase run.
+1. **Open.** Walk phases in order.
+   - Set the current phase `status: in-progress`.
+   - In a feature folder, read `phase-<n>.md` beside `plan.md`.
+2. **Code.** Build the next task or inseparable group against its acceptance criteria.
+   - Follow the plan's task order.
+3. **Assert.** Apply the validation rules below to every acceptance criterion of the selected task or group.
+   - After the last task:
+     - Validate the full phase workflow.
+     - Set the phase `status: done` on success.
+4. **Complete.** Commit according to the commit policy.
+   - Repeat steps 2–4 for the remaining tasks.
+
+## Rules
+
+- Validate every acceptance criterion through the real affected workflow.
+  - Use the appropriate interface (browser, CLI, API…).
+  - Check actual against expected behavior at every step.
+  - Fix any mismatch.
+  - Restart from the beginning after a repair.
+- Gate task commits and `done` on successful validation.
+  - Require a full successful run.
+  - Require observable evidence for every step.
+  - Report blocked validation.
+  - Never count blocked validation as success.
+- Follow [blocked.md](../references/blocked.md) when implementation is blocked.
+  - Record the blocked plan according to the commit policy.
+  - Leave unfinished code uncommitted.
+- Stop if satisfying the acceptance criteria requires changing scope or requirements.
+  - Report `replan needed: <reason>`.
+  - Never rewrite the plan.

plugins/aidd-dev/skills/02-implement/actions/03-finalize.md

@@ -1,21 +1,26 @@
 # 03 - Finalize
 
-Run the validation and mark the plan implemented once every phase is done.
-
 ## Input
 
-A plan whose phases are all `status: done`, from `02-execute`.
+The coded plan.
 
 ## Output
 
-The feature validated green with the plan frontmatter `status: implemented`.
+The validated plan marked `implemented`.
 
 ## Process
 
-1. **Verify.** Run the plan's validation commands and tests. Never format code, never run dev mode.
-2. **Mark.** Every phase done and validation green, set the plan `status: implemented` and commit it.
+1. **Verify.** Run the plan's validation commands and tests.
+   - Start the required runtime if needed.
+2. **Mark.** Set the plan `status: implemented`.
+   - Commit according to the commit policy.
 
-## Test
+## Rules
 
-- The validation commands exit zero.
-- The plan reads `status: implemented`, committed (`git status --short` shows it clean).
+- Gate `implemented` on successful validation.
+  - Require every phase `done`.
+  - Require all validation commands and tests to pass.
+- Repair validation failures before `implemented`.
+  - Rerun the affected workflow after a repair.
+  - Rerun the validation commands and tests.
+  - Follow Execute's validation, blocker and drift rules.