Skip to content

Commit 556d342

Browse files
author
DavidQ
committed
Add completion, error handling, UI, input, capture, and testing contracts to project instructions - PR_26126_053-project-instructions-completion-contracts
1 parent a5be88d commit 556d342

4 files changed

Lines changed: 269 additions & 0 deletions

‎docs/dev/PROJECT_INSTRUCTIONS.md‎

Lines changed: 107 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -511,3 +511,110 @@ All CSS must be external.
511511
- No `tools/shared` dependency is allowed.
512512
- Shared UI behavior must use reusable classes.
513513
- Do not duplicate shared UI behavior logic across controls or tools.
514+
515+
## DEFINITION OF DONE
516+
517+
A PR is complete only when:
518+
- scope is clean
519+
- requested validation passes
520+
- required reports exist
521+
- manual test notes are present
522+
523+
No PR is complete with:
524+
- unresolved console errors
525+
- broken UI controls
526+
- missing review artifacts
527+
- unintended file changes
528+
529+
## ERROR HANDLING CONTRACT
530+
531+
- No silent fallback.
532+
- No hidden defaults.
533+
- Failures must be visible, actionable, and logged.
534+
- Invalid input must not partially render.
535+
- Batch failures must identify the exact item that failed.
536+
537+
## UI CONSISTENCY CONTRACT
538+
539+
- Tools must use consistent header, NAV, panel, accordion, status, and action patterns.
540+
- Left and right tool panels must use working accordion sections unless explicitly exempted.
541+
- Dead accordion controls are prohibited.
542+
543+
## INPUT RESOLUTION RULES
544+
545+
- Discover real files and directories.
546+
- Never assume numeric sequences.
547+
- Missing inputs are SKIP when batch processing, not FAIL, unless the selected single input is missing.
548+
- Logs must identify resolved paths.
549+
550+
## RENDERING AND CAPTURE RULES
551+
552+
- Capture modes must be explicit.
553+
- Do not silently fall back between capture modes.
554+
- Capture failures must log the mode, target, and underlying error.
555+
- Rendering tools must not claim OK when fallback or partial capture occurred.
556+
557+
## SEPARATION OF CONCERNS CONTRACT
558+
559+
- One class per file.
560+
- One control or section per class.
561+
- App/root class coordinates only.
562+
- Controls do not reach into other controls directly.
563+
- Shared behavior must use reusable classes.
564+
565+
## TESTING DEPTH REQUIREMENT
566+
567+
- Playwright must validate meaningful behavior, not just page load.
568+
- Tests should cover state transitions, failure states, and edge cases when impacted.
569+
570+
## BATCH OPERATION RULES
571+
572+
- Batch operations must log per item.
573+
- One failed item must not stop the batch unless the failure is global.
574+
- Summary must include written, failed, skipped, and warnings.
575+
576+
## DEFINITION OF DONE PLAYWRIGHT CONTRACT
577+
578+
Playwright MUST pass when the PR changes:
579+
- tool runtime behavior
580+
- UI controls or interactions
581+
- workspace or toolState flows
582+
- capture or rendering paths
583+
584+
Playwright is NOT required when the PR is:
585+
- docs-only
586+
- naming/formatting-only
587+
- a pure refactor with no behavior change, when that no-behavior-change claim is justified
588+
589+
Each PR must state:
590+
591+
`Playwright impacted: Yes/No`
592+
593+
If Playwright impacted is Yes:
594+
- `npm run test:workspace-v2` must pass.
595+
596+
If Playwright impacted is No:
597+
- include `No Playwright impact. This PR is docs/workflow only.`
598+
599+
Keep the full samples smoke test rule unchanged:
600+
- full samples smoke test runs only when broadly impacted.
601+
602+
## PLAYWRIGHT COVERAGE DEPTH REQUIREMENT
603+
604+
Playwright must validate behavior, not just page load.
605+
606+
When a PR impacts a tool, Playwright tests must cover:
607+
- the primary user action, such as Generate Preview
608+
- control state transitions, such as enabled and disabled states
609+
- at least one failure case when applicable
610+
611+
Playwright tests must verify actual outcomes, not just element existence.
612+
613+
Playwright tests must not be limited to page loads without error.
614+
615+
Each PR must state what behavior is being validated.
616+
617+
Do NOT require:
618+
- full feature coverage
619+
- 100% code coverage
620+
- performance requirements

