qfai 1.7.5 → 1.7.7

package/README.md

@@ -15,6 +15,12 @@ QFAI addresses these failure modes by standardizing an end-to-end delivery loop
 QFAI is designed for a skills-driven operating model: engineers select a prepared custom skill and provide only the task intent.
 The agent reads the repository, produces the required artifacts, and iterates until the hard gates pass.
 
+## Release status
+
+- Current package version: `1.7.7`
+- Release posture: v1.7.7 is the correction release that aligns the v1.7.6 remediation line before deeper prototyping work.
+- Current repo note: some repo-wide `qfai validate --fail-on error` blockers still come from historical review/evidence/ATDD/TDD artifacts and are being cleaned incrementally.
+
 ## Quick start
 
 > **Windows users:** `qfai init` creates symlinks internally.
@@ -54,7 +60,7 @@ npx qfai report
     Use `--autogen-only` to fail when generation fails (for CI gates).
     Enable with `QFAI_PROTOTYPE_FIDELITY_AUTOGEN=1` as an alternative to `--autogen-ui-fidelity`.
 
-## ATDD annotation hard gate (v1.4.36)
+## ATDD annotation hard gate
 
 `qfai validate` enforces spec-to-test traceability with directory-based rules.
 
@@ -64,7 +70,7 @@ npx qfai report
 - `tests/api/**` and `tests/e2e/**` must not use `TC` annotations.
 - `AC` annotations are not required in code; AC coverage is treated as indirect through full `TC` coverage.
 
-## Prototyping uiFidelity autogen (v1.4.36)
+## Prototyping uiFidelity autogen
 
 `qfai prototyping --autogen-ui-fidelity` auto-generates `uiFidelity` evidence by:
 
@@ -251,7 +257,7 @@ flowchart LR
 - Contracts SSOT: `.qfai/contracts/**`
 - Report outputs (`.qfai/report/**`) are derived artifacts and not SSOT.
 
-## Minimal tutorial (v1.5.6)
+## Minimal tutorial (v1.7.7)
 
 1. `npx qfai init`
 2. Run `/qfai-discussion` to structure scope, open questions, and produce a discussion pack under `.qfai/discussion/discussion-<ts>/`.
@@ -277,7 +283,7 @@ Release gate behavior:
 
 ## Continuous integration
 
-QFAI v1.4.36 generates integration wrappers under `.agents/**`, `.claude/**`,
+QFAI generates integration wrappers under `.agents/**`, `.claude/**`,
 `.github/**`, and `.codex/**`.
 It does not generate GitHub Actions workflows.
 Configure CI in your own platform and run:

package/assets/init/.qfai/assistant/skills/qfai-discussion/templates/uiux/20_eval_axis_usability.md

@@ -1,5 +1,10 @@
 # Evaluation Axis: Usability
 
+## Layer Classification
+
+- Layer: invariant
+- Source: Universal UX heuristic (Nielsen)
+
 ## Evaluation Criteria
 
 | Criterion        | Description                                      | Weight |

package/assets/init/.qfai/assistant/skills/qfai-discussion/templates/uiux/21_eval_axis_consistency.md

@@ -1,5 +1,10 @@
 # Evaluation Axis: Consistency
 
+## Layer Classification
+
+- Layer: invariant
+- Source: Design system adherence principle
+
 ## Evaluation Criteria
 
 | Criterion               | Description                                   | Weight |

package/assets/init/.qfai/assistant/skills/qfai-discussion/templates/uiux/22_eval_axis_accessibility.md

@@ -1,5 +1,10 @@
 # Evaluation Axis: Accessibility
 
+## Layer Classification
+
+- Layer: invariant
+- Source: WCAG 2.1 compliance requirement
+
 ## Evaluation Criteria
 
 | Criterion             | Description                             | Weight |

package/assets/init/.qfai/assistant/skills/qfai-discussion/templates/uiux/23_eval_axis_delight.md

@@ -1,5 +1,10 @@
 # Evaluation Axis: Delight
 
+## Layer Classification
+
+- Layer: invariant
+- Source: User satisfaction and perceived quality
+
 ## Evaluation Criteria
 
 | Criterion              | Description                              | Weight |
@@ -25,10 +30,27 @@
 - 2: Friction points noticed by users
 - 1: Frustrating experience reported
 
