From 82cde5e1f02079c6c3b0009408613e9a1871751c Mon Sep 17 00:00:00 2001 From: Shinsuke Kagawa Date: Sat, 5 Sep 2026 16:00:31 +0900 Subject: [PATCH 1/3] fix: align workflow verification and direct-scope QA contracts --- agents/acceptance-test-generator.md | 3 +-- agents/quality-fixer-frontend.md | 14 ++++++++++---- agents/quality-fixer.md | 14 ++++++++++---- agents/task-executor-frontend.md | 8 ++++---- agents/task-executor.md | 8 ++++---- agents/work-planner.md | 2 +- .../references/task-template.md | 2 +- dev-skills/skills/integration-e2e-testing/SKILL.md | 2 +- .../agents/acceptance-test-generator.md | 3 +-- .../agents/quality-fixer-frontend.md | 14 ++++++++++---- .../agents/task-executor-frontend.md | 8 ++++---- dev-workflows-frontend/agents/work-planner.md | 2 +- .../references/task-template.md | 2 +- .../skills/integration-e2e-testing/SKILL.md | 2 +- .../skills/recipe-front-adjust/SKILL.md | 3 +++ .../skills/recipe-front-review/SKILL.md | 2 +- .../skills/subagents-orchestration-guide/SKILL.md | 2 +- .../agents/acceptance-test-generator.md | 3 +-- .../agents/quality-fixer-frontend.md | 14 ++++++++++---- dev-workflows-fullstack/agents/quality-fixer.md | 14 ++++++++++---- .../agents/task-executor-frontend.md | 8 ++++---- dev-workflows-fullstack/agents/task-executor.md | 8 ++++---- dev-workflows-fullstack/agents/work-planner.md | 2 +- .../references/task-template.md | 2 +- .../skills/integration-e2e-testing/SKILL.md | 2 +- .../skills/recipe-add-integration-tests/SKILL.md | 3 ++- .../skills/recipe-front-adjust/SKILL.md | 3 +++ .../skills/recipe-front-review/SKILL.md | 2 +- .../skills/recipe-implement/SKILL.md | 2 +- .../skills/recipe-review/SKILL.md | 2 +- .../skills/subagents-orchestration-guide/SKILL.md | 2 +- dev-workflows/agents/acceptance-test-generator.md | 3 +-- dev-workflows/agents/quality-fixer.md | 14 ++++++++++---- dev-workflows/agents/task-executor.md | 8 ++++---- dev-workflows/agents/work-planner.md | 2 +- .../references/task-template.md | 2 +- .../skills/integration-e2e-testing/SKILL.md | 2 +- .../skills/recipe-add-integration-tests/SKILL.md | 3 ++- dev-workflows/skills/recipe-implement/SKILL.md | 2 +- dev-workflows/skills/recipe-review/SKILL.md | 2 +- .../skills/subagents-orchestration-guide/SKILL.md | 2 +- .../references/task-template.md | 2 +- skills/integration-e2e-testing/SKILL.md | 2 +- skills/recipe-add-integration-tests/SKILL.md | 3 ++- skills/recipe-front-adjust/SKILL.md | 3 +++ skills/recipe-front-review/SKILL.md | 2 +- skills/recipe-implement/SKILL.md | 2 +- skills/recipe-review/SKILL.md | 2 +- skills/subagents-orchestration-guide/SKILL.md | 2 +- 49 files changed, 130 insertions(+), 86 deletions(-) diff --git a/agents/acceptance-test-generator.md b/agents/acceptance-test-generator.md index 3db866d..fb07691 100644 --- a/agents/acceptance-test-generator.md +++ b/agents/acceptance-test-generator.md @@ -46,12 +46,11 @@ Test type definitions, budgets, and ROI calculations are specified in **integrat | **If-then** | Branch coverage test | Condition true/false → verify both paths | | (none) | Basic functionality test | Direct invocation → verify result | -**For each AC, apply 3 mandatory checks**: +**For each AC, apply these mandatory checks**: | Check | Question | Action if NO | Skip Reason | |-------|----------|--------------|-------------| | **Observable** | Can a user observe this? | Skip | [IMPLEMENTATION_DETAIL] | -| **System Context** | Requires full system integration? | Skip | [UNIT_LEVEL] | | **Upstream Scope** | In Include list? | Skip | [OUT_OF_SCOPE] | **AC Selection Criteria**: diff --git a/agents/quality-fixer-frontend.md b/agents/quality-fixer-frontend.md index dcbc2dd..74efec1 100644 --- a/agents/quality-fixer-frontend.md +++ b/agents/quality-fixer-frontend.md @@ -23,9 +23,15 @@ Executes applicable quality checks, fixes in-scope failures, and reports exact p ## Input Parameters - **task_file** (optional): Path to the task file being verified. When provided, use its Operation Verification Methods as task-specific checks. +- **direct_scope** (for workflow execution without a task file): Confirmed outcome and exclusions, copied unchanged from the execution scope +- **governing_sources** (for direct scope): Authoritative source paths and unchanged governing values used for execution +- **observable_verification** (for direct scope): The same behavior, artifact state, or command result required to prove execution complete +- **correction_findings** (optional): Complete applied finding objects supplied to the executor, copied unchanged as the correction scope and acceptance evidence - **qualityCommand** (optional): Quality command supplied by the caller or recorded in the task. Run it first, then cover the remaining applicable check categories. - **mutationEvidence** (optional): Upstream mutation results with restoration and target-revision proof +Use the task file when supplied; otherwise use the direct scope and read its governing sources. For ad-hoc quality requests, resolve the scope from the request and repository evidence. Missing decision-relevant evidence follows the existing `verification_incomplete` rule. + ## Execution Gate Before acting, map the preloaded skills to concrete rules for this task. Follow the applicable process below, advancing only when the current step's required evidence is present. Before returning, verify that the result satisfies those rules and the output requirements below. @@ -37,7 +43,7 @@ Use the appropriate run command based on the `packageManager` field in package.j ### Step 1: Incomplete Implementation Check [BLOCKING — before any quality checks] -Review the current uncommitted changes for incomplete implementation using the current task and repository context. This step runs before any quality checks because verifying the quality of unfinished code is meaningless. +Review the current uncommitted changes and the required outcome in the current repository state for incomplete implementation, using the task file or direct scope and governing sources. Include missing required behavior even when it has no changed file. This step runs before quality checks so generic check success cannot substitute for implementation completeness. Use the indicators below for this review. @@ -60,7 +66,7 @@ Use the indicators below for this review. Run `qualityCommand` first when provided. Treat it as covering the check categories it executes, then detect commands for remaining Step 3 categories from project manifests and configuration. When absent, detect all applicable commands this way. -When `task_file` is provided, run its Operation Verification Methods in addition to applicable checks discovered from project manifests and configuration. +Run the task file's Operation Verification Methods, or the direct scope's `observable_verification`, in addition to applicable checks discovered from project manifests and configuration. Use each supplied success condition to judge its proof. **External Resources Consultation**: When a quality check references a resource recorded in `docs/project-context/external-resources.md` or in a UI Spec / Design Doc / Work Plan "External Resources Used" entry, consult it per the external-resource-context skill (Reference Protocol). When the resource is referenced but unreachable, return `verification_incomplete` with `reason: "Execution prerequisites not met"` and populate `missingPrerequisites` after completing unaffected checks. @@ -104,7 +110,7 @@ Prefer repository-local component patterns over generic React advice; when patte ## Status Determination Criteria ### stub_detected (Incomplete implementation found — Step 1 gate) -Returned immediately when Step 1 finds incomplete implementations in the diff. Quality checks are not executed. The orchestrator should route this back to the implementation step for completion. +Returned immediately when Step 1 finds incomplete implementation of the required outcome. Quality checks are not executed. The orchestrator should route this back to the implementation step for completion. ### approved (All quality checks pass) - All tests pass (React Testing Library) @@ -170,7 +176,7 @@ Use this status only after Step 1 confirmed implementation completeness and ever ```json { "status": "stub_detected", - "reason": "Incomplete implementation detected in changed files", + "reason": "Required outcome is not fully implemented", "incompleteImplementations": [ { "file": "path/to/file", diff --git a/agents/quality-fixer.md b/agents/quality-fixer.md index 8166886..60be523 100644 --- a/agents/quality-fixer.md +++ b/agents/quality-fixer.md @@ -23,9 +23,15 @@ Executes applicable quality checks, fixes in-scope failures, and reports exact p ## Input Parameters - **task_file** (optional): Path to the task file being verified. When provided, use its Operation Verification Methods as task-specific checks. +- **direct_scope** (for workflow execution without a task file): Confirmed outcome and exclusions, copied unchanged from the execution scope +- **governing_sources** (for direct scope): Authoritative source paths and unchanged governing values used for execution +- **observable_verification** (for direct scope): The same behavior, artifact state, or command result required to prove execution complete +- **correction_findings** (optional): Complete applied finding objects supplied to the executor, copied unchanged as the correction scope and acceptance evidence - **qualityCommand** (optional): Quality command supplied by the caller or recorded in the task. Run it first, then cover the remaining applicable check categories. - **mutationEvidence** (optional): Upstream mutation results with restoration and target-revision proof +Use the task file when supplied; otherwise use the direct scope and read its governing sources. For ad-hoc quality requests, resolve the scope from the request and repository evidence. Missing decision-relevant evidence follows the existing `verification_incomplete` rule. + ## Execution Gate Before acting, map the preloaded skills to concrete rules for this task. Follow the applicable process below, advancing only when the current step's required evidence is present. Before returning, verify that the result satisfies those rules and the output requirements below. @@ -34,7 +40,7 @@ Before acting, map the preloaded skills to concrete rules for this task. Follow ### Step 1: Incomplete Implementation Check [BLOCKING — before any quality checks] -Review the current uncommitted changes for incomplete implementation using the current task and repository context. This step runs before any quality checks because verifying the quality of unfinished code is meaningless. +Review the current uncommitted changes and the required outcome in the current repository state for incomplete implementation, using the task file or direct scope and governing sources. Include missing required behavior even when it has no changed file. This step runs before quality checks so generic check success cannot substitute for implementation completeness. Use the indicators below for this review. @@ -54,7 +60,7 @@ Use the indicators below for this review. Run `qualityCommand` first when provided. Treat it as covering the check categories it executes, then detect commands for remaining Step 3 categories from project manifests and configuration. When absent, detect all applicable commands this way. -When `task_file` is provided, run its Operation Verification Methods in addition to applicable checks discovered from project manifests and configuration. +Run the task file's Operation Verification Methods, or the direct scope's `observable_verification`, in addition to applicable checks discovered from project manifests and configuration. Use each supplied success condition to judge its proof. **External Resources Consultation**: When a quality check references a resource recorded in `docs/project-context/external-resources.md` or in a Design Doc / Work Plan "External Resources Used" entry, consult it per the external-resource-context skill (Reference Protocol). When the resource is referenced but unreachable, return `verification_incomplete` with `reason: "Execution prerequisites not met"` and populate `missingPrerequisites` after completing unaffected checks. @@ -84,7 +90,7 @@ Return one of the following as the final response (see Output Format for schemas ## Status Determination Criteria ### stub_detected (Incomplete implementation found — Step 1 gate) -Returned immediately when Step 1 finds incomplete implementations in the diff. Quality checks are not executed. The orchestrator should route this back to the implementation step for completion. +Returned immediately when Step 1 finds incomplete implementation of the required outcome. Quality checks are not executed. The orchestrator should route this back to the implementation step for completion. ### approved (All quality checks pass) - All tests pass @@ -142,7 +148,7 @@ Use this status only after Step 1 confirmed implementation completeness and ever ```json { "status": "stub_detected", - "reason": "Incomplete implementation detected in changed files", + "reason": "Required outcome is not fully implemented", "incompleteImplementations": [ { "file": "path/to/file", diff --git a/agents/task-executor-frontend.md b/agents/task-executor-frontend.md index 6073e2d..a6231af 100644 --- a/agents/task-executor-frontend.md +++ b/agents/task-executor-frontend.md @@ -99,7 +99,7 @@ Any YES is corrected in implementation when the value boundary can remain true. ### 1. Task Selection -Resolve the frontend implementation objective through the input precedence above, derive operational details inside this agent, and begin repository investigation. A provided task file with every item complete returns the existing completed state; other inputs proceed from their outcome and available evidence. +Resolve the frontend implementation objective through the input precedence above, derive operational details inside this agent, and begin repository investigation. Completed task checkboxes guide continuation; confirm the outcome against the current repository state and applicable verification evidence before returning an existing completed result. ### 2. Task Background Understanding @@ -156,14 +156,14 @@ When adopting a pattern, hook, or library from existing code, apply Reference Re □ **New option discipline**: when no repository choice covers the concern, use the implementation-approach and external-resource-context rules to select the lowest-surface sufficient option, then apply the authoritative escalation boundary below #### Implementation Flow (TDD Compliant) -**Completion Confirmation**: When the execution scope is supplied as a task file or Work Plan and all relevant checkboxes are already `[x]`, report "already completed" and end +**When the outcome is already satisfied**: Preserve the implementation and proceed to Operation Verification before reporting completion. **Apply the applicable testing-principles flow and the task's Operation Verification Methods**: - **New/changed behavior or reproducible bug**: RED → GREEN → REFACTOR → VERIFY - **Behavior-preserving refactor**: BASELINE → REFACTOR → VERIFY the same evidence - **Non-reproducible bug**: record the reproduction blocker and alternate evidence → FIX → VERIFY that evidence - **Non-executable deliverable**: read the named source → PRODUCE/UPDATE → VERIFY against it -- For integration tests (multiple components), create and execute them with implementation; execute E2E tests in the final phase only +- Implement and run required integration/E2E tests in the earliest task where their declared proof boundary and dependencies are executable. Preserve generated skeleton paths and repository-required final checks. - **Progress Update [MANDATORY]**: Apply the Responsibility Boundaries progress rule after verification #### Operation Verification @@ -211,7 +211,7 @@ Complete this agent's work by returning the following JSON; the quality assuranc "requiresTestReview": false, "newTestsPassed": true, "reuseDecisions": [{"candidate": "[path:component-or-hook]", "decision": "reuse | extend | separate", "evidence": "[Responsibility, props/contract, lifecycle/state ownership, design-system role, and repository-representativeness evidence]"}], - "runnableCheck": {"level": "L1: Unit test (React Testing Library) / L2: Integration test / L3: E2E test", "executed": true, "command": "test -- Button.test.tsx", "result": "passed / failed / skipped", "reason": "Test execution reason/verification content"}, + "runnableCheck": {"level": "L1: Functional Operation Verification / L2: Test Operation Verification / L3: Build Success Verification", "executed": true, "command": "Executed verification command", "result": "passed / failed / skipped", "reason": "Verification content or exact limitation"}, "mutationEvidence": [{"mutation": "[description or patch]", "killedTest": "[test name]", "baselineResult": "[baseline command and result]", "mutatedResult": "[mutated command and result]", "restorationProof": "[restoration checksum or clean diff]", "targetRevision": "[revision or file hashes]"}] } ``` diff --git a/agents/task-executor.md b/agents/task-executor.md index 0bcc5fa..159ea42 100644 --- a/agents/task-executor.md +++ b/agents/task-executor.md @@ -94,7 +94,7 @@ Any YES is corrected in implementation when the value boundary can remain true. ### 1. Task Selection -Resolve the implementation objective through the input precedence above, derive operational details inside this agent, and begin repository investigation. A provided task file with every item complete returns the existing completed state; other inputs proceed from their outcome and available evidence. +Resolve the implementation objective through the input precedence above, derive operational details inside this agent, and begin repository investigation. Completed task checkboxes guide continuation; confirm the outcome against the current repository state and applicable verification evidence before returning an existing completed result. ### 2. Task Background Understanding @@ -152,7 +152,7 @@ When adopting a pattern or dependency from existing code, apply coding-principle #### Implementation Flow (TDD Compliant) -**When the execution scope is supplied as a task file or Work Plan and all relevant checkboxes are already `[x]`**: Report "already completed" and end +**When the outcome is already satisfied**: Preserve the implementation and proceed to Operation Verification before reporting completion. **For each implementation item, apply the applicable testing-principles flow and the task's Operation Verification Methods**: - **New/changed behavior or reproducible bug**: RED → GREEN → REFACTOR → VERIFY @@ -161,7 +161,7 @@ When adopting a pattern or dependency from existing code, apply coding-principle - **Non-executable deliverable**: read the named source → PRODUCE/UPDATE → VERIFY against it - **Progress Update**: Apply the Responsibility Boundaries progress rule after verification -**Test types**: Unit tests — use the applicable flow above; Integration tests — create and execute with implementation; E2E tests — execute in final phase only. +**Test types**: Apply the flow above to unit tests. Implement and run required integration/E2E tests in the earliest task where their declared proof boundary and dependencies are executable. Preserve generated skeleton paths and repository-required final checks. #### Operation Verification - Execute the Operation Verification Methods in the execution instructions @@ -208,7 +208,7 @@ Complete this agent's work by returning the following JSON; the quality assuranc "requiresTestReview": true, "newTestsPassed": true, "reuseDecisions": [{"candidate": "[path:symbol]", "decision": "reuse | extend | separate", "evidence": "[Responsibility, contract, lifecycle, and repository-representativeness evidence]"}], - "runnableCheck": {"level": "L1: Unit test / L2: Integration test / L3: E2E test", "executed": true, "command": "Executed test command", "result": "passed / failed / skipped", "reason": "Test execution reason/verification content"}, + "runnableCheck": {"level": "L1: Functional Operation Verification / L2: Test Operation Verification / L3: Build Success Verification", "executed": true, "command": "Executed verification command", "result": "passed / failed / skipped", "reason": "Verification content or exact limitation"}, "mutationEvidence": [{"mutation": "[description or patch]", "killedTest": "[test name]", "baselineResult": "[baseline command and result]", "mutatedResult": "[mutated command and result]", "restorationProof": "[restoration checksum or clean diff]", "targetRevision": "[revision or file hashes]"}] } ``` diff --git a/agents/work-planner.md b/agents/work-planner.md index 3a2bdad..ac95669 100644 --- a/agents/work-planner.md +++ b/agents/work-planner.md @@ -59,7 +59,7 @@ Apply the Design Doc's implementation approach and dependency order. 1. Treat the approved Selected Design as the complete implementation scope. 2. Group source, tests, repository configuration, wiring, and documentation that become complete at the same observable verification point. 3. Put a shared dependency before its consumer only when it must exist for that consumer to execute in a green repository state. -4. Use each skeleton's `@lane` as its placement rule: assign `integration` to the earliest task where its declared boundary becomes executable, `fixture-e2e` alongside the owning UI feature, and `service-integration-e2e` to the final implementation phase after its services are executable. That task preserves the skeleton path unchanged and completes the file as a runnable test. +4. Assign each skeleton to the earliest task where its declared proof boundary and dependencies become executable: `integration` with its in-process components, `fixture-e2e` with the owning UI feature, and `service-integration-e2e` when its required services are executable. That task preserves the skeleton path unchanged and completes the file as a runnable test. 5. Repeat until every implementation obligation is covered. Separate tasks only when a repository dependency, backend/frontend executor route, or independently completable governing outcome requires it. diff --git a/dev-skills/skills/documentation-criteria/references/task-template.md b/dev-skills/skills/documentation-criteria/references/task-template.md index 7af5917..a5292fd 100644 --- a/dev-skills/skills/documentation-criteria/references/task-template.md +++ b/dev-skills/skills/documentation-criteria/references/task-template.md @@ -46,7 +46,7 @@ Read the smallest representative set needed to implement the task: - **Verification method**: [Governing verification method or repository command] - **Success criteria**: [Observable result tied to cited ACs] -- **Verification level**: [L1 unit/local | L2 integration | L3 end-to-end] +- **Verification level**: [L1 functional operation | L2 passing tests | L3 successful build — per implementation-approach] ## Verification Focus diff --git a/dev-skills/skills/integration-e2e-testing/SKILL.md b/dev-skills/skills/integration-e2e-testing/SKILL.md index cfaa43c..f04bbbd 100644 --- a/dev-skills/skills/integration-e2e-testing/SKILL.md +++ b/dev-skills/skills/integration-e2e-testing/SKILL.md @@ -15,7 +15,7 @@ description: Integration and E2E test design principles, ROI calculation, test s |-----------|---------|-------|---------------|-------------------|----------------------| | Integration | Verify component interactions in-process | Partial system integration (in-process modules; for UI components, the framework's in-process renderer e.g., RTL+MSW for React/TS) | Mocked or in-process | MAX 3 | Created alongside implementation | | fixture-e2e | Verify UI behavior in a browser with deterministic fixtures | Full UI flow with mocked backend / fixture-driven state | Mocked / fixture only — no live services | MAX 3 | Created alongside the UI feature | -| service-integration-e2e | Verify critical user journeys against a running local stack | Full system across services | Live local services or stubs | MAX 1-2 | Executed only in the final phase | +| service-integration-e2e | Verify critical user journeys against a running local stack | Full system across services | Live local services or stubs | MAX 1-2 | Earliest task where the proof boundary and required services are executable | **Lane selection (E2E only)**: - Default lane for user-facing UI journeys is **fixture-e2e** — it runs a real browser against deterministic fixtures, catches the bugs that unit/integration tests miss (button no-op, state never updates, navigation breaks), and runs in CI without infrastructure setup diff --git a/dev-workflows-frontend/agents/acceptance-test-generator.md b/dev-workflows-frontend/agents/acceptance-test-generator.md index 3db866d..fb07691 100644 --- a/dev-workflows-frontend/agents/acceptance-test-generator.md +++ b/dev-workflows-frontend/agents/acceptance-test-generator.md @@ -46,12 +46,11 @@ Test type definitions, budgets, and ROI calculations are specified in **integrat | **If-then** | Branch coverage test | Condition true/false → verify both paths | | (none) | Basic functionality test | Direct invocation → verify result | -**For each AC, apply 3 mandatory checks**: +**For each AC, apply these mandatory checks**: | Check | Question | Action if NO | Skip Reason | |-------|----------|--------------|-------------| | **Observable** | Can a user observe this? | Skip | [IMPLEMENTATION_DETAIL] | -| **System Context** | Requires full system integration? | Skip | [UNIT_LEVEL] | | **Upstream Scope** | In Include list? | Skip | [OUT_OF_SCOPE] | **AC Selection Criteria**: diff --git a/dev-workflows-frontend/agents/quality-fixer-frontend.md b/dev-workflows-frontend/agents/quality-fixer-frontend.md index dcbc2dd..74efec1 100644 --- a/dev-workflows-frontend/agents/quality-fixer-frontend.md +++ b/dev-workflows-frontend/agents/quality-fixer-frontend.md @@ -23,9 +23,15 @@ Executes applicable quality checks, fixes in-scope failures, and reports exact p ## Input Parameters - **task_file** (optional): Path to the task file being verified. When provided, use its Operation Verification Methods as task-specific checks. +- **direct_scope** (for workflow execution without a task file): Confirmed outcome and exclusions, copied unchanged from the execution scope +- **governing_sources** (for direct scope): Authoritative source paths and unchanged governing values used for execution +- **observable_verification** (for direct scope): The same behavior, artifact state, or command result required to prove execution complete +- **correction_findings** (optional): Complete applied finding objects supplied to the executor, copied unchanged as the correction scope and acceptance evidence - **qualityCommand** (optional): Quality command supplied by the caller or recorded in the task. Run it first, then cover the remaining applicable check categories. - **mutationEvidence** (optional): Upstream mutation results with restoration and target-revision proof +Use the task file when supplied; otherwise use the direct scope and read its governing sources. For ad-hoc quality requests, resolve the scope from the request and repository evidence. Missing decision-relevant evidence follows the existing `verification_incomplete` rule. + ## Execution Gate Before acting, map the preloaded skills to concrete rules for this task. Follow the applicable process below, advancing only when the current step's required evidence is present. Before returning, verify that the result satisfies those rules and the output requirements below. @@ -37,7 +43,7 @@ Use the appropriate run command based on the `packageManager` field in package.j ### Step 1: Incomplete Implementation Check [BLOCKING — before any quality checks] -Review the current uncommitted changes for incomplete implementation using the current task and repository context. This step runs before any quality checks because verifying the quality of unfinished code is meaningless. +Review the current uncommitted changes and the required outcome in the current repository state for incomplete implementation, using the task file or direct scope and governing sources. Include missing required behavior even when it has no changed file. This step runs before quality checks so generic check success cannot substitute for implementation completeness. Use the indicators below for this review. @@ -60,7 +66,7 @@ Use the indicators below for this review. Run `qualityCommand` first when provided. Treat it as covering the check categories it executes, then detect commands for remaining Step 3 categories from project manifests and configuration. When absent, detect all applicable commands this way. -When `task_file` is provided, run its Operation Verification Methods in addition to applicable checks discovered from project manifests and configuration. +Run the task file's Operation Verification Methods, or the direct scope's `observable_verification`, in addition to applicable checks discovered from project manifests and configuration. Use each supplied success condition to judge its proof. **External Resources Consultation**: When a quality check references a resource recorded in `docs/project-context/external-resources.md` or in a UI Spec / Design Doc / Work Plan "External Resources Used" entry, consult it per the external-resource-context skill (Reference Protocol). When the resource is referenced but unreachable, return `verification_incomplete` with `reason: "Execution prerequisites not met"` and populate `missingPrerequisites` after completing unaffected checks. @@ -104,7 +110,7 @@ Prefer repository-local component patterns over generic React advice; when patte ## Status Determination Criteria ### stub_detected (Incomplete implementation found — Step 1 gate) -Returned immediately when Step 1 finds incomplete implementations in the diff. Quality checks are not executed. The orchestrator should route this back to the implementation step for completion. +Returned immediately when Step 1 finds incomplete implementation of the required outcome. Quality checks are not executed. The orchestrator should route this back to the implementation step for completion. ### approved (All quality checks pass) - All tests pass (React Testing Library) @@ -170,7 +176,7 @@ Use this status only after Step 1 confirmed implementation completeness and ever ```json { "status": "stub_detected", - "reason": "Incomplete implementation detected in changed files", + "reason": "Required outcome is not fully implemented", "incompleteImplementations": [ { "file": "path/to/file", diff --git a/dev-workflows-frontend/agents/task-executor-frontend.md b/dev-workflows-frontend/agents/task-executor-frontend.md index 6073e2d..a6231af 100644 --- a/dev-workflows-frontend/agents/task-executor-frontend.md +++ b/dev-workflows-frontend/agents/task-executor-frontend.md @@ -99,7 +99,7 @@ Any YES is corrected in implementation when the value boundary can remain true. ### 1. Task Selection -Resolve the frontend implementation objective through the input precedence above, derive operational details inside this agent, and begin repository investigation. A provided task file with every item complete returns the existing completed state; other inputs proceed from their outcome and available evidence. +Resolve the frontend implementation objective through the input precedence above, derive operational details inside this agent, and begin repository investigation. Completed task checkboxes guide continuation; confirm the outcome against the current repository state and applicable verification evidence before returning an existing completed result. ### 2. Task Background Understanding @@ -156,14 +156,14 @@ When adopting a pattern, hook, or library from existing code, apply Reference Re □ **New option discipline**: when no repository choice covers the concern, use the implementation-approach and external-resource-context rules to select the lowest-surface sufficient option, then apply the authoritative escalation boundary below #### Implementation Flow (TDD Compliant) -**Completion Confirmation**: When the execution scope is supplied as a task file or Work Plan and all relevant checkboxes are already `[x]`, report "already completed" and end +**When the outcome is already satisfied**: Preserve the implementation and proceed to Operation Verification before reporting completion. **Apply the applicable testing-principles flow and the task's Operation Verification Methods**: - **New/changed behavior or reproducible bug**: RED → GREEN → REFACTOR → VERIFY - **Behavior-preserving refactor**: BASELINE → REFACTOR → VERIFY the same evidence - **Non-reproducible bug**: record the reproduction blocker and alternate evidence → FIX → VERIFY that evidence - **Non-executable deliverable**: read the named source → PRODUCE/UPDATE → VERIFY against it -- For integration tests (multiple components), create and execute them with implementation; execute E2E tests in the final phase only +- Implement and run required integration/E2E tests in the earliest task where their declared proof boundary and dependencies are executable. Preserve generated skeleton paths and repository-required final checks. - **Progress Update [MANDATORY]**: Apply the Responsibility Boundaries progress rule after verification #### Operation Verification @@ -211,7 +211,7 @@ Complete this agent's work by returning the following JSON; the quality assuranc "requiresTestReview": false, "newTestsPassed": true, "reuseDecisions": [{"candidate": "[path:component-or-hook]", "decision": "reuse | extend | separate", "evidence": "[Responsibility, props/contract, lifecycle/state ownership, design-system role, and repository-representativeness evidence]"}], - "runnableCheck": {"level": "L1: Unit test (React Testing Library) / L2: Integration test / L3: E2E test", "executed": true, "command": "test -- Button.test.tsx", "result": "passed / failed / skipped", "reason": "Test execution reason/verification content"}, + "runnableCheck": {"level": "L1: Functional Operation Verification / L2: Test Operation Verification / L3: Build Success Verification", "executed": true, "command": "Executed verification command", "result": "passed / failed / skipped", "reason": "Verification content or exact limitation"}, "mutationEvidence": [{"mutation": "[description or patch]", "killedTest": "[test name]", "baselineResult": "[baseline command and result]", "mutatedResult": "[mutated command and result]", "restorationProof": "[restoration checksum or clean diff]", "targetRevision": "[revision or file hashes]"}] } ``` diff --git a/dev-workflows-frontend/agents/work-planner.md b/dev-workflows-frontend/agents/work-planner.md index 3a2bdad..ac95669 100644 --- a/dev-workflows-frontend/agents/work-planner.md +++ b/dev-workflows-frontend/agents/work-planner.md @@ -59,7 +59,7 @@ Apply the Design Doc's implementation approach and dependency order. 1. Treat the approved Selected Design as the complete implementation scope. 2. Group source, tests, repository configuration, wiring, and documentation that become complete at the same observable verification point. 3. Put a shared dependency before its consumer only when it must exist for that consumer to execute in a green repository state. -4. Use each skeleton's `@lane` as its placement rule: assign `integration` to the earliest task where its declared boundary becomes executable, `fixture-e2e` alongside the owning UI feature, and `service-integration-e2e` to the final implementation phase after its services are executable. That task preserves the skeleton path unchanged and completes the file as a runnable test. +4. Assign each skeleton to the earliest task where its declared proof boundary and dependencies become executable: `integration` with its in-process components, `fixture-e2e` with the owning UI feature, and `service-integration-e2e` when its required services are executable. That task preserves the skeleton path unchanged and completes the file as a runnable test. 5. Repeat until every implementation obligation is covered. Separate tasks only when a repository dependency, backend/frontend executor route, or independently completable governing outcome requires it. diff --git a/dev-workflows-frontend/skills/documentation-criteria/references/task-template.md b/dev-workflows-frontend/skills/documentation-criteria/references/task-template.md index 7af5917..a5292fd 100644 --- a/dev-workflows-frontend/skills/documentation-criteria/references/task-template.md +++ b/dev-workflows-frontend/skills/documentation-criteria/references/task-template.md @@ -46,7 +46,7 @@ Read the smallest representative set needed to implement the task: - **Verification method**: [Governing verification method or repository command] - **Success criteria**: [Observable result tied to cited ACs] -- **Verification level**: [L1 unit/local | L2 integration | L3 end-to-end] +- **Verification level**: [L1 functional operation | L2 passing tests | L3 successful build — per implementation-approach] ## Verification Focus diff --git a/dev-workflows-frontend/skills/integration-e2e-testing/SKILL.md b/dev-workflows-frontend/skills/integration-e2e-testing/SKILL.md index cfaa43c..f04bbbd 100644 --- a/dev-workflows-frontend/skills/integration-e2e-testing/SKILL.md +++ b/dev-workflows-frontend/skills/integration-e2e-testing/SKILL.md @@ -15,7 +15,7 @@ description: Integration and E2E test design principles, ROI calculation, test s |-----------|---------|-------|---------------|-------------------|----------------------| | Integration | Verify component interactions in-process | Partial system integration (in-process modules; for UI components, the framework's in-process renderer e.g., RTL+MSW for React/TS) | Mocked or in-process | MAX 3 | Created alongside implementation | | fixture-e2e | Verify UI behavior in a browser with deterministic fixtures | Full UI flow with mocked backend / fixture-driven state | Mocked / fixture only — no live services | MAX 3 | Created alongside the UI feature | -| service-integration-e2e | Verify critical user journeys against a running local stack | Full system across services | Live local services or stubs | MAX 1-2 | Executed only in the final phase | +| service-integration-e2e | Verify critical user journeys against a running local stack | Full system across services | Live local services or stubs | MAX 1-2 | Earliest task where the proof boundary and required services are executable | **Lane selection (E2E only)**: - Default lane for user-facing UI journeys is **fixture-e2e** — it runs a real browser against deterministic fixtures, catches the bugs that unit/integration tests miss (button no-op, state never updates, navigation breaks), and runs in CI without infrastructure setup diff --git a/dev-workflows-frontend/skills/recipe-front-adjust/SKILL.md b/dev-workflows-frontend/skills/recipe-front-adjust/SKILL.md index 8d4b192..dbec52f 100644 --- a/dev-workflows-frontend/skills/recipe-front-adjust/SKILL.md +++ b/dev-workflows-frontend/skills/recipe-front-adjust/SKILL.md @@ -113,6 +113,9 @@ When the project-tier file declares no automated verification mechanism for an a - Invoke **quality-fixer-frontend** using Agent tool - `subagent_type: "dev-workflows-frontend:quality-fixer-frontend"` - `description: "Quality verification for adjustment unit"` + - `direct_scope`: Copy the current unit's confirmed adjustment request and preserved visible behavior from Step 4 unchanged. + - `governing_sources`: Pass the existing UI and design source references used for this unit unchanged. + - `observable_verification`: Copy the verification criteria used for this unit in Step 5 unchanged. - Pass `qualityCommand` when available (caller first, otherwise current task). - Route the quality-fixer-frontend response by `status`: - `approved` → proceed to Step 7 diff --git a/dev-workflows-frontend/skills/recipe-front-review/SKILL.md b/dev-workflows-frontend/skills/recipe-front-review/SKILL.md index eec0dff..fea8c04 100644 --- a/dev-workflows-frontend/skills/recipe-front-review/SKILL.md +++ b/dev-workflows-frontend/skills/recipe-front-review/SKILL.md @@ -139,8 +139,8 @@ Invoke task-executor-frontend using Agent tool: Invoke quality-fixer-frontend using Agent tool: - `subagent_type`: "dev-workflows-frontend:quality-fixer-frontend" - `description`: "Quality gate check" +- Copy Step 6 `direct_scope`, `governing_sources`, `observable_verification`, and `correction_findings` inputs unchanged. - Pass Step 6 `mutationEvidence`. -- `prompt`: "Confirm quality gate passage for fixed files." Route the quality-fixer-frontend result: - `approved` → Proceed to Step 8 diff --git a/dev-workflows-frontend/skills/subagents-orchestration-guide/SKILL.md b/dev-workflows-frontend/skills/subagents-orchestration-guide/SKILL.md index 102e99a..a6eb108 100644 --- a/dev-workflows-frontend/skills/subagents-orchestration-guide/SKILL.md +++ b/dev-workflows-frontend/skills/subagents-orchestration-guide/SKILL.md @@ -239,7 +239,7 @@ Derive the values from the quality-fixer result. Keep the complete result in orc - `blocked` → Apply Specialist Result Acceptance - `needs_revision` → Pass `qualityIssues` objects unchanged into Review Resolution. On correction re-review, derive the next transition only from `prior_feedback_reconciliation`; return to step 1 for rerouted corrections and proceed to step 3 only at convergence - Otherwise → Proceed to step 3 -3. **Quality-fix**: invoke quality-fixer with upstream `mutationEvidence`, plus `task_file` when available and `qualityCommand` from the caller first or task otherwise +3. **Quality-fix**: invoke quality-fixer with `task_file` when available; otherwise copy the executor's `direct_scope`, `governing_sources`, and `observable_verification` inputs unchanged, including `correction_findings` when supplied. Add upstream `mutationEvidence` and `qualityCommand` from the caller first or task otherwise - `stub_detected` → Return to step 1 with quality-fixer's `incompleteImplementations` array unchanged as the canonical `incompleteImplementations` field - `blocked` → Apply Specialist Result Acceptance - `verification_incomplete` → Retain the complete result for final retry and proceed to step 4 diff --git a/dev-workflows-fullstack/agents/acceptance-test-generator.md b/dev-workflows-fullstack/agents/acceptance-test-generator.md index 3db866d..fb07691 100644 --- a/dev-workflows-fullstack/agents/acceptance-test-generator.md +++ b/dev-workflows-fullstack/agents/acceptance-test-generator.md @@ -46,12 +46,11 @@ Test type definitions, budgets, and ROI calculations are specified in **integrat | **If-then** | Branch coverage test | Condition true/false → verify both paths | | (none) | Basic functionality test | Direct invocation → verify result | -**For each AC, apply 3 mandatory checks**: +**For each AC, apply these mandatory checks**: | Check | Question | Action if NO | Skip Reason | |-------|----------|--------------|-------------| | **Observable** | Can a user observe this? | Skip | [IMPLEMENTATION_DETAIL] | -| **System Context** | Requires full system integration? | Skip | [UNIT_LEVEL] | | **Upstream Scope** | In Include list? | Skip | [OUT_OF_SCOPE] | **AC Selection Criteria**: diff --git a/dev-workflows-fullstack/agents/quality-fixer-frontend.md b/dev-workflows-fullstack/agents/quality-fixer-frontend.md index dcbc2dd..74efec1 100644 --- a/dev-workflows-fullstack/agents/quality-fixer-frontend.md +++ b/dev-workflows-fullstack/agents/quality-fixer-frontend.md @@ -23,9 +23,15 @@ Executes applicable quality checks, fixes in-scope failures, and reports exact p ## Input Parameters - **task_file** (optional): Path to the task file being verified. When provided, use its Operation Verification Methods as task-specific checks. +- **direct_scope** (for workflow execution without a task file): Confirmed outcome and exclusions, copied unchanged from the execution scope +- **governing_sources** (for direct scope): Authoritative source paths and unchanged governing values used for execution +- **observable_verification** (for direct scope): The same behavior, artifact state, or command result required to prove execution complete +- **correction_findings** (optional): Complete applied finding objects supplied to the executor, copied unchanged as the correction scope and acceptance evidence - **qualityCommand** (optional): Quality command supplied by the caller or recorded in the task. Run it first, then cover the remaining applicable check categories. - **mutationEvidence** (optional): Upstream mutation results with restoration and target-revision proof +Use the task file when supplied; otherwise use the direct scope and read its governing sources. For ad-hoc quality requests, resolve the scope from the request and repository evidence. Missing decision-relevant evidence follows the existing `verification_incomplete` rule. + ## Execution Gate Before acting, map the preloaded skills to concrete rules for this task. Follow the applicable process below, advancing only when the current step's required evidence is present. Before returning, verify that the result satisfies those rules and the output requirements below. @@ -37,7 +43,7 @@ Use the appropriate run command based on the `packageManager` field in package.j ### Step 1: Incomplete Implementation Check [BLOCKING — before any quality checks] -Review the current uncommitted changes for incomplete implementation using the current task and repository context. This step runs before any quality checks because verifying the quality of unfinished code is meaningless. +Review the current uncommitted changes and the required outcome in the current repository state for incomplete implementation, using the task file or direct scope and governing sources. Include missing required behavior even when it has no changed file. This step runs before quality checks so generic check success cannot substitute for implementation completeness. Use the indicators below for this review. @@ -60,7 +66,7 @@ Use the indicators below for this review. Run `qualityCommand` first when provided. Treat it as covering the check categories it executes, then detect commands for remaining Step 3 categories from project manifests and configuration. When absent, detect all applicable commands this way. -When `task_file` is provided, run its Operation Verification Methods in addition to applicable checks discovered from project manifests and configuration. +Run the task file's Operation Verification Methods, or the direct scope's `observable_verification`, in addition to applicable checks discovered from project manifests and configuration. Use each supplied success condition to judge its proof. **External Resources Consultation**: When a quality check references a resource recorded in `docs/project-context/external-resources.md` or in a UI Spec / Design Doc / Work Plan "External Resources Used" entry, consult it per the external-resource-context skill (Reference Protocol). When the resource is referenced but unreachable, return `verification_incomplete` with `reason: "Execution prerequisites not met"` and populate `missingPrerequisites` after completing unaffected checks. @@ -104,7 +110,7 @@ Prefer repository-local component patterns over generic React advice; when patte ## Status Determination Criteria ### stub_detected (Incomplete implementation found — Step 1 gate) -Returned immediately when Step 1 finds incomplete implementations in the diff. Quality checks are not executed. The orchestrator should route this back to the implementation step for completion. +Returned immediately when Step 1 finds incomplete implementation of the required outcome. Quality checks are not executed. The orchestrator should route this back to the implementation step for completion. ### approved (All quality checks pass) - All tests pass (React Testing Library) @@ -170,7 +176,7 @@ Use this status only after Step 1 confirmed implementation completeness and ever ```json { "status": "stub_detected", - "reason": "Incomplete implementation detected in changed files", + "reason": "Required outcome is not fully implemented", "incompleteImplementations": [ { "file": "path/to/file", diff --git a/dev-workflows-fullstack/agents/quality-fixer.md b/dev-workflows-fullstack/agents/quality-fixer.md index 8166886..60be523 100644 --- a/dev-workflows-fullstack/agents/quality-fixer.md +++ b/dev-workflows-fullstack/agents/quality-fixer.md @@ -23,9 +23,15 @@ Executes applicable quality checks, fixes in-scope failures, and reports exact p ## Input Parameters - **task_file** (optional): Path to the task file being verified. When provided, use its Operation Verification Methods as task-specific checks. +- **direct_scope** (for workflow execution without a task file): Confirmed outcome and exclusions, copied unchanged from the execution scope +- **governing_sources** (for direct scope): Authoritative source paths and unchanged governing values used for execution +- **observable_verification** (for direct scope): The same behavior, artifact state, or command result required to prove execution complete +- **correction_findings** (optional): Complete applied finding objects supplied to the executor, copied unchanged as the correction scope and acceptance evidence - **qualityCommand** (optional): Quality command supplied by the caller or recorded in the task. Run it first, then cover the remaining applicable check categories. - **mutationEvidence** (optional): Upstream mutation results with restoration and target-revision proof +Use the task file when supplied; otherwise use the direct scope and read its governing sources. For ad-hoc quality requests, resolve the scope from the request and repository evidence. Missing decision-relevant evidence follows the existing `verification_incomplete` rule. + ## Execution Gate Before acting, map the preloaded skills to concrete rules for this task. Follow the applicable process below, advancing only when the current step's required evidence is present. Before returning, verify that the result satisfies those rules and the output requirements below. @@ -34,7 +40,7 @@ Before acting, map the preloaded skills to concrete rules for this task. Follow ### Step 1: Incomplete Implementation Check [BLOCKING — before any quality checks] -Review the current uncommitted changes for incomplete implementation using the current task and repository context. This step runs before any quality checks because verifying the quality of unfinished code is meaningless. +Review the current uncommitted changes and the required outcome in the current repository state for incomplete implementation, using the task file or direct scope and governing sources. Include missing required behavior even when it has no changed file. This step runs before quality checks so generic check success cannot substitute for implementation completeness. Use the indicators below for this review. @@ -54,7 +60,7 @@ Use the indicators below for this review. Run `qualityCommand` first when provided. Treat it as covering the check categories it executes, then detect commands for remaining Step 3 categories from project manifests and configuration. When absent, detect all applicable commands this way. -When `task_file` is provided, run its Operation Verification Methods in addition to applicable checks discovered from project manifests and configuration. +Run the task file's Operation Verification Methods, or the direct scope's `observable_verification`, in addition to applicable checks discovered from project manifests and configuration. Use each supplied success condition to judge its proof. **External Resources Consultation**: When a quality check references a resource recorded in `docs/project-context/external-resources.md` or in a Design Doc / Work Plan "External Resources Used" entry, consult it per the external-resource-context skill (Reference Protocol). When the resource is referenced but unreachable, return `verification_incomplete` with `reason: "Execution prerequisites not met"` and populate `missingPrerequisites` after completing unaffected checks. @@ -84,7 +90,7 @@ Return one of the following as the final response (see Output Format for schemas ## Status Determination Criteria ### stub_detected (Incomplete implementation found — Step 1 gate) -Returned immediately when Step 1 finds incomplete implementations in the diff. Quality checks are not executed. The orchestrator should route this back to the implementation step for completion. +Returned immediately when Step 1 finds incomplete implementation of the required outcome. Quality checks are not executed. The orchestrator should route this back to the implementation step for completion. ### approved (All quality checks pass) - All tests pass @@ -142,7 +148,7 @@ Use this status only after Step 1 confirmed implementation completeness and ever ```json { "status": "stub_detected", - "reason": "Incomplete implementation detected in changed files", + "reason": "Required outcome is not fully implemented", "incompleteImplementations": [ { "file": "path/to/file", diff --git a/dev-workflows-fullstack/agents/task-executor-frontend.md b/dev-workflows-fullstack/agents/task-executor-frontend.md index 6073e2d..a6231af 100644 --- a/dev-workflows-fullstack/agents/task-executor-frontend.md +++ b/dev-workflows-fullstack/agents/task-executor-frontend.md @@ -99,7 +99,7 @@ Any YES is corrected in implementation when the value boundary can remain true. ### 1. Task Selection -Resolve the frontend implementation objective through the input precedence above, derive operational details inside this agent, and begin repository investigation. A provided task file with every item complete returns the existing completed state; other inputs proceed from their outcome and available evidence. +Resolve the frontend implementation objective through the input precedence above, derive operational details inside this agent, and begin repository investigation. Completed task checkboxes guide continuation; confirm the outcome against the current repository state and applicable verification evidence before returning an existing completed result. ### 2. Task Background Understanding @@ -156,14 +156,14 @@ When adopting a pattern, hook, or library from existing code, apply Reference Re □ **New option discipline**: when no repository choice covers the concern, use the implementation-approach and external-resource-context rules to select the lowest-surface sufficient option, then apply the authoritative escalation boundary below #### Implementation Flow (TDD Compliant) -**Completion Confirmation**: When the execution scope is supplied as a task file or Work Plan and all relevant checkboxes are already `[x]`, report "already completed" and end +**When the outcome is already satisfied**: Preserve the implementation and proceed to Operation Verification before reporting completion. **Apply the applicable testing-principles flow and the task's Operation Verification Methods**: - **New/changed behavior or reproducible bug**: RED → GREEN → REFACTOR → VERIFY - **Behavior-preserving refactor**: BASELINE → REFACTOR → VERIFY the same evidence - **Non-reproducible bug**: record the reproduction blocker and alternate evidence → FIX → VERIFY that evidence - **Non-executable deliverable**: read the named source → PRODUCE/UPDATE → VERIFY against it -- For integration tests (multiple components), create and execute them with implementation; execute E2E tests in the final phase only +- Implement and run required integration/E2E tests in the earliest task where their declared proof boundary and dependencies are executable. Preserve generated skeleton paths and repository-required final checks. - **Progress Update [MANDATORY]**: Apply the Responsibility Boundaries progress rule after verification #### Operation Verification @@ -211,7 +211,7 @@ Complete this agent's work by returning the following JSON; the quality assuranc "requiresTestReview": false, "newTestsPassed": true, "reuseDecisions": [{"candidate": "[path:component-or-hook]", "decision": "reuse | extend | separate", "evidence": "[Responsibility, props/contract, lifecycle/state ownership, design-system role, and repository-representativeness evidence]"}], - "runnableCheck": {"level": "L1: Unit test (React Testing Library) / L2: Integration test / L3: E2E test", "executed": true, "command": "test -- Button.test.tsx", "result": "passed / failed / skipped", "reason": "Test execution reason/verification content"}, + "runnableCheck": {"level": "L1: Functional Operation Verification / L2: Test Operation Verification / L3: Build Success Verification", "executed": true, "command": "Executed verification command", "result": "passed / failed / skipped", "reason": "Verification content or exact limitation"}, "mutationEvidence": [{"mutation": "[description or patch]", "killedTest": "[test name]", "baselineResult": "[baseline command and result]", "mutatedResult": "[mutated command and result]", "restorationProof": "[restoration checksum or clean diff]", "targetRevision": "[revision or file hashes]"}] } ``` diff --git a/dev-workflows-fullstack/agents/task-executor.md b/dev-workflows-fullstack/agents/task-executor.md index 0bcc5fa..159ea42 100644 --- a/dev-workflows-fullstack/agents/task-executor.md +++ b/dev-workflows-fullstack/agents/task-executor.md @@ -94,7 +94,7 @@ Any YES is corrected in implementation when the value boundary can remain true. ### 1. Task Selection -Resolve the implementation objective through the input precedence above, derive operational details inside this agent, and begin repository investigation. A provided task file with every item complete returns the existing completed state; other inputs proceed from their outcome and available evidence. +Resolve the implementation objective through the input precedence above, derive operational details inside this agent, and begin repository investigation. Completed task checkboxes guide continuation; confirm the outcome against the current repository state and applicable verification evidence before returning an existing completed result. ### 2. Task Background Understanding @@ -152,7 +152,7 @@ When adopting a pattern or dependency from existing code, apply coding-principle #### Implementation Flow (TDD Compliant) -**When the execution scope is supplied as a task file or Work Plan and all relevant checkboxes are already `[x]`**: Report "already completed" and end +**When the outcome is already satisfied**: Preserve the implementation and proceed to Operation Verification before reporting completion. **For each implementation item, apply the applicable testing-principles flow and the task's Operation Verification Methods**: - **New/changed behavior or reproducible bug**: RED → GREEN → REFACTOR → VERIFY @@ -161,7 +161,7 @@ When adopting a pattern or dependency from existing code, apply coding-principle - **Non-executable deliverable**: read the named source → PRODUCE/UPDATE → VERIFY against it - **Progress Update**: Apply the Responsibility Boundaries progress rule after verification -**Test types**: Unit tests — use the applicable flow above; Integration tests — create and execute with implementation; E2E tests — execute in final phase only. +**Test types**: Apply the flow above to unit tests. Implement and run required integration/E2E tests in the earliest task where their declared proof boundary and dependencies are executable. Preserve generated skeleton paths and repository-required final checks. #### Operation Verification - Execute the Operation Verification Methods in the execution instructions @@ -208,7 +208,7 @@ Complete this agent's work by returning the following JSON; the quality assuranc "requiresTestReview": true, "newTestsPassed": true, "reuseDecisions": [{"candidate": "[path:symbol]", "decision": "reuse | extend | separate", "evidence": "[Responsibility, contract, lifecycle, and repository-representativeness evidence]"}], - "runnableCheck": {"level": "L1: Unit test / L2: Integration test / L3: E2E test", "executed": true, "command": "Executed test command", "result": "passed / failed / skipped", "reason": "Test execution reason/verification content"}, + "runnableCheck": {"level": "L1: Functional Operation Verification / L2: Test Operation Verification / L3: Build Success Verification", "executed": true, "command": "Executed verification command", "result": "passed / failed / skipped", "reason": "Verification content or exact limitation"}, "mutationEvidence": [{"mutation": "[description or patch]", "killedTest": "[test name]", "baselineResult": "[baseline command and result]", "mutatedResult": "[mutated command and result]", "restorationProof": "[restoration checksum or clean diff]", "targetRevision": "[revision or file hashes]"}] } ``` diff --git a/dev-workflows-fullstack/agents/work-planner.md b/dev-workflows-fullstack/agents/work-planner.md index 3a2bdad..ac95669 100644 --- a/dev-workflows-fullstack/agents/work-planner.md +++ b/dev-workflows-fullstack/agents/work-planner.md @@ -59,7 +59,7 @@ Apply the Design Doc's implementation approach and dependency order. 1. Treat the approved Selected Design as the complete implementation scope. 2. Group source, tests, repository configuration, wiring, and documentation that become complete at the same observable verification point. 3. Put a shared dependency before its consumer only when it must exist for that consumer to execute in a green repository state. -4. Use each skeleton's `@lane` as its placement rule: assign `integration` to the earliest task where its declared boundary becomes executable, `fixture-e2e` alongside the owning UI feature, and `service-integration-e2e` to the final implementation phase after its services are executable. That task preserves the skeleton path unchanged and completes the file as a runnable test. +4. Assign each skeleton to the earliest task where its declared proof boundary and dependencies become executable: `integration` with its in-process components, `fixture-e2e` with the owning UI feature, and `service-integration-e2e` when its required services are executable. That task preserves the skeleton path unchanged and completes the file as a runnable test. 5. Repeat until every implementation obligation is covered. Separate tasks only when a repository dependency, backend/frontend executor route, or independently completable governing outcome requires it. diff --git a/dev-workflows-fullstack/skills/documentation-criteria/references/task-template.md b/dev-workflows-fullstack/skills/documentation-criteria/references/task-template.md index 7af5917..a5292fd 100644 --- a/dev-workflows-fullstack/skills/documentation-criteria/references/task-template.md +++ b/dev-workflows-fullstack/skills/documentation-criteria/references/task-template.md @@ -46,7 +46,7 @@ Read the smallest representative set needed to implement the task: - **Verification method**: [Governing verification method or repository command] - **Success criteria**: [Observable result tied to cited ACs] -- **Verification level**: [L1 unit/local | L2 integration | L3 end-to-end] +- **Verification level**: [L1 functional operation | L2 passing tests | L3 successful build — per implementation-approach] ## Verification Focus diff --git a/dev-workflows-fullstack/skills/integration-e2e-testing/SKILL.md b/dev-workflows-fullstack/skills/integration-e2e-testing/SKILL.md index cfaa43c..f04bbbd 100644 --- a/dev-workflows-fullstack/skills/integration-e2e-testing/SKILL.md +++ b/dev-workflows-fullstack/skills/integration-e2e-testing/SKILL.md @@ -15,7 +15,7 @@ description: Integration and E2E test design principles, ROI calculation, test s |-----------|---------|-------|---------------|-------------------|----------------------| | Integration | Verify component interactions in-process | Partial system integration (in-process modules; for UI components, the framework's in-process renderer e.g., RTL+MSW for React/TS) | Mocked or in-process | MAX 3 | Created alongside implementation | | fixture-e2e | Verify UI behavior in a browser with deterministic fixtures | Full UI flow with mocked backend / fixture-driven state | Mocked / fixture only — no live services | MAX 3 | Created alongside the UI feature | -| service-integration-e2e | Verify critical user journeys against a running local stack | Full system across services | Live local services or stubs | MAX 1-2 | Executed only in the final phase | +| service-integration-e2e | Verify critical user journeys against a running local stack | Full system across services | Live local services or stubs | MAX 1-2 | Earliest task where the proof boundary and required services are executable | **Lane selection (E2E only)**: - Default lane for user-facing UI journeys is **fixture-e2e** — it runs a real browser against deterministic fixtures, catches the bugs that unit/integration tests miss (button no-op, state never updates, navigation breaks), and runs in CI without infrastructure setup diff --git a/dev-workflows-fullstack/skills/recipe-add-integration-tests/SKILL.md b/dev-workflows-fullstack/skills/recipe-add-integration-tests/SKILL.md index 6457daa..8f7eeb5 100644 --- a/dev-workflows-fullstack/skills/recipe-add-integration-tests/SKILL.md +++ b/dev-workflows-fullstack/skills/recipe-add-integration-tests/SKILL.md @@ -112,8 +112,9 @@ Invoke quality-fixer for the current layer: - Backend or single-layer → `subagent_type`: "dev-workflows-fullstack:quality-fixer" - Frontend → `subagent_type`: "dev-workflows-fullstack:quality-fixer-frontend" - `description`: "Final quality assurance" +- Copy Step 3 `direct_scope`, `governing_sources`, and `observable_verification` inputs unchanged. +- Include the latest executor's `correction_findings` input unchanged when supplied. - Pass the latest executor's `mutationEvidence`. -- `prompt`: "Run the repository-configured quality checks applicable to the test files added in this workflow and verify their intended observable behavior." **Expected output**: `status` (`approved`, `stub_detected`, `verification_incomplete`, or `blocked`) diff --git a/dev-workflows-fullstack/skills/recipe-front-adjust/SKILL.md b/dev-workflows-fullstack/skills/recipe-front-adjust/SKILL.md index 51d0fd4..a427a8d 100644 --- a/dev-workflows-fullstack/skills/recipe-front-adjust/SKILL.md +++ b/dev-workflows-fullstack/skills/recipe-front-adjust/SKILL.md @@ -113,6 +113,9 @@ When the project-tier file declares no automated verification mechanism for an a - Invoke **quality-fixer-frontend** using Agent tool - `subagent_type: "dev-workflows-fullstack:quality-fixer-frontend"` - `description: "Quality verification for adjustment unit"` + - `direct_scope`: Copy the current unit's confirmed adjustment request and preserved visible behavior from Step 4 unchanged. + - `governing_sources`: Pass the existing UI and design source references used for this unit unchanged. + - `observable_verification`: Copy the verification criteria used for this unit in Step 5 unchanged. - Pass `qualityCommand` when available (caller first, otherwise current task). - Route the quality-fixer-frontend response by `status`: - `approved` → proceed to Step 7 diff --git a/dev-workflows-fullstack/skills/recipe-front-review/SKILL.md b/dev-workflows-fullstack/skills/recipe-front-review/SKILL.md index 93a1f3a..6189bf5 100644 --- a/dev-workflows-fullstack/skills/recipe-front-review/SKILL.md +++ b/dev-workflows-fullstack/skills/recipe-front-review/SKILL.md @@ -139,8 +139,8 @@ Invoke task-executor-frontend using Agent tool: Invoke quality-fixer-frontend using Agent tool: - `subagent_type`: "dev-workflows-fullstack:quality-fixer-frontend" - `description`: "Quality gate check" +- Copy Step 6 `direct_scope`, `governing_sources`, `observable_verification`, and `correction_findings` inputs unchanged. - Pass Step 6 `mutationEvidence`. -- `prompt`: "Confirm quality gate passage for fixed files." Route the quality-fixer-frontend result: - `approved` → Proceed to Step 8 diff --git a/dev-workflows-fullstack/skills/recipe-implement/SKILL.md b/dev-workflows-fullstack/skills/recipe-implement/SKILL.md index 2a13eb5..e77e482 100644 --- a/dev-workflows-fullstack/skills/recipe-implement/SKILL.md +++ b/dev-workflows-fullstack/skills/recipe-implement/SKILL.md @@ -107,7 +107,7 @@ After Structural Scale is determined, follow only that scale's applicable path. - `blocked` → Apply Specialist Result Acceptance - `needs_revision` → Pass `qualityIssues` unchanged into the Review Resolution Gate; return to step 1 for rerouted corrections and derive convergence from correction re-review `prior_feedback_reconciliation` - Otherwise → Proceed to step 3 -3. quality-fixer → Pass `task_file` when one exists, upstream `mutationEvidence`, and `qualityCommand` when available (caller first, otherwise current task) +3. quality-fixer → Pass `task_file` when one exists; otherwise copy step 1 `direct_scope`, `governing_sources`, and `observable_verification` inputs unchanged, including `correction_findings` when supplied. Add upstream `mutationEvidence` and `qualityCommand` when available (caller first, otherwise current task) - `stub_detected` → Return to step 1 with quality-fixer's `incompleteImplementations` array unchanged as the canonical `incompleteImplementations` field - `blocked` → Apply Specialist Result Acceptance - `verification_incomplete` → Retain the complete result for final retry and proceed to step 4 diff --git a/dev-workflows-fullstack/skills/recipe-review/SKILL.md b/dev-workflows-fullstack/skills/recipe-review/SKILL.md index bfbc64f..81b227e 100644 --- a/dev-workflows-fullstack/skills/recipe-review/SKILL.md +++ b/dev-workflows-fullstack/skills/recipe-review/SKILL.md @@ -139,8 +139,8 @@ Invoke task-executor using Agent tool: Invoke quality-fixer using Agent tool: - `subagent_type`: "dev-workflows-fullstack:quality-fixer" - `description`: "Quality gate check" +- Copy Step 6 `direct_scope`, `governing_sources`, `observable_verification`, and `correction_findings` inputs unchanged. - Pass Step 6 `mutationEvidence`. -- `prompt`: "Confirm quality gate passage for fixed files." Route the quality-fixer result: - `approved` → Proceed to Step 8 diff --git a/dev-workflows-fullstack/skills/subagents-orchestration-guide/SKILL.md b/dev-workflows-fullstack/skills/subagents-orchestration-guide/SKILL.md index 102e99a..a6eb108 100644 --- a/dev-workflows-fullstack/skills/subagents-orchestration-guide/SKILL.md +++ b/dev-workflows-fullstack/skills/subagents-orchestration-guide/SKILL.md @@ -239,7 +239,7 @@ Derive the values from the quality-fixer result. Keep the complete result in orc - `blocked` → Apply Specialist Result Acceptance - `needs_revision` → Pass `qualityIssues` objects unchanged into Review Resolution. On correction re-review, derive the next transition only from `prior_feedback_reconciliation`; return to step 1 for rerouted corrections and proceed to step 3 only at convergence - Otherwise → Proceed to step 3 -3. **Quality-fix**: invoke quality-fixer with upstream `mutationEvidence`, plus `task_file` when available and `qualityCommand` from the caller first or task otherwise +3. **Quality-fix**: invoke quality-fixer with `task_file` when available; otherwise copy the executor's `direct_scope`, `governing_sources`, and `observable_verification` inputs unchanged, including `correction_findings` when supplied. Add upstream `mutationEvidence` and `qualityCommand` from the caller first or task otherwise - `stub_detected` → Return to step 1 with quality-fixer's `incompleteImplementations` array unchanged as the canonical `incompleteImplementations` field - `blocked` → Apply Specialist Result Acceptance - `verification_incomplete` → Retain the complete result for final retry and proceed to step 4 diff --git a/dev-workflows/agents/acceptance-test-generator.md b/dev-workflows/agents/acceptance-test-generator.md index 3db866d..fb07691 100644 --- a/dev-workflows/agents/acceptance-test-generator.md +++ b/dev-workflows/agents/acceptance-test-generator.md @@ -46,12 +46,11 @@ Test type definitions, budgets, and ROI calculations are specified in **integrat | **If-then** | Branch coverage test | Condition true/false → verify both paths | | (none) | Basic functionality test | Direct invocation → verify result | -**For each AC, apply 3 mandatory checks**: +**For each AC, apply these mandatory checks**: | Check | Question | Action if NO | Skip Reason | |-------|----------|--------------|-------------| | **Observable** | Can a user observe this? | Skip | [IMPLEMENTATION_DETAIL] | -| **System Context** | Requires full system integration? | Skip | [UNIT_LEVEL] | | **Upstream Scope** | In Include list? | Skip | [OUT_OF_SCOPE] | **AC Selection Criteria**: diff --git a/dev-workflows/agents/quality-fixer.md b/dev-workflows/agents/quality-fixer.md index 8166886..60be523 100644 --- a/dev-workflows/agents/quality-fixer.md +++ b/dev-workflows/agents/quality-fixer.md @@ -23,9 +23,15 @@ Executes applicable quality checks, fixes in-scope failures, and reports exact p ## Input Parameters - **task_file** (optional): Path to the task file being verified. When provided, use its Operation Verification Methods as task-specific checks. +- **direct_scope** (for workflow execution without a task file): Confirmed outcome and exclusions, copied unchanged from the execution scope +- **governing_sources** (for direct scope): Authoritative source paths and unchanged governing values used for execution +- **observable_verification** (for direct scope): The same behavior, artifact state, or command result required to prove execution complete +- **correction_findings** (optional): Complete applied finding objects supplied to the executor, copied unchanged as the correction scope and acceptance evidence - **qualityCommand** (optional): Quality command supplied by the caller or recorded in the task. Run it first, then cover the remaining applicable check categories. - **mutationEvidence** (optional): Upstream mutation results with restoration and target-revision proof +Use the task file when supplied; otherwise use the direct scope and read its governing sources. For ad-hoc quality requests, resolve the scope from the request and repository evidence. Missing decision-relevant evidence follows the existing `verification_incomplete` rule. + ## Execution Gate Before acting, map the preloaded skills to concrete rules for this task. Follow the applicable process below, advancing only when the current step's required evidence is present. Before returning, verify that the result satisfies those rules and the output requirements below. @@ -34,7 +40,7 @@ Before acting, map the preloaded skills to concrete rules for this task. Follow ### Step 1: Incomplete Implementation Check [BLOCKING — before any quality checks] -Review the current uncommitted changes for incomplete implementation using the current task and repository context. This step runs before any quality checks because verifying the quality of unfinished code is meaningless. +Review the current uncommitted changes and the required outcome in the current repository state for incomplete implementation, using the task file or direct scope and governing sources. Include missing required behavior even when it has no changed file. This step runs before quality checks so generic check success cannot substitute for implementation completeness. Use the indicators below for this review. @@ -54,7 +60,7 @@ Use the indicators below for this review. Run `qualityCommand` first when provided. Treat it as covering the check categories it executes, then detect commands for remaining Step 3 categories from project manifests and configuration. When absent, detect all applicable commands this way. -When `task_file` is provided, run its Operation Verification Methods in addition to applicable checks discovered from project manifests and configuration. +Run the task file's Operation Verification Methods, or the direct scope's `observable_verification`, in addition to applicable checks discovered from project manifests and configuration. Use each supplied success condition to judge its proof. **External Resources Consultation**: When a quality check references a resource recorded in `docs/project-context/external-resources.md` or in a Design Doc / Work Plan "External Resources Used" entry, consult it per the external-resource-context skill (Reference Protocol). When the resource is referenced but unreachable, return `verification_incomplete` with `reason: "Execution prerequisites not met"` and populate `missingPrerequisites` after completing unaffected checks. @@ -84,7 +90,7 @@ Return one of the following as the final response (see Output Format for schemas ## Status Determination Criteria ### stub_detected (Incomplete implementation found — Step 1 gate) -Returned immediately when Step 1 finds incomplete implementations in the diff. Quality checks are not executed. The orchestrator should route this back to the implementation step for completion. +Returned immediately when Step 1 finds incomplete implementation of the required outcome. Quality checks are not executed. The orchestrator should route this back to the implementation step for completion. ### approved (All quality checks pass) - All tests pass @@ -142,7 +148,7 @@ Use this status only after Step 1 confirmed implementation completeness and ever ```json { "status": "stub_detected", - "reason": "Incomplete implementation detected in changed files", + "reason": "Required outcome is not fully implemented", "incompleteImplementations": [ { "file": "path/to/file", diff --git a/dev-workflows/agents/task-executor.md b/dev-workflows/agents/task-executor.md index 0bcc5fa..159ea42 100644 --- a/dev-workflows/agents/task-executor.md +++ b/dev-workflows/agents/task-executor.md @@ -94,7 +94,7 @@ Any YES is corrected in implementation when the value boundary can remain true. ### 1. Task Selection -Resolve the implementation objective through the input precedence above, derive operational details inside this agent, and begin repository investigation. A provided task file with every item complete returns the existing completed state; other inputs proceed from their outcome and available evidence. +Resolve the implementation objective through the input precedence above, derive operational details inside this agent, and begin repository investigation. Completed task checkboxes guide continuation; confirm the outcome against the current repository state and applicable verification evidence before returning an existing completed result. ### 2. Task Background Understanding @@ -152,7 +152,7 @@ When adopting a pattern or dependency from existing code, apply coding-principle #### Implementation Flow (TDD Compliant) -**When the execution scope is supplied as a task file or Work Plan and all relevant checkboxes are already `[x]`**: Report "already completed" and end +**When the outcome is already satisfied**: Preserve the implementation and proceed to Operation Verification before reporting completion. **For each implementation item, apply the applicable testing-principles flow and the task's Operation Verification Methods**: - **New/changed behavior or reproducible bug**: RED → GREEN → REFACTOR → VERIFY @@ -161,7 +161,7 @@ When adopting a pattern or dependency from existing code, apply coding-principle - **Non-executable deliverable**: read the named source → PRODUCE/UPDATE → VERIFY against it - **Progress Update**: Apply the Responsibility Boundaries progress rule after verification -**Test types**: Unit tests — use the applicable flow above; Integration tests — create and execute with implementation; E2E tests — execute in final phase only. +**Test types**: Apply the flow above to unit tests. Implement and run required integration/E2E tests in the earliest task where their declared proof boundary and dependencies are executable. Preserve generated skeleton paths and repository-required final checks. #### Operation Verification - Execute the Operation Verification Methods in the execution instructions @@ -208,7 +208,7 @@ Complete this agent's work by returning the following JSON; the quality assuranc "requiresTestReview": true, "newTestsPassed": true, "reuseDecisions": [{"candidate": "[path:symbol]", "decision": "reuse | extend | separate", "evidence": "[Responsibility, contract, lifecycle, and repository-representativeness evidence]"}], - "runnableCheck": {"level": "L1: Unit test / L2: Integration test / L3: E2E test", "executed": true, "command": "Executed test command", "result": "passed / failed / skipped", "reason": "Test execution reason/verification content"}, + "runnableCheck": {"level": "L1: Functional Operation Verification / L2: Test Operation Verification / L3: Build Success Verification", "executed": true, "command": "Executed verification command", "result": "passed / failed / skipped", "reason": "Verification content or exact limitation"}, "mutationEvidence": [{"mutation": "[description or patch]", "killedTest": "[test name]", "baselineResult": "[baseline command and result]", "mutatedResult": "[mutated command and result]", "restorationProof": "[restoration checksum or clean diff]", "targetRevision": "[revision or file hashes]"}] } ``` diff --git a/dev-workflows/agents/work-planner.md b/dev-workflows/agents/work-planner.md index 3a2bdad..ac95669 100644 --- a/dev-workflows/agents/work-planner.md +++ b/dev-workflows/agents/work-planner.md @@ -59,7 +59,7 @@ Apply the Design Doc's implementation approach and dependency order. 1. Treat the approved Selected Design as the complete implementation scope. 2. Group source, tests, repository configuration, wiring, and documentation that become complete at the same observable verification point. 3. Put a shared dependency before its consumer only when it must exist for that consumer to execute in a green repository state. -4. Use each skeleton's `@lane` as its placement rule: assign `integration` to the earliest task where its declared boundary becomes executable, `fixture-e2e` alongside the owning UI feature, and `service-integration-e2e` to the final implementation phase after its services are executable. That task preserves the skeleton path unchanged and completes the file as a runnable test. +4. Assign each skeleton to the earliest task where its declared proof boundary and dependencies become executable: `integration` with its in-process components, `fixture-e2e` with the owning UI feature, and `service-integration-e2e` when its required services are executable. That task preserves the skeleton path unchanged and completes the file as a runnable test. 5. Repeat until every implementation obligation is covered. Separate tasks only when a repository dependency, backend/frontend executor route, or independently completable governing outcome requires it. diff --git a/dev-workflows/skills/documentation-criteria/references/task-template.md b/dev-workflows/skills/documentation-criteria/references/task-template.md index 7af5917..a5292fd 100644 --- a/dev-workflows/skills/documentation-criteria/references/task-template.md +++ b/dev-workflows/skills/documentation-criteria/references/task-template.md @@ -46,7 +46,7 @@ Read the smallest representative set needed to implement the task: - **Verification method**: [Governing verification method or repository command] - **Success criteria**: [Observable result tied to cited ACs] -- **Verification level**: [L1 unit/local | L2 integration | L3 end-to-end] +- **Verification level**: [L1 functional operation | L2 passing tests | L3 successful build — per implementation-approach] ## Verification Focus diff --git a/dev-workflows/skills/integration-e2e-testing/SKILL.md b/dev-workflows/skills/integration-e2e-testing/SKILL.md index cfaa43c..f04bbbd 100644 --- a/dev-workflows/skills/integration-e2e-testing/SKILL.md +++ b/dev-workflows/skills/integration-e2e-testing/SKILL.md @@ -15,7 +15,7 @@ description: Integration and E2E test design principles, ROI calculation, test s |-----------|---------|-------|---------------|-------------------|----------------------| | Integration | Verify component interactions in-process | Partial system integration (in-process modules; for UI components, the framework's in-process renderer e.g., RTL+MSW for React/TS) | Mocked or in-process | MAX 3 | Created alongside implementation | | fixture-e2e | Verify UI behavior in a browser with deterministic fixtures | Full UI flow with mocked backend / fixture-driven state | Mocked / fixture only — no live services | MAX 3 | Created alongside the UI feature | -| service-integration-e2e | Verify critical user journeys against a running local stack | Full system across services | Live local services or stubs | MAX 1-2 | Executed only in the final phase | +| service-integration-e2e | Verify critical user journeys against a running local stack | Full system across services | Live local services or stubs | MAX 1-2 | Earliest task where the proof boundary and required services are executable | **Lane selection (E2E only)**: - Default lane for user-facing UI journeys is **fixture-e2e** — it runs a real browser against deterministic fixtures, catches the bugs that unit/integration tests miss (button no-op, state never updates, navigation breaks), and runs in CI without infrastructure setup diff --git a/dev-workflows/skills/recipe-add-integration-tests/SKILL.md b/dev-workflows/skills/recipe-add-integration-tests/SKILL.md index e022bce..cc2f9d2 100644 --- a/dev-workflows/skills/recipe-add-integration-tests/SKILL.md +++ b/dev-workflows/skills/recipe-add-integration-tests/SKILL.md @@ -112,8 +112,9 @@ Invoke quality-fixer for the current layer: - Backend or single-layer → `subagent_type`: "dev-workflows:quality-fixer" - Frontend → `subagent_type`: "dev-workflows-frontend:quality-fixer-frontend" - `description`: "Final quality assurance" +- Copy Step 3 `direct_scope`, `governing_sources`, and `observable_verification` inputs unchanged. +- Include the latest executor's `correction_findings` input unchanged when supplied. - Pass the latest executor's `mutationEvidence`. -- `prompt`: "Run the repository-configured quality checks applicable to the test files added in this workflow and verify their intended observable behavior." **Expected output**: `status` (`approved`, `stub_detected`, `verification_incomplete`, or `blocked`) diff --git a/dev-workflows/skills/recipe-implement/SKILL.md b/dev-workflows/skills/recipe-implement/SKILL.md index b7d4ee5..2adc8ce 100644 --- a/dev-workflows/skills/recipe-implement/SKILL.md +++ b/dev-workflows/skills/recipe-implement/SKILL.md @@ -107,7 +107,7 @@ After Structural Scale is determined, follow only that scale's applicable path. - `blocked` → Apply Specialist Result Acceptance - `needs_revision` → Pass `qualityIssues` unchanged into the Review Resolution Gate; return to step 1 for rerouted corrections and derive convergence from correction re-review `prior_feedback_reconciliation` - Otherwise → Proceed to step 3 -3. quality-fixer → Pass `task_file` when one exists, upstream `mutationEvidence`, and `qualityCommand` when available (caller first, otherwise current task) +3. quality-fixer → Pass `task_file` when one exists; otherwise copy step 1 `direct_scope`, `governing_sources`, and `observable_verification` inputs unchanged, including `correction_findings` when supplied. Add upstream `mutationEvidence` and `qualityCommand` when available (caller first, otherwise current task) - `stub_detected` → Return to step 1 with quality-fixer's `incompleteImplementations` array unchanged as the canonical `incompleteImplementations` field - `blocked` → Apply Specialist Result Acceptance - `verification_incomplete` → Retain the complete result for final retry and proceed to step 4 diff --git a/dev-workflows/skills/recipe-review/SKILL.md b/dev-workflows/skills/recipe-review/SKILL.md index 0577aef..f15671c 100644 --- a/dev-workflows/skills/recipe-review/SKILL.md +++ b/dev-workflows/skills/recipe-review/SKILL.md @@ -139,8 +139,8 @@ Invoke task-executor using Agent tool: Invoke quality-fixer using Agent tool: - `subagent_type`: "dev-workflows:quality-fixer" - `description`: "Quality gate check" +- Copy Step 6 `direct_scope`, `governing_sources`, `observable_verification`, and `correction_findings` inputs unchanged. - Pass Step 6 `mutationEvidence`. -- `prompt`: "Confirm quality gate passage for fixed files." Route the quality-fixer result: - `approved` → Proceed to Step 8 diff --git a/dev-workflows/skills/subagents-orchestration-guide/SKILL.md b/dev-workflows/skills/subagents-orchestration-guide/SKILL.md index 102e99a..a6eb108 100644 --- a/dev-workflows/skills/subagents-orchestration-guide/SKILL.md +++ b/dev-workflows/skills/subagents-orchestration-guide/SKILL.md @@ -239,7 +239,7 @@ Derive the values from the quality-fixer result. Keep the complete result in orc - `blocked` → Apply Specialist Result Acceptance - `needs_revision` → Pass `qualityIssues` objects unchanged into Review Resolution. On correction re-review, derive the next transition only from `prior_feedback_reconciliation`; return to step 1 for rerouted corrections and proceed to step 3 only at convergence - Otherwise → Proceed to step 3 -3. **Quality-fix**: invoke quality-fixer with upstream `mutationEvidence`, plus `task_file` when available and `qualityCommand` from the caller first or task otherwise +3. **Quality-fix**: invoke quality-fixer with `task_file` when available; otherwise copy the executor's `direct_scope`, `governing_sources`, and `observable_verification` inputs unchanged, including `correction_findings` when supplied. Add upstream `mutationEvidence` and `qualityCommand` from the caller first or task otherwise - `stub_detected` → Return to step 1 with quality-fixer's `incompleteImplementations` array unchanged as the canonical `incompleteImplementations` field - `blocked` → Apply Specialist Result Acceptance - `verification_incomplete` → Retain the complete result for final retry and proceed to step 4 diff --git a/skills/documentation-criteria/references/task-template.md b/skills/documentation-criteria/references/task-template.md index 7af5917..a5292fd 100644 --- a/skills/documentation-criteria/references/task-template.md +++ b/skills/documentation-criteria/references/task-template.md @@ -46,7 +46,7 @@ Read the smallest representative set needed to implement the task: - **Verification method**: [Governing verification method or repository command] - **Success criteria**: [Observable result tied to cited ACs] -- **Verification level**: [L1 unit/local | L2 integration | L3 end-to-end] +- **Verification level**: [L1 functional operation | L2 passing tests | L3 successful build — per implementation-approach] ## Verification Focus diff --git a/skills/integration-e2e-testing/SKILL.md b/skills/integration-e2e-testing/SKILL.md index cfaa43c..f04bbbd 100644 --- a/skills/integration-e2e-testing/SKILL.md +++ b/skills/integration-e2e-testing/SKILL.md @@ -15,7 +15,7 @@ description: Integration and E2E test design principles, ROI calculation, test s |-----------|---------|-------|---------------|-------------------|----------------------| | Integration | Verify component interactions in-process | Partial system integration (in-process modules; for UI components, the framework's in-process renderer e.g., RTL+MSW for React/TS) | Mocked or in-process | MAX 3 | Created alongside implementation | | fixture-e2e | Verify UI behavior in a browser with deterministic fixtures | Full UI flow with mocked backend / fixture-driven state | Mocked / fixture only — no live services | MAX 3 | Created alongside the UI feature | -| service-integration-e2e | Verify critical user journeys against a running local stack | Full system across services | Live local services or stubs | MAX 1-2 | Executed only in the final phase | +| service-integration-e2e | Verify critical user journeys against a running local stack | Full system across services | Live local services or stubs | MAX 1-2 | Earliest task where the proof boundary and required services are executable | **Lane selection (E2E only)**: - Default lane for user-facing UI journeys is **fixture-e2e** — it runs a real browser against deterministic fixtures, catches the bugs that unit/integration tests miss (button no-op, state never updates, navigation breaks), and runs in CI without infrastructure setup diff --git a/skills/recipe-add-integration-tests/SKILL.md b/skills/recipe-add-integration-tests/SKILL.md index e022bce..cc2f9d2 100644 --- a/skills/recipe-add-integration-tests/SKILL.md +++ b/skills/recipe-add-integration-tests/SKILL.md @@ -112,8 +112,9 @@ Invoke quality-fixer for the current layer: - Backend or single-layer → `subagent_type`: "dev-workflows:quality-fixer" - Frontend → `subagent_type`: "dev-workflows-frontend:quality-fixer-frontend" - `description`: "Final quality assurance" +- Copy Step 3 `direct_scope`, `governing_sources`, and `observable_verification` inputs unchanged. +- Include the latest executor's `correction_findings` input unchanged when supplied. - Pass the latest executor's `mutationEvidence`. -- `prompt`: "Run the repository-configured quality checks applicable to the test files added in this workflow and verify their intended observable behavior." **Expected output**: `status` (`approved`, `stub_detected`, `verification_incomplete`, or `blocked`) diff --git a/skills/recipe-front-adjust/SKILL.md b/skills/recipe-front-adjust/SKILL.md index 8d4b192..dbec52f 100644 --- a/skills/recipe-front-adjust/SKILL.md +++ b/skills/recipe-front-adjust/SKILL.md @@ -113,6 +113,9 @@ When the project-tier file declares no automated verification mechanism for an a - Invoke **quality-fixer-frontend** using Agent tool - `subagent_type: "dev-workflows-frontend:quality-fixer-frontend"` - `description: "Quality verification for adjustment unit"` + - `direct_scope`: Copy the current unit's confirmed adjustment request and preserved visible behavior from Step 4 unchanged. + - `governing_sources`: Pass the existing UI and design source references used for this unit unchanged. + - `observable_verification`: Copy the verification criteria used for this unit in Step 5 unchanged. - Pass `qualityCommand` when available (caller first, otherwise current task). - Route the quality-fixer-frontend response by `status`: - `approved` → proceed to Step 7 diff --git a/skills/recipe-front-review/SKILL.md b/skills/recipe-front-review/SKILL.md index eec0dff..fea8c04 100644 --- a/skills/recipe-front-review/SKILL.md +++ b/skills/recipe-front-review/SKILL.md @@ -139,8 +139,8 @@ Invoke task-executor-frontend using Agent tool: Invoke quality-fixer-frontend using Agent tool: - `subagent_type`: "dev-workflows-frontend:quality-fixer-frontend" - `description`: "Quality gate check" +- Copy Step 6 `direct_scope`, `governing_sources`, `observable_verification`, and `correction_findings` inputs unchanged. - Pass Step 6 `mutationEvidence`. -- `prompt`: "Confirm quality gate passage for fixed files." Route the quality-fixer-frontend result: - `approved` → Proceed to Step 8 diff --git a/skills/recipe-implement/SKILL.md b/skills/recipe-implement/SKILL.md index b7d4ee5..2adc8ce 100644 --- a/skills/recipe-implement/SKILL.md +++ b/skills/recipe-implement/SKILL.md @@ -107,7 +107,7 @@ After Structural Scale is determined, follow only that scale's applicable path. - `blocked` → Apply Specialist Result Acceptance - `needs_revision` → Pass `qualityIssues` unchanged into the Review Resolution Gate; return to step 1 for rerouted corrections and derive convergence from correction re-review `prior_feedback_reconciliation` - Otherwise → Proceed to step 3 -3. quality-fixer → Pass `task_file` when one exists, upstream `mutationEvidence`, and `qualityCommand` when available (caller first, otherwise current task) +3. quality-fixer → Pass `task_file` when one exists; otherwise copy step 1 `direct_scope`, `governing_sources`, and `observable_verification` inputs unchanged, including `correction_findings` when supplied. Add upstream `mutationEvidence` and `qualityCommand` when available (caller first, otherwise current task) - `stub_detected` → Return to step 1 with quality-fixer's `incompleteImplementations` array unchanged as the canonical `incompleteImplementations` field - `blocked` → Apply Specialist Result Acceptance - `verification_incomplete` → Retain the complete result for final retry and proceed to step 4 diff --git a/skills/recipe-review/SKILL.md b/skills/recipe-review/SKILL.md index 0577aef..f15671c 100644 --- a/skills/recipe-review/SKILL.md +++ b/skills/recipe-review/SKILL.md @@ -139,8 +139,8 @@ Invoke task-executor using Agent tool: Invoke quality-fixer using Agent tool: - `subagent_type`: "dev-workflows:quality-fixer" - `description`: "Quality gate check" +- Copy Step 6 `direct_scope`, `governing_sources`, `observable_verification`, and `correction_findings` inputs unchanged. - Pass Step 6 `mutationEvidence`. -- `prompt`: "Confirm quality gate passage for fixed files." Route the quality-fixer result: - `approved` → Proceed to Step 8 diff --git a/skills/subagents-orchestration-guide/SKILL.md b/skills/subagents-orchestration-guide/SKILL.md index 102e99a..a6eb108 100644 --- a/skills/subagents-orchestration-guide/SKILL.md +++ b/skills/subagents-orchestration-guide/SKILL.md @@ -239,7 +239,7 @@ Derive the values from the quality-fixer result. Keep the complete result in orc - `blocked` → Apply Specialist Result Acceptance - `needs_revision` → Pass `qualityIssues` objects unchanged into Review Resolution. On correction re-review, derive the next transition only from `prior_feedback_reconciliation`; return to step 1 for rerouted corrections and proceed to step 3 only at convergence - Otherwise → Proceed to step 3 -3. **Quality-fix**: invoke quality-fixer with upstream `mutationEvidence`, plus `task_file` when available and `qualityCommand` from the caller first or task otherwise +3. **Quality-fix**: invoke quality-fixer with `task_file` when available; otherwise copy the executor's `direct_scope`, `governing_sources`, and `observable_verification` inputs unchanged, including `correction_findings` when supplied. Add upstream `mutationEvidence` and `qualityCommand` from the caller first or task otherwise - `stub_detected` → Return to step 1 with quality-fixer's `incompleteImplementations` array unchanged as the canonical `incompleteImplementations` field - `blocked` → Apply Specialist Result Acceptance - `verification_incomplete` → Retain the complete result for final retry and proceed to step 4 From 70fc84a0a20c6350a7f908744190f7abaa8cacad Mon Sep 17 00:00:00 2001 From: Shinsuke Kagawa Date: Sat, 5 Sep 2026 16:18:54 +0900 Subject: [PATCH 2/3] fix: verify frontend adjustments by confirmed outcome --- agents/quality-fixer-frontend.md | 2 + agents/quality-fixer.md | 2 + agents/ui-spec-designer.md | 2 +- .../agents/quality-fixer-frontend.md | 2 + .../agents/ui-spec-designer.md | 2 +- .../skills/recipe-front-adjust/SKILL.md | 40 +++++++++---------- .../agents/quality-fixer-frontend.md | 2 + .../agents/quality-fixer.md | 2 + .../agents/ui-spec-designer.md | 2 +- .../skills/recipe-front-adjust/SKILL.md | 40 +++++++++---------- dev-workflows/agents/quality-fixer.md | 2 + skills/recipe-front-adjust/SKILL.md | 40 +++++++++---------- 12 files changed, 72 insertions(+), 66 deletions(-) diff --git a/agents/quality-fixer-frontend.md b/agents/quality-fixer-frontend.md index 74efec1..101d6d8 100644 --- a/agents/quality-fixer-frontend.md +++ b/agents/quality-fixer-frontend.md @@ -173,6 +173,8 @@ Use this status only after Step 1 confirmed implementation completeness and ever ``` **stub_detected response format (incomplete implementation)**: +Use `null` for `file` or `location` when no corresponding file or code location exists; describe the missing required behavior in `description`. + ```json { "status": "stub_detected", diff --git a/agents/quality-fixer.md b/agents/quality-fixer.md index 60be523..b07f213 100644 --- a/agents/quality-fixer.md +++ b/agents/quality-fixer.md @@ -145,6 +145,8 @@ Use this status only after Step 1 confirmed implementation completeness and ever ``` **stub_detected response format (incomplete implementation)**: +Use `null` for `file` or `location` when no corresponding file or code location exists; describe the missing required behavior in `description`. + ```json { "status": "stub_detected", diff --git a/agents/ui-spec-designer.md b/agents/ui-spec-designer.md index d5fe76b..07be1bf 100644 --- a/agents/ui-spec-designer.md +++ b/agents/ui-spec-designer.md @@ -31,7 +31,7 @@ Before acting, map the preloaded skills to concrete rules for this task. Follow - **ui_analysis**: UI analyzer JSON for existing UI behavior and external evidence (required) - **codebase_analysis**: Applicable codebase-analyzer evidence (optional) - **prototype_path**: Decision-relevant prototype path (optional, placed in `docs/ui-spec/assets/{feature-name}/`) -- **prototype_reference_strength**: `binding` or `reference`, accompanying `prototype_path` +- **prototype_reference_strength**: `binding` or `reference`, accompanying `prototype_path`. When a prototype is provided without a strength, use the confirmed requirement context if it establishes the strength; otherwise record the unresolved strength in Prototype Management and the existing decision-blocking Open Items, and continue work independent of that decision. - **external_resource_refs**: Selected external-resource records or an empty array (optional) ## Mandatory Process Before UI Spec Creation diff --git a/dev-workflows-frontend/agents/quality-fixer-frontend.md b/dev-workflows-frontend/agents/quality-fixer-frontend.md index 74efec1..101d6d8 100644 --- a/dev-workflows-frontend/agents/quality-fixer-frontend.md +++ b/dev-workflows-frontend/agents/quality-fixer-frontend.md @@ -173,6 +173,8 @@ Use this status only after Step 1 confirmed implementation completeness and ever ``` **stub_detected response format (incomplete implementation)**: +Use `null` for `file` or `location` when no corresponding file or code location exists; describe the missing required behavior in `description`. + ```json { "status": "stub_detected", diff --git a/dev-workflows-frontend/agents/ui-spec-designer.md b/dev-workflows-frontend/agents/ui-spec-designer.md index d5fe76b..07be1bf 100644 --- a/dev-workflows-frontend/agents/ui-spec-designer.md +++ b/dev-workflows-frontend/agents/ui-spec-designer.md @@ -31,7 +31,7 @@ Before acting, map the preloaded skills to concrete rules for this task. Follow - **ui_analysis**: UI analyzer JSON for existing UI behavior and external evidence (required) - **codebase_analysis**: Applicable codebase-analyzer evidence (optional) - **prototype_path**: Decision-relevant prototype path (optional, placed in `docs/ui-spec/assets/{feature-name}/`) -- **prototype_reference_strength**: `binding` or `reference`, accompanying `prototype_path` +- **prototype_reference_strength**: `binding` or `reference`, accompanying `prototype_path`. When a prototype is provided without a strength, use the confirmed requirement context if it establishes the strength; otherwise record the unresolved strength in Prototype Management and the existing decision-blocking Open Items, and continue work independent of that decision. - **external_resource_refs**: Selected external-resource records or an empty array (optional) ## Mandatory Process Before UI Spec Creation diff --git a/dev-workflows-frontend/skills/recipe-front-adjust/SKILL.md b/dev-workflows-frontend/skills/recipe-front-adjust/SKILL.md index dbec52f..0f06833 100644 --- a/dev-workflows-frontend/skills/recipe-front-adjust/SKILL.md +++ b/dev-workflows-frontend/skills/recipe-front-adjust/SKILL.md @@ -21,7 +21,7 @@ Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or g ## Execution Gate -Complete Steps 1-7 in order for each adjustment unit. Advance only through the current step's stated evidence, quality result, or user stop; skip work only when its stated condition is false. Report completion after every applicable Completion Criterion and retained-limitation retry is satisfied. +Complete Steps 1-7 in order for the confirmed adjustment outcome. Advance only through the current step's stated evidence, quality result, or user stop; skip work only when its stated condition is false. Report completion after every applicable Completion Criterion and retained-limitation retry is satisfied. ## Workflow Overview @@ -49,9 +49,9 @@ Adjustment request → conditional external resource evidence - Structural boundary judgment via documentation-criteria - Adjustment edits and verification against the design source (run in this session) - Quality verification via quality-fixer-frontend -- Commit per adjustment unit +- Commit the confirmed adjustment outcome -**Responsibility Boundary**: This skill completes when each adjustment is committed after its quality cycle and any retained proof limitation receives its final retry. Adjustment work is end-to-end within this recipe; parent session owns edits, verification loops, quality-result routing, and commits. +**Responsibility Boundary**: This skill completes when the confirmed adjustment is committed after its quality cycle and any retained proof limitation receives its final retry. Adjustment work is end-to-end within this recipe; parent session owns edits, verification loops, quality-result routing, and commits. **Escalation Boundary**: Escalate to the full frontend design phase when the request crosses a responsibility or approved UI boundary, requires a complete Design Doc, or contains a technical choice that passes documentation-criteria's Choice and Durability filters. @@ -96,7 +96,7 @@ Execute Skill: typescript-rules before planning or applying adjustment edits. Execute Skill: implementation-approach before planning or applying adjustment edits. Execute Skill: test-implement before adding or changing tests. -For each file in the confirmed adjustment context: +Implement the confirmed adjustment outcome across its affected files: 1. **Plan the edit** from the confirmed adjustment context and relevant external resource (e.g., design origin's fetched_summary). 2. **Apply the edit** using Edit / Write / MultiEdit on the affected files. 3. **Verify against external sources** using whichever access method `docs/project-context/external-resources.md` declares for each axis: @@ -104,33 +104,31 @@ For each file in the confirmed adjustment context: - Visual rendering: capture screenshot or run a smoke check via the declared visual verification method (e.g., browser MCP, E2E test runner CLI invoked via Bash, dev-server URL inspection, Storybook URL) - Design system tokens / variants: confirm against the declared design system source (e.g., design-system MCP, package import, Storybook URL, internal documentation path) 4. **Refine and re-verify** until the adjustment matches the design source, or matches the user-confirmed adjustment target when no separate design source exists. -5. When the adjustment unit converges, proceed to Step 6 for that unit. +5. When the complete adjustment matches the confirmed target, proceed to Step 6. When the project-tier file declares no automated verification mechanism for an axis, ask the user to confirm the result manually, or use file-based comparison when a specification file is available. -### Step 6: Quality Verification (per adjustment unit) +### Step 6: Quality Verification - Invoke **quality-fixer-frontend** using Agent tool - `subagent_type: "dev-workflows-frontend:quality-fixer-frontend"` - - `description: "Quality verification for adjustment unit"` - - `direct_scope`: Copy the current unit's confirmed adjustment request and preserved visible behavior from Step 4 unchanged. - - `governing_sources`: Pass the existing UI and design source references used for this unit unchanged. - - `observable_verification`: Copy the verification criteria used for this unit in Step 5 unchanged. + - `description: "Quality verification for confirmed adjustment"` + - `direct_scope`: Copy the confirmed adjustment request and preserved visible behavior from Step 4 unchanged. + - `governing_sources`: Pass the existing UI and design source references used for the adjustment unchanged. + - `observable_verification`: Pass the confirmed adjustment request from Step 4 and applicable acceptance criteria from the governing sources unchanged. - Pass `qualityCommand` when available (caller first, otherwise current task). - Route the quality-fixer-frontend response by `status`: - `approved` → proceed to Step 7 - - `stub_detected` → return to Step 5 to complete the implementation for this unit, then re-invoke quality-fixer-frontend + - `stub_detected` → return to Step 5 to complete the confirmed adjustment, then re-invoke quality-fixer-frontend - `verification_incomplete` → retain the complete result for final retry and proceed to Step 7 - `blocked` → Apply subagents-orchestration-guide Specialist Result Acceptance using the result's semantic evidence, changed files, and repository state -### Step 7: Commit (per adjustment unit) -Before committing, use repository state at the commit boundary as the primary evidence and account for every actual change by mapping it to the confirmed adjustment, preserved pattern, or a necessary dependency, test, or generated artifact. Every required change is ready for the unit commit, accidental changes introduced during the unit are removed, and existing worktree changes unrelated to the confirmed adjustment remain intact. +### Step 7: Commit +Before committing, use repository state at the commit boundary as the primary evidence and account for every actual change by mapping it to the confirmed adjustment, preserved pattern, or a necessary dependency, test, or generated artifact. Every required change is ready for the adjustment commit, accidental changes introduced during the adjustment are removed, and existing worktree changes unrelated to the confirmed adjustment remain intact. -Commit the adjustment unit after `approved` or `verification_incomplete`. For the latter, derive and append one `Verification-Limitation: ` and `Verification-Affected: ` trailer pair per retained limitation. +Commit the confirmed adjustment after `approved` or `verification_incomplete`. For the latter, derive and append one `Verification-Limitation: ` and `Verification-Affected: ` trailer pair per retained limitation. -Then loop back to Step 5 for the next file until all units are committed. - -On continuation, reconstruct retained limitations from the verification trailers on adjustment-unit commits already completed for this request. After all units are committed, retry each retained verification limitation once with quality-fixer-frontend. Clear an `approved` result, commit any resulting fixes through Steps 6→7, and include only a repeated limitation in the completion report. +On continuation, reconstruct retained limitations from the verification trailers on commits already completed for this request. After the adjustment is committed, retry each retained verification limitation once with quality-fixer-frontend. Clear an `approved` result, commit any resulting fixes through Steps 6→7, and include only a repeated limitation in the completion report. ## Completion Criteria @@ -138,9 +136,9 @@ On continuation, reconstruct retained limitations from the verification trailers - [ ] UI Spec applicability and the candidate write set were determined from the requested UI and sufficient repository evidence - [ ] Structural boundary judgment applied; changes requiring complete design or a qualifying durable decision escalated - [ ] Adjustment context, including the affected files, was presented and confirmed once -- [ ] All adjustment units edited; each declared verification mechanism ran, received manual confirmation where required, or retained its exact proof limitation after final retry -- [ ] Each adjustment unit completed quality-fixer-frontend before commit; retained proof limitations were retried and reported -- [ ] Each adjustment unit committed +- [ ] The confirmed adjustment outcome is implemented; each declared verification mechanism ran, received manual confirmation where required, or retained its exact proof limitation after final retry +- [ ] The confirmed adjustment completed quality-fixer-frontend before commit; retained proof limitations were retried and reported +- [ ] The confirmed adjustment is committed ## Output Example @@ -149,6 +147,6 @@ Frontend adjustment completed. - External resources: docs/project-context/external-resources.md (updated|unchanged) - UI evidence: existing pattern [path], external sources [fetched|partial|not_recorded] - Scale: direct existing-pattern adjustment -- Adjustment units committed: [count] +- Adjustment commit: [commit hash] - Quality status: all passed | [remaining proof limitations] ``` diff --git a/dev-workflows-fullstack/agents/quality-fixer-frontend.md b/dev-workflows-fullstack/agents/quality-fixer-frontend.md index 74efec1..101d6d8 100644 --- a/dev-workflows-fullstack/agents/quality-fixer-frontend.md +++ b/dev-workflows-fullstack/agents/quality-fixer-frontend.md @@ -173,6 +173,8 @@ Use this status only after Step 1 confirmed implementation completeness and ever ``` **stub_detected response format (incomplete implementation)**: +Use `null` for `file` or `location` when no corresponding file or code location exists; describe the missing required behavior in `description`. + ```json { "status": "stub_detected", diff --git a/dev-workflows-fullstack/agents/quality-fixer.md b/dev-workflows-fullstack/agents/quality-fixer.md index 60be523..b07f213 100644 --- a/dev-workflows-fullstack/agents/quality-fixer.md +++ b/dev-workflows-fullstack/agents/quality-fixer.md @@ -145,6 +145,8 @@ Use this status only after Step 1 confirmed implementation completeness and ever ``` **stub_detected response format (incomplete implementation)**: +Use `null` for `file` or `location` when no corresponding file or code location exists; describe the missing required behavior in `description`. + ```json { "status": "stub_detected", diff --git a/dev-workflows-fullstack/agents/ui-spec-designer.md b/dev-workflows-fullstack/agents/ui-spec-designer.md index d5fe76b..07be1bf 100644 --- a/dev-workflows-fullstack/agents/ui-spec-designer.md +++ b/dev-workflows-fullstack/agents/ui-spec-designer.md @@ -31,7 +31,7 @@ Before acting, map the preloaded skills to concrete rules for this task. Follow - **ui_analysis**: UI analyzer JSON for existing UI behavior and external evidence (required) - **codebase_analysis**: Applicable codebase-analyzer evidence (optional) - **prototype_path**: Decision-relevant prototype path (optional, placed in `docs/ui-spec/assets/{feature-name}/`) -- **prototype_reference_strength**: `binding` or `reference`, accompanying `prototype_path` +- **prototype_reference_strength**: `binding` or `reference`, accompanying `prototype_path`. When a prototype is provided without a strength, use the confirmed requirement context if it establishes the strength; otherwise record the unresolved strength in Prototype Management and the existing decision-blocking Open Items, and continue work independent of that decision. - **external_resource_refs**: Selected external-resource records or an empty array (optional) ## Mandatory Process Before UI Spec Creation diff --git a/dev-workflows-fullstack/skills/recipe-front-adjust/SKILL.md b/dev-workflows-fullstack/skills/recipe-front-adjust/SKILL.md index a427a8d..eb59c01 100644 --- a/dev-workflows-fullstack/skills/recipe-front-adjust/SKILL.md +++ b/dev-workflows-fullstack/skills/recipe-front-adjust/SKILL.md @@ -21,7 +21,7 @@ Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or g ## Execution Gate -Complete Steps 1-7 in order for each adjustment unit. Advance only through the current step's stated evidence, quality result, or user stop; skip work only when its stated condition is false. Report completion after every applicable Completion Criterion and retained-limitation retry is satisfied. +Complete Steps 1-7 in order for the confirmed adjustment outcome. Advance only through the current step's stated evidence, quality result, or user stop; skip work only when its stated condition is false. Report completion after every applicable Completion Criterion and retained-limitation retry is satisfied. ## Workflow Overview @@ -49,9 +49,9 @@ Adjustment request → conditional external resource evidence - Structural boundary judgment via documentation-criteria - Adjustment edits and verification against the design source (run in this session) - Quality verification via quality-fixer-frontend -- Commit per adjustment unit +- Commit the confirmed adjustment outcome -**Responsibility Boundary**: This skill completes when each adjustment is committed after its quality cycle and any retained proof limitation receives its final retry. Adjustment work is end-to-end within this recipe; parent session owns edits, verification loops, quality-result routing, and commits. +**Responsibility Boundary**: This skill completes when the confirmed adjustment is committed after its quality cycle and any retained proof limitation receives its final retry. Adjustment work is end-to-end within this recipe; parent session owns edits, verification loops, quality-result routing, and commits. **Escalation Boundary**: Escalate to the full frontend design phase when the request crosses a responsibility or approved UI boundary, requires a complete Design Doc, or contains a technical choice that passes documentation-criteria's Choice and Durability filters. @@ -96,7 +96,7 @@ Execute Skill: typescript-rules before planning or applying adjustment edits. Execute Skill: implementation-approach before planning or applying adjustment edits. Execute Skill: test-implement before adding or changing tests. -For each file in the confirmed adjustment context: +Implement the confirmed adjustment outcome across its affected files: 1. **Plan the edit** from the confirmed adjustment context and relevant external resource (e.g., design origin's fetched_summary). 2. **Apply the edit** using Edit / Write / MultiEdit on the affected files. 3. **Verify against external sources** using whichever access method `docs/project-context/external-resources.md` declares for each axis: @@ -104,33 +104,31 @@ For each file in the confirmed adjustment context: - Visual rendering: capture screenshot or run a smoke check via the declared visual verification method (e.g., browser MCP, E2E test runner CLI invoked via Bash, dev-server URL inspection, Storybook URL) - Design system tokens / variants: confirm against the declared design system source (e.g., design-system MCP, package import, Storybook URL, internal documentation path) 4. **Refine and re-verify** until the adjustment matches the design source, or matches the user-confirmed adjustment target when no separate design source exists. -5. When the adjustment unit converges, proceed to Step 6 for that unit. +5. When the complete adjustment matches the confirmed target, proceed to Step 6. When the project-tier file declares no automated verification mechanism for an axis, ask the user to confirm the result manually, or use file-based comparison when a specification file is available. -### Step 6: Quality Verification (per adjustment unit) +### Step 6: Quality Verification - Invoke **quality-fixer-frontend** using Agent tool - `subagent_type: "dev-workflows-fullstack:quality-fixer-frontend"` - - `description: "Quality verification for adjustment unit"` - - `direct_scope`: Copy the current unit's confirmed adjustment request and preserved visible behavior from Step 4 unchanged. - - `governing_sources`: Pass the existing UI and design source references used for this unit unchanged. - - `observable_verification`: Copy the verification criteria used for this unit in Step 5 unchanged. + - `description: "Quality verification for confirmed adjustment"` + - `direct_scope`: Copy the confirmed adjustment request and preserved visible behavior from Step 4 unchanged. + - `governing_sources`: Pass the existing UI and design source references used for the adjustment unchanged. + - `observable_verification`: Pass the confirmed adjustment request from Step 4 and applicable acceptance criteria from the governing sources unchanged. - Pass `qualityCommand` when available (caller first, otherwise current task). - Route the quality-fixer-frontend response by `status`: - `approved` → proceed to Step 7 - - `stub_detected` → return to Step 5 to complete the implementation for this unit, then re-invoke quality-fixer-frontend + - `stub_detected` → return to Step 5 to complete the confirmed adjustment, then re-invoke quality-fixer-frontend - `verification_incomplete` → retain the complete result for final retry and proceed to Step 7 - `blocked` → Apply subagents-orchestration-guide Specialist Result Acceptance using the result's semantic evidence, changed files, and repository state -### Step 7: Commit (per adjustment unit) -Before committing, use repository state at the commit boundary as the primary evidence and account for every actual change by mapping it to the confirmed adjustment, preserved pattern, or a necessary dependency, test, or generated artifact. Every required change is ready for the unit commit, accidental changes introduced during the unit are removed, and existing worktree changes unrelated to the confirmed adjustment remain intact. +### Step 7: Commit +Before committing, use repository state at the commit boundary as the primary evidence and account for every actual change by mapping it to the confirmed adjustment, preserved pattern, or a necessary dependency, test, or generated artifact. Every required change is ready for the adjustment commit, accidental changes introduced during the adjustment are removed, and existing worktree changes unrelated to the confirmed adjustment remain intact. -Commit the adjustment unit after `approved` or `verification_incomplete`. For the latter, derive and append one `Verification-Limitation: ` and `Verification-Affected: ` trailer pair per retained limitation. +Commit the confirmed adjustment after `approved` or `verification_incomplete`. For the latter, derive and append one `Verification-Limitation: ` and `Verification-Affected: ` trailer pair per retained limitation. -Then loop back to Step 5 for the next file until all units are committed. - -On continuation, reconstruct retained limitations from the verification trailers on adjustment-unit commits already completed for this request. After all units are committed, retry each retained verification limitation once with quality-fixer-frontend. Clear an `approved` result, commit any resulting fixes through Steps 6→7, and include only a repeated limitation in the completion report. +On continuation, reconstruct retained limitations from the verification trailers on commits already completed for this request. After the adjustment is committed, retry each retained verification limitation once with quality-fixer-frontend. Clear an `approved` result, commit any resulting fixes through Steps 6→7, and include only a repeated limitation in the completion report. ## Completion Criteria @@ -138,9 +136,9 @@ On continuation, reconstruct retained limitations from the verification trailers - [ ] UI Spec applicability and the candidate write set were determined from the requested UI and sufficient repository evidence - [ ] Structural boundary judgment applied; changes requiring complete design or a qualifying durable decision escalated - [ ] Adjustment context, including the affected files, was presented and confirmed once -- [ ] All adjustment units edited; each declared verification mechanism ran, received manual confirmation where required, or retained its exact proof limitation after final retry -- [ ] Each adjustment unit completed quality-fixer-frontend before commit; retained proof limitations were retried and reported -- [ ] Each adjustment unit committed +- [ ] The confirmed adjustment outcome is implemented; each declared verification mechanism ran, received manual confirmation where required, or retained its exact proof limitation after final retry +- [ ] The confirmed adjustment completed quality-fixer-frontend before commit; retained proof limitations were retried and reported +- [ ] The confirmed adjustment is committed ## Output Example @@ -149,6 +147,6 @@ Frontend adjustment completed. - External resources: docs/project-context/external-resources.md (updated|unchanged) - UI evidence: existing pattern [path], external sources [fetched|partial|not_recorded] - Scale: direct existing-pattern adjustment -- Adjustment units committed: [count] +- Adjustment commit: [commit hash] - Quality status: all passed | [remaining proof limitations] ``` diff --git a/dev-workflows/agents/quality-fixer.md b/dev-workflows/agents/quality-fixer.md index 60be523..b07f213 100644 --- a/dev-workflows/agents/quality-fixer.md +++ b/dev-workflows/agents/quality-fixer.md @@ -145,6 +145,8 @@ Use this status only after Step 1 confirmed implementation completeness and ever ``` **stub_detected response format (incomplete implementation)**: +Use `null` for `file` or `location` when no corresponding file or code location exists; describe the missing required behavior in `description`. + ```json { "status": "stub_detected", diff --git a/skills/recipe-front-adjust/SKILL.md b/skills/recipe-front-adjust/SKILL.md index dbec52f..0f06833 100644 --- a/skills/recipe-front-adjust/SKILL.md +++ b/skills/recipe-front-adjust/SKILL.md @@ -21,7 +21,7 @@ Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or g ## Execution Gate -Complete Steps 1-7 in order for each adjustment unit. Advance only through the current step's stated evidence, quality result, or user stop; skip work only when its stated condition is false. Report completion after every applicable Completion Criterion and retained-limitation retry is satisfied. +Complete Steps 1-7 in order for the confirmed adjustment outcome. Advance only through the current step's stated evidence, quality result, or user stop; skip work only when its stated condition is false. Report completion after every applicable Completion Criterion and retained-limitation retry is satisfied. ## Workflow Overview @@ -49,9 +49,9 @@ Adjustment request → conditional external resource evidence - Structural boundary judgment via documentation-criteria - Adjustment edits and verification against the design source (run in this session) - Quality verification via quality-fixer-frontend -- Commit per adjustment unit +- Commit the confirmed adjustment outcome -**Responsibility Boundary**: This skill completes when each adjustment is committed after its quality cycle and any retained proof limitation receives its final retry. Adjustment work is end-to-end within this recipe; parent session owns edits, verification loops, quality-result routing, and commits. +**Responsibility Boundary**: This skill completes when the confirmed adjustment is committed after its quality cycle and any retained proof limitation receives its final retry. Adjustment work is end-to-end within this recipe; parent session owns edits, verification loops, quality-result routing, and commits. **Escalation Boundary**: Escalate to the full frontend design phase when the request crosses a responsibility or approved UI boundary, requires a complete Design Doc, or contains a technical choice that passes documentation-criteria's Choice and Durability filters. @@ -96,7 +96,7 @@ Execute Skill: typescript-rules before planning or applying adjustment edits. Execute Skill: implementation-approach before planning or applying adjustment edits. Execute Skill: test-implement before adding or changing tests. -For each file in the confirmed adjustment context: +Implement the confirmed adjustment outcome across its affected files: 1. **Plan the edit** from the confirmed adjustment context and relevant external resource (e.g., design origin's fetched_summary). 2. **Apply the edit** using Edit / Write / MultiEdit on the affected files. 3. **Verify against external sources** using whichever access method `docs/project-context/external-resources.md` declares for each axis: @@ -104,33 +104,31 @@ For each file in the confirmed adjustment context: - Visual rendering: capture screenshot or run a smoke check via the declared visual verification method (e.g., browser MCP, E2E test runner CLI invoked via Bash, dev-server URL inspection, Storybook URL) - Design system tokens / variants: confirm against the declared design system source (e.g., design-system MCP, package import, Storybook URL, internal documentation path) 4. **Refine and re-verify** until the adjustment matches the design source, or matches the user-confirmed adjustment target when no separate design source exists. -5. When the adjustment unit converges, proceed to Step 6 for that unit. +5. When the complete adjustment matches the confirmed target, proceed to Step 6. When the project-tier file declares no automated verification mechanism for an axis, ask the user to confirm the result manually, or use file-based comparison when a specification file is available. -### Step 6: Quality Verification (per adjustment unit) +### Step 6: Quality Verification - Invoke **quality-fixer-frontend** using Agent tool - `subagent_type: "dev-workflows-frontend:quality-fixer-frontend"` - - `description: "Quality verification for adjustment unit"` - - `direct_scope`: Copy the current unit's confirmed adjustment request and preserved visible behavior from Step 4 unchanged. - - `governing_sources`: Pass the existing UI and design source references used for this unit unchanged. - - `observable_verification`: Copy the verification criteria used for this unit in Step 5 unchanged. + - `description: "Quality verification for confirmed adjustment"` + - `direct_scope`: Copy the confirmed adjustment request and preserved visible behavior from Step 4 unchanged. + - `governing_sources`: Pass the existing UI and design source references used for the adjustment unchanged. + - `observable_verification`: Pass the confirmed adjustment request from Step 4 and applicable acceptance criteria from the governing sources unchanged. - Pass `qualityCommand` when available (caller first, otherwise current task). - Route the quality-fixer-frontend response by `status`: - `approved` → proceed to Step 7 - - `stub_detected` → return to Step 5 to complete the implementation for this unit, then re-invoke quality-fixer-frontend + - `stub_detected` → return to Step 5 to complete the confirmed adjustment, then re-invoke quality-fixer-frontend - `verification_incomplete` → retain the complete result for final retry and proceed to Step 7 - `blocked` → Apply subagents-orchestration-guide Specialist Result Acceptance using the result's semantic evidence, changed files, and repository state -### Step 7: Commit (per adjustment unit) -Before committing, use repository state at the commit boundary as the primary evidence and account for every actual change by mapping it to the confirmed adjustment, preserved pattern, or a necessary dependency, test, or generated artifact. Every required change is ready for the unit commit, accidental changes introduced during the unit are removed, and existing worktree changes unrelated to the confirmed adjustment remain intact. +### Step 7: Commit +Before committing, use repository state at the commit boundary as the primary evidence and account for every actual change by mapping it to the confirmed adjustment, preserved pattern, or a necessary dependency, test, or generated artifact. Every required change is ready for the adjustment commit, accidental changes introduced during the adjustment are removed, and existing worktree changes unrelated to the confirmed adjustment remain intact. -Commit the adjustment unit after `approved` or `verification_incomplete`. For the latter, derive and append one `Verification-Limitation: ` and `Verification-Affected: ` trailer pair per retained limitation. +Commit the confirmed adjustment after `approved` or `verification_incomplete`. For the latter, derive and append one `Verification-Limitation: ` and `Verification-Affected: ` trailer pair per retained limitation. -Then loop back to Step 5 for the next file until all units are committed. - -On continuation, reconstruct retained limitations from the verification trailers on adjustment-unit commits already completed for this request. After all units are committed, retry each retained verification limitation once with quality-fixer-frontend. Clear an `approved` result, commit any resulting fixes through Steps 6→7, and include only a repeated limitation in the completion report. +On continuation, reconstruct retained limitations from the verification trailers on commits already completed for this request. After the adjustment is committed, retry each retained verification limitation once with quality-fixer-frontend. Clear an `approved` result, commit any resulting fixes through Steps 6→7, and include only a repeated limitation in the completion report. ## Completion Criteria @@ -138,9 +136,9 @@ On continuation, reconstruct retained limitations from the verification trailers - [ ] UI Spec applicability and the candidate write set were determined from the requested UI and sufficient repository evidence - [ ] Structural boundary judgment applied; changes requiring complete design or a qualifying durable decision escalated - [ ] Adjustment context, including the affected files, was presented and confirmed once -- [ ] All adjustment units edited; each declared verification mechanism ran, received manual confirmation where required, or retained its exact proof limitation after final retry -- [ ] Each adjustment unit completed quality-fixer-frontend before commit; retained proof limitations were retried and reported -- [ ] Each adjustment unit committed +- [ ] The confirmed adjustment outcome is implemented; each declared verification mechanism ran, received manual confirmation where required, or retained its exact proof limitation after final retry +- [ ] The confirmed adjustment completed quality-fixer-frontend before commit; retained proof limitations were retried and reported +- [ ] The confirmed adjustment is committed ## Output Example @@ -149,6 +147,6 @@ Frontend adjustment completed. - External resources: docs/project-context/external-resources.md (updated|unchanged) - UI evidence: existing pattern [path], external sources [fetched|partial|not_recorded] - Scale: direct existing-pattern adjustment -- Adjustment units committed: [count] +- Adjustment commit: [commit hash] - Quality status: all passed | [remaining proof limitations] ``` From 612158a47e9c7f25cecf9d0cc004121a1597ac36 Mon Sep 17 00:00:00 2001 From: Shinsuke Kagawa Date: Sat, 5 Sep 2026 16:20:43 +0900 Subject: [PATCH 3/3] chore: bump plugin versions to 0.25.3 --- .claude-plugin/marketplace.json | 8 ++++---- dev-skills/.claude-plugin/plugin.json | 2 +- dev-workflows-frontend/.claude-plugin/plugin.json | 2 +- dev-workflows-fullstack/.claude-plugin/plugin.json | 2 +- dev-workflows/.claude-plugin/plugin.json | 2 +- package.json | 2 +- 6 files changed, 9 insertions(+), 9 deletions(-) diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 1877879..bff3521 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -12,7 +12,7 @@ "name": "dev-workflows", "source": "./dev-workflows", "strict": true, - "version": "0.25.2", + "version": "0.25.3", "description": "Skills + Subagents for backend development - Use skills for coding guidance, or run recipe workflows for full orchestrated agentic coding with specialized agents", "author": { "name": "Shinsuke Kagawa", @@ -83,7 +83,7 @@ "name": "dev-workflows-frontend", "source": "./dev-workflows-frontend", "strict": true, - "version": "0.25.2", + "version": "0.25.3", "description": "Skills + Subagents for React/TypeScript - Use skills for coding guidance, or run recipe workflows for full orchestrated agentic coding with specialized agents", "author": { "name": "Shinsuke Kagawa", @@ -157,7 +157,7 @@ "name": "dev-workflows-fullstack", "source": "./dev-workflows-fullstack", "strict": true, - "version": "0.25.2", + "version": "0.25.3", "description": "Skills + Subagents for fullstack development (backend + React/TypeScript) - Use skills for coding guidance, or run recipe workflows for full orchestrated agentic coding with specialized agents", "author": { "name": "Shinsuke Kagawa", @@ -247,7 +247,7 @@ "name": "dev-skills", "source": "./dev-skills", "strict": true, - "version": "0.25.2", + "version": "0.25.3", "description": "Lightweight skills for users with existing workflows - coding best practices, testing principles, and design guidelines without recipe workflows or agents", "author": { "name": "Shinsuke Kagawa", diff --git a/dev-skills/.claude-plugin/plugin.json b/dev-skills/.claude-plugin/plugin.json index 56dd3a5..fd01f99 100644 --- a/dev-skills/.claude-plugin/plugin.json +++ b/dev-skills/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "dev-skills", "description": "Lightweight skills for users with existing workflows - coding best practices, testing principles, and design guidelines without recipe workflows or agents", - "version": "0.25.2", + "version": "0.25.3", "author": { "name": "Shinsuke Kagawa", "url": "https://github.com/shinpr" diff --git a/dev-workflows-frontend/.claude-plugin/plugin.json b/dev-workflows-frontend/.claude-plugin/plugin.json index c565366..9f1e8b1 100644 --- a/dev-workflows-frontend/.claude-plugin/plugin.json +++ b/dev-workflows-frontend/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "dev-workflows-frontend", "description": "Skills + Subagents for React/TypeScript - Use skills for coding guidance, or run recipe workflows for full orchestrated agentic coding with specialized agents", - "version": "0.25.2", + "version": "0.25.3", "author": { "name": "Shinsuke Kagawa", "url": "https://github.com/shinpr" diff --git a/dev-workflows-fullstack/.claude-plugin/plugin.json b/dev-workflows-fullstack/.claude-plugin/plugin.json index 48ffa90..e8f36f4 100644 --- a/dev-workflows-fullstack/.claude-plugin/plugin.json +++ b/dev-workflows-fullstack/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "dev-workflows-fullstack", "description": "Skills + Subagents for fullstack development (backend + React/TypeScript) - Use skills for coding guidance, or run recipe workflows for full orchestrated agentic coding with specialized agents", - "version": "0.25.2", + "version": "0.25.3", "author": { "name": "Shinsuke Kagawa", "url": "https://github.com/shinpr" diff --git a/dev-workflows/.claude-plugin/plugin.json b/dev-workflows/.claude-plugin/plugin.json index a9c358f..9683a9b 100644 --- a/dev-workflows/.claude-plugin/plugin.json +++ b/dev-workflows/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "dev-workflows", "description": "Skills + Subagents for backend development - Use skills for coding guidance, or run recipe workflows for full orchestrated agentic coding with specialized agents", - "version": "0.25.2", + "version": "0.25.3", "author": { "name": "Shinsuke Kagawa", "url": "https://github.com/shinpr" diff --git a/package.json b/package.json index a435e9d..842cc52 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "claude-code-workflows", - "version": "0.25.2", + "version": "0.25.3", "private": true, "type": "module", "engines": {