‎docs/dev/reports/project_instructions_completion_contracts.txt‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
PR_26126_053-project-instructions-completion-contracts
2+
3+
Purpose:
4+
Append missing execution contracts that make the repo workflow self-enforcing.
5+
6+
Appended sections:
7+
8+
## DEFINITION OF DONE
9+
10+
A PR is complete only when:
11+
- scope is clean
12+
- requested validation passes
13+
- required reports exist
14+
- manual test notes are present
15+
16+
No PR is complete with:
17+
- unresolved console errors
18+
- broken UI controls
19+
- missing review artifacts
20+
- unintended file changes
21+
22+
## ERROR HANDLING CONTRACT
23+
24+
- No silent fallback.
25+
- No hidden defaults.
26+
- Failures must be visible, actionable, and logged.
27+
- Invalid input must not partially render.
28+
- Batch failures must identify the exact item that failed.
29+
30+
## UI CONSISTENCY CONTRACT
31+
32+
- Tools must use consistent header, NAV, panel, accordion, status, and action patterns.
33+
- Left and right tool panels must use working accordion sections unless explicitly exempted.
34+
- Dead accordion controls are prohibited.
35+
36+
## INPUT RESOLUTION RULES
37+
38+
- Discover real files and directories.
39+
- Never assume numeric sequences.
40+
- Missing inputs are SKIP when batch processing, not FAIL, unless the selected single input is missing.
41+
- Logs must identify resolved paths.
42+
43+
## RENDERING AND CAPTURE RULES
44+
45+
- Capture modes must be explicit.
46+
- Do not silently fall back between capture modes.
47+
- Capture failures must log the mode, target, and underlying error.
48+
- Rendering tools must not claim OK when fallback or partial capture occurred.
49+
50+
## SEPARATION OF CONCERNS CONTRACT
51+
52+
- One class per file.
53+
- One control or section per class.
54+
- App/root class coordinates only.
55+
- Controls do not reach into other controls directly.
56+
- Shared behavior must use reusable classes.
57+
58+
## TESTING DEPTH REQUIREMENT
59+
60+
- Playwright must validate meaningful behavior, not just page load.
61+
- Tests should cover state transitions, failure states, and edge cases when impacted.
62+
63+
## BATCH OPERATION RULES
64+
65+
- Batch operations must log per item.
66+
- One failed item must not stop the batch unless the failure is global.
67+
- Summary must include written, failed, skipped, and warnings.
68+
69+
70+
Validation notes:
71+
- docs/dev/PROJECT_INSTRUCTIONS.md was the only target document edited.
72+
- Existing content was preserved; new sections were appended at the end of the file.
73+
- No roadmap, code, samples, schema, or start_of_day files were modified for this PR.
74+
- No Playwright impact. This PR is docs/workflow only.
75+
76+
Manual test notes:
77+
- Open docs/dev/PROJECT_INSTRUCTIONS.md and confirm the new completion, error handling, UI consistency, input resolution, rendering/capture, separation, testing depth, and batch operation contracts appear at the end of the file.
78+
- Confirm the appended contract text is readable and copy/paste ready.

‎docs/dev/reports/project_instructions_dod_playwright.txt‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
PR_26126_054-project-instructions-dod-playwright
2+
3+
Purpose:
4+
Append a Definition of Done Playwright contract that clearly states when Playwright is required, when it is not required, and what each PR must report.
5+
6+
Appended section:
7+
8+
## DEFINITION OF DONE PLAYWRIGHT CONTRACT
9+
10+
Playwright MUST pass when the PR changes:
11+
- tool runtime behavior
12+
- UI controls or interactions
13+
- workspace or toolState flows
14+
- capture or rendering paths
15+
16+
Playwright is NOT required when the PR is:
17+
- docs-only
18+
- naming/formatting-only
19+
- a pure refactor with no behavior change, when that no-behavior-change claim is justified
20+
21+
Each PR must state:
22+
23+
`Playwright impacted: Yes/No`
24+
25+
If Playwright impacted is Yes:
26+
- `npm run test:workspace-v2` must pass.
27+
28+
If Playwright impacted is No:
29+
- include `No Playwright impact. This PR is docs/workflow only.`
30+
31+
Keep the full samples smoke test rule unchanged:
32+
- full samples smoke test runs only when broadly impacted.
33+
34+
35+
Validation notes:
36+
- docs/dev/PROJECT_INSTRUCTIONS.md was the only target document edited.
37+
- Existing wording was preserved; the Playwright DoD contract was appended at the end of the file.
38+
- No roadmap, code, samples, schema, or start_of_day files were modified for this PR.
39+
- Playwright impacted: No.
40+
- No Playwright impact. This PR is docs/workflow only.
41+
42+
Manual test notes:
43+
- Open docs/dev/PROJECT_INSTRUCTIONS.md and confirm the Definition of Done Playwright Contract appears at the end of the file.
44+
- Confirm the section clearly states when Playwright must pass and when a PR may explicitly mark no Playwright impact.
45+
- Confirm the full samples smoke test rule remains unchanged.

‎docs/dev/reports/project_instructions_playwright_depth.txt‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
PR_26126_055-project-instructions-playwright-depth
2+
3+
Purpose:
4+
Append minimum Playwright coverage depth requirements so impacted tool PRs validate behavior, state transitions, and outcomes instead of page load only.
5+
6+
Appended section:
7+
8+
## PLAYWRIGHT COVERAGE DEPTH REQUIREMENT
9+
10+
Playwright must validate behavior, not just page load.
11+
12+
When a PR impacts a tool, Playwright tests must cover:
13+
- the primary user action, such as Generate Preview
14+
- control state transitions, such as enabled and disabled states
15+
- at least one failure case when applicable
16+
17+
Playwright tests must verify actual outcomes, not just element existence.
18+
19+
Playwright tests must not be limited to page loads without error.
20+
21+
Each PR must state what behavior is being validated.
22+
23+
Do NOT require:
24+
- full feature coverage
25+
- 100% code coverage
26+
- performance requirements
27+
28+
29+
Validation notes:
30+
- docs/dev/PROJECT_INSTRUCTIONS.md was the only target document edited.
31+
- Existing wording was preserved; the Playwright coverage depth requirement was appended at the end of the file.
32+
- No roadmap, code, samples, schema, or start_of_day files were modified for this PR.
33+
- Playwright impacted: No.
34+
- No Playwright impact. This PR is docs/workflow only.
35+
36+
Manual test notes:
37+
- Open docs/dev/PROJECT_INSTRUCTIONS.md and confirm the Playwright Coverage Depth Requirement appears at the end of the file.
38+
- Confirm the section requires behavior validation, primary user action coverage, state transition coverage, applicable failure coverage, and actual outcome checks.
39+
- Confirm the section does not require full feature coverage, 100% code coverage, or performance requirements.

0 commit comments

Comments
 (0)