+## Trend-derived Axes
+
+<!-- Add trend-derived axes below. Each requires source_translation from research findings. -->
+
+| Criterion       | Source Translation                        | Description   | Weight   |
+| --------------- | ----------------------------------------- | ------------- | -------- |
+| (trend-derived) | (research finding → evaluation criterion) | (description) | (weight) |
+
 ## Product-specific Axes
 
-<!-- Add project-specific delight criteria below. These are trend-derived or product-specific axes. -->
+<!-- Add product-specific axes below. These are unique to the project's domain. -->
 
 | Criterion          | Description   | Weight   |
 | ------------------ | ------------- | -------- |
 | (project-specific) | (description) | (weight) |
+
+## Aggregate Scoring Rules
+
+| Element       | Value                                            |
+| ------------- | ------------------------------------------------ |
+| Weights       | Invariant: 60%, Trend-derived: 25%, Product: 15% |
+| Normalization | Linear 1-5 scale per axis, weighted sum          |
+| Thresholds    | Accept >= 3.5, Refine 2.5-3.4, Pivot < 2.5       |
+| Stopping      | Stop when all axes scored and aggregate computed |

package/assets/init/.qfai/assistant/skills/qfai-discussion/templates/uiux/30_comparison.md

@@ -6,6 +6,8 @@ Compare 2+ design options against scoring axes to support anchor screen selectio
 
 ## Comparison Matrix
 
+### Invariant Axes
+
 | Axis               | Option A: [Name] | Option B: [Name] | Notes       |
 | ------------------ | ---------------- | ---------------- | ----------- |
 | Usability (20)     | [score 1-5]      | [score 1-5]      | [rationale] |
@@ -13,12 +15,24 @@ Compare 2+ design options against scoring axes to support anchor screen selectio
 | Accessibility (22) | [score 1-5]      | [score 1-5]      | [rationale] |
 | Delight (23)       | [score 1-5]      | [score 1-5]      | [rationale] |
 
+### Trend-derived Axes
+
+| Axis            | Option A: [Name] | Option B: [Name] | Source Translation |
+| --------------- | ---------------- | ---------------- | ------------------ |
+| (trend-derived) | [score 1-5]      | [score 1-5]      | [research source]  |
+
+### Product-specific Axes
+
+| Axis               | Option A: [Name] | Option B: [Name] | Notes       |
+| ------------------ | ---------------- | ---------------- | ----------- |
+| (product-specific) | [score 1-5]      | [score 1-5]      | [rationale] |
+
 ## Aggregate Scoring
 
-| Option   | Weighted Total | Rank   |
-| -------- | -------------- | ------ |
-| Option A | [total]        | [rank] |
-| Option B | [total]        | [rank] |
+| Option   | Weights                               | Normalized Total | Threshold             | Rank   |
+| -------- | ------------------------------------- | ---------------- | --------------------- | ------ |
+| Option A | Invariant: 60%, Trend: 25%, Prod: 15% | [total]          | [accept/refine/pivot] | [rank] |
+| Option B | Invariant: 60%, Trend: 25%, Prod: 15% | [total]          | [accept/refine/pivot] | [rank] |
 
 ## Recommendation
 
@@ -26,5 +40,6 @@ Selected: [Option X] — [rationale for selection based on scores and constraint
 
 ## Cross-references
 
-- Scoring axes: `20_eval_axis_usability.md`, `21_eval_axis_consistency.md`, `22_eval_axis_accessibility.md`, `23_eval_axis_delight.md`
+- Invariant axes: `20_eval_axis_usability.md`, `21_eval_axis_consistency.md`, `22_eval_axis_accessibility.md`, `23_eval_axis_delight.md`
+- 3-layer model & aggregate rules: `23_eval_axis_delight.md` (Aggregate Scoring Rules section)
 - Anchor selection: `31_anchor.md`

package/assets/init/.qfai/assistant/skills/qfai-discussion/templates/uiux/40_contracts.md

@@ -8,21 +8,42 @@ Draft interaction contracts for the anchor screen and key screens.
 
 ### Screen: [Screen name]
 
-#### States
-
-| State     | Trigger                | Display                     | Transitions            |
-| --------- | ---------------------- | --------------------------- | ---------------------- |
-| empty     | Initial load, no data  | [empty state description]   | -> loading (on fetch)  |
-| loading   | Data fetch in progress | [loading indicator]         | -> populated, -> error |
-| error     | Fetch failure          | [error message + retry CTA] | -> loading (on retry)  |
-| populated | Data available         | [primary content layout]    | -> empty (on clear)    |
-
-#### Interactions
-
-| Element     | Action    | Result    | Feedback                 |
-| ----------- | --------- | --------- | ------------------------ |
-| Primary CTA | Click/tap | [outcome] | [visual/haptic feedback] |
-| [element]   | [action]  | [result]  | [feedback]               |
+- Route: [/path-to-screen]
+- Actor: [primary user role]
+- Purpose: [what the user accomplishes on this screen]
+
+#### Primary Tasks
+
+| Task             | Trigger       | Success Criteria     |
+| ---------------- | ------------- | -------------------- |
+| [primary task]   | [user action] | [observable outcome] |
+| [secondary task] | [user action] | [observable outcome] |
+
+#### Required States
+
+| State     | Trigger                | Display                     |
+| --------- | ---------------------- | --------------------------- |
+| empty     | Initial load, no data  | [empty state description]   |
+| loading   | Data fetch in progress | [loading indicator]         |
+| error     | Fetch failure          | [error message + retry CTA] |
+| populated | Data available         | [primary content layout]    |
+
+#### Transitions
+
+| From      | To        | Trigger              |
+| --------- | --------- | -------------------- |
+| empty     | loading   | Data fetch initiated |
+| loading   | populated | Data received        |
+| loading   | error     | Fetch failure        |
+| error     | loading   | Retry action         |
+| populated | empty     | Clear action         |
+
+#### Observable Outcomes
+
+| Outcome                    | Verification Method |
+| -------------------------- | ------------------- |
+| [expected user outcome]    | [how to verify]     |
+| [expected system behavior] | [how to verify]     |
 
 ## Cross-references
 

package/assets/uix-rev/comparison-review.md

@@ -0,0 +1,13 @@
+# UIX-REV: Comparison Review
+
+Review option comparison and anchor selection.
+
+## Comparison (30_comparison.md)
+
+- Must contain at least 2 options
+- Each option should have structured evaluation
+
+## Anchor (31_anchor.md)
+
+- Must declare selected_anchor or chosen field
+- Anchor must reference one of the compared options

package/assets/uix-rev/contracts-review.md

@@ -0,0 +1,18 @@
+# UIX-REV: Screen Contracts Review
+
+Review screen contracts for completeness.
+
+## Required Fields per Screen
+
+- route
+- actor
+- purpose
+- primary_tasks
+- required_states
+- transitions
+- observable_outcomes
+
+## Quality Criteria
+
+- Each screen contract must be independently verifiable
+- Routes must be unique across all contracts

package/assets/uix-rev/migration-review.md

@@ -0,0 +1,17 @@
+# UIX-REV: Migration Review
+
+Review migration status of UI-bearing specs.
+
+## Sidecar Presence
+
+- UI-bearing specs must have uiux/ directory
+- Default: warning; strict mode: error
+
+## Version Check
+
+- .sidecar-version must match current template version
+- Stale versions emit warning with upgrade steps
+
+## Configuration
+
+- uiux.migration.strict: boolean (default false)

package/assets/uix-rev/oq-review.md

@@ -0,0 +1,13 @@
+# UIX-REV: Open Questions Review
+
+Review OQ Register for blocking items.
+
+## Blocking Criteria
+
+- Status: open
+- Severity: critical or blocking
+
+## Resolution
+
+- Each blocking OQ must be resolved or downgraded before validation passes
+- Include OQ-ID in all related issue descriptions

package/assets/uix-rev/scoring-review.md

@@ -0,0 +1,14 @@
+# UIX-REV: Scoring Review
+
+Review evaluation axes and aggregate scoring rules.
+
+## Evaluation Axes
+
+- Each trend-derived row must include source_translation
+- Axes must be measurable and verifiable
+
+## Aggregate Scoring
+
+- weights: defined for all axes
+- normalization: method specified
+- threshold: pass/fail boundary defined

package/assets/uix-rev/strategy-review.md

@@ -0,0 +1,22 @@
+# UIX-REV: Strategy Review
+
+Review the UI/UX strategy document for completeness and quality.
+
+## Required Fields
+
+- selection_required
+- candidate_options
+- chosen_option
+- verification_expectations
+- none_as_legitimate_outcome
+
+## Depth Check
+
+- rationale: minimum 20 characters
+- approach: minimum 20 characters
+
+## Verdict
+
+- **accept**: All fields present and meet depth requirements
+- **refine**: Fields present but insufficient depth
+- **pivot**: Missing required fields — fundamental rework needed