Harden UI functional capability coverage

Author: liuyingxuvka

.agents/skills/flowguard-model-miss-review/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: flowguard-model-miss-review
-description: Use for non-trivial bug repairs or when runtime, tests, replay, logs, manual validation, or production evidence fails after FlowGuard modeling passed. Triggers include model miss, false confidence, boundary missing, state too coarse, input branch missing, invariant too weak, evidence overclaimed, root-cause backpropagation, or needing a generalized bad case after a real failure.
+description: Use when runtime, tests, replay, logs, manual validation, or production evidence fails after FlowGuard passed. Triggers include model miss, false confidence, boundary missing, state too coarse, input branch missing, invariant too weak, evidence overclaimed, root-cause backpropagation, or generalized bad case.
 ---
 
 # FlowGuard Model Miss Review
@@ -12,15 +12,15 @@ the model, code contract, tests, or final claim is too narrow. Return to
 ## First Read
 
 - Route id: `model_miss_review`.
-- Entry: `ROUTE_STARTER_API["model_miss_review"]`, `model-miss-template`, or `model-miss-full-template`.
+- Entry: `ROUTE_STARTER_API["model_miss_review"]`, `model-miss-template`, or full variant.
 - Concepts: observed failure, same-class bad case, `boundary_missing`, root-cause backpropagation, owner code contract, old-path/field disposition, defect-family gate, maturation.
 - Reference: `references/model_miss_protocol.md`.
 
 ## Hard Gates
 
 - Verify the real package, keep AGENTS.md managed records current, and do not create a fake mini-framework.
 - A user-observed UI failure after a green claim is a model miss, not a local button-only cleanup.
-- UI misses preserve previous claim/reason, real failure, affected controls/fields, same-class controls/fields, task-flow, affordance/action/dialog/focus gaps, tests/evidence, backpropagation, and code owner.
+- UI misses preserve previous claim/reason, failure, affected and same-class capabilities/controls/fields, task/affordance/dialog/focus gaps, tests/evidence, backpropagation, and code owner.
 - The observed bug instance and bug-class responsibility are separate.
 - Root cause, model obligation, owner code contract, observed test, and same-class test must bind to the same repaired behavior before broad closure.
 - Old, fallback, compatibility, alternate paths, and field misses need disposition/projection instead of accidental reachability.
@@ -31,7 +31,7 @@ the model, code contract, tests, or final claim is too narrow. Return to
 
 1. Run existing-model preflight when the bug is inside a modeled system.
 2. Classify the miss, preserve observed evidence, and backpropagate root cause into the plan/model/test gap.
-3. For UI misses, run `review_ui_model_misses()` and scan same-class controls or fields before fixing only the observed control.
+3. For UI misses, run `review_ui_model_misses()` and scan same-class capabilities, controls, or fields before fixing only the observed control.
 4. Add or name one same-class generalized bad case when practical.
 5. Update the model or FieldLifecycleMesh and bind the owner code contract.
 6. Add observed-regression and same-class evidence, then rerun alignment, disposition, mesh/reattachment, maturation, process freshness, and risk ledger gates as relevant.

.agents/skills/flowguard-model-miss-review/references/model_miss_protocol.md

@@ -11,9 +11,9 @@ not close a known model miss unless the miss has been reviewed.
 If a user opens a UI after a green FlowGuard claim and the visible behavior is
 wrong, treat the episode as a model miss. Typical UI miss types are
 `evidence_overclaimed` when the prior proof only showed a label or API route,
-and `boundary_missing` when the prior model did not account for the visible
-control, field, source-interaction branch, task flow, human-operability rule, or UI state
-update.
+and `boundary_missing` when the prior model did not account for the promised
+capability, visible control, field, source-interaction branch, task flow,
+human-operability rule, or UI state update.
 
 For bug repair work inside an existing modeled system, run Existing Model
 Preflight first so the fix extends the current model boundary instead of
@@ -42,10 +42,14 @@ creating a parallel one.
 6. Add one same-class generalized bad case when practical.
 7. For UI misses, run `review_ui_model_misses(...)` with a record of the prior
    green claim, why it looked green, the user-observed failure, affected
-   controls/fields, same-class controls/fields, same-class tests or click
-   evidence, task-flow/human-operability gaps, root-cause backpropagation, and
-   code owner. Select/Open txt/Load table/Load File style failures should be
-   reviewed as a same-class UI family before closure.
+   capabilities/controls/fields, same-class capabilities/controls/fields,
+   same-class tests or click evidence, task-flow/human-operability gaps,
+   root-cause backpropagation, and code owner. Missing promised UI
+   capabilities must be listed in `missing_promised_capability_ids`, also
+   listed as affected capabilities, and classified as `boundary_missing` or
+   `evidence_overclaimed`. Same-shape missing load, render, plot, refresh,
+   export, save, open, configure, delete, or generated-output functions should
+   be reviewed as a same-class UI family before closure.
 8. Add current test evidence for the observed regression and for the
    same-class generalized case. A point regression is necessary but does not
    close an in-scope miss by itself.

.agents/skills/flowguard-ui-flow-structure/SKILL.md

@@ -5,28 +5,27 @@ description: Use for UI behavior, visible surface, human-operability, and eviden
 
 # FlowGuard UI Flow Structure
 
-Standalone FlowGuard satellite skill for UI states, text, journeys,
-human-operability, structure, runnable evidence. Return to
-`model-first-function-flow` when non-UI.
+Standalone FlowGuard satellite skill for UI states, journeys, human-operability, structure, and evidence. Return to `model-first-function-flow` when non-UI.
 
 ## First Read
 
 - Route id: `ui_flow_structure`.
-- Starter: `ROUTE_STARTER_API["ui_flow_structure"]`; templates: `ui-flow-structure-template`, `ui-flow-structure-full-template`.
+- Starter: `ROUTE_STARTER_API["ui_flow_structure"]`; templates: compact/full.
 - Shape: UI event x UI state -> controls, displays, overlays, recovery, feedback.
-- Helpers: inventory, model, Visible surface, journey, task/human, implementation validation, render/geometry, text hierarchy.
+- Helpers: inventory, capability coverage, model, Visible surface, journey, task/human, implementation, render/geometry, text.
 - Reference: `references/ui_flow_structure_protocol.md`.
 
 ## Hard Gates
 
 - Verify real package and AGENTS.md managed records; no fake mini-framework.
-- Work mode comes first: `greenfield`, `source_based`, or `mixed`. Source-based/mixed need source baseline -> target mapping -> observed-source alignment; greenfield invents no source.
-- Existing/runnable UI: real Visible surface inventory is first. Map observed buttons, inputs, selects, tables, fields, status, dialogs, regions, menus, toolbars to model owner or blindspot.
-- Every reachable enabled action needs visible-control -> event -> code owner -> backend/local/native function -> UI state update -> click/test evidence. Label proof is not enough.
-- Every supported task needs task path, primary control, chain, feedback, cancel/error, keyboard/focus, walkthrough, and human-operable affordance/grammar/region/dialog behavior.
-- Source-based scopes need generic source branches: picker, external open, dialog, no-handler, trigger/confirm/cancel/value/result/error, and approved differences.
-- UI complete/runnable/button-wired claims need `UIImplementationValidation`; screenshot, DOM text, native/manual checks need evidence kind, event, result, ref, boundary.
-- Visible branches, recovery/cancel, ownership, calm typography guidance, and blindspots stay explicit.
+- Work mode first: `greenfield`, `source_based`, or `mixed`; source-based/mixed need baseline -> mapping -> observed alignment.
+- Existing/runnable UI: observed surface is first. Map visible controls, fields, status, dialogs, menus, toolbars, and regions to owner or blindspot.
+- Non-trivial UI or complete/runnable/function claims need `UIFunctionalCapabilityInventory` plus `review_ui_functional_capability_coverage`: required capability -> feature, task, UI path, owner/chain, output, evidence or scoped blindspot.
+- Each reachable enabled action needs visible-control -> event -> owner -> backend/local/native function -> UI state update -> click/test evidence. Label proof is not enough.
+- Supported tasks need path, primary control, chain, feedback, cancel/error, keyboard/focus, walkthrough, and affordance/grammar/region/dialog behavior.
+- Source-based scopes need generic source branches and approved differences.
+- Complete/runnable/button-wired claims need `UIImplementationValidation` with evidence kind such as screenshot/DOM text, event, result, ref, and boundary.
+- Branches, recovery/cancel, ownership, typography guidance, and blindspots stay explicit.
 - Broad transition-test claims need owner cells, then MTA or TestMesh.
 - New/deepened UI models need harvest closure before broad claims.
 
@@ -36,12 +35,13 @@ human-operability, structure, runnable evidence. Return to
 2. Inventory real UI surface when it exists or runs.
 3. For source-based/mixed scope, inventory source, map target differences, and align observed UI.
 4. Model states, events, controls, displays, overlays, transitions, availability.
-5. Review visible surface, chains, source branches, duplicates, blindspots.
-6. Add task coverage and human-operability evidence.
-7. Derive regions, controls, text hierarchy, calm typography guidance.
-8. Add journey, evidence-kind, geometry, transition-cell, and implementation validation as needed.
+5. Add capability coverage: required capabilities, scoped gaps, outputs, and bindings to feature/task/UI path/owner/evidence.
+6. Review visible surface, chains, source branches, duplicates, blindspots.
+7. Add task coverage and human-operability evidence.
+8. Derive regions, controls, text hierarchy, calm typography guidance.
+9. Add journey, evidence-kind, geometry, transition-cell, and implementation validation as needed.
 
-Snapshot: UI state diagram with controls, tasks, visible surface, recovery, text ownership, evidence kinds, and blindspots.
+Snapshot: UI state diagram with controls, capabilities, tasks, visible surface, recovery, text ownership, evidence, blindspots.
 
 ## Non-Goals
 

.agents/skills/flowguard-ui-flow-structure/references/ui_flow_structure_protocol.md

@@ -7,8 +7,9 @@ grounded in user tasks, target UI intent, observed UI, functional chains, and
 implementation evidence. Source-based and mixed work must also build a source
 baseline, target mapping, approved-difference ledger, and observed-source
 alignment. After work-mode routing, the route has model/design stages for
-complete app-level UI claims: build or review a UI interaction model, review
-visible UI surface, review launch-to-terminal journey coverage, derive UI
+complete app-level UI claims: account required user-visible functional
+capabilities, build or review a UI interaction model, review visible UI
+surface, review launch-to-terminal journey coverage, derive UI
 structure from that model, then derive a UI text hierarchy blueprint from the
 reviewed structure. It has a later implementation-evidence stage only when the
 agent claims the running UI is implemented, runnable, or complete. Local
@@ -49,6 +50,10 @@ Use UI Flow Structure when:
 - the UI already exists or can run, and the agent needs to account the real
   visible buttons, inputs, dropdowns, tables, displayed fields, status text,
   dialogs, and regions before claiming the model covers it.
+- the UI is supposed to provide user-visible functions such as load, plot,
+  render, refresh, export, save, delete, search, configure, generate, or open,
+  and those functions must be checked before the visual/control model can be
+  called complete.
 - the UI may technically be wired but still confusing to a human, so supported
   user-visible features must be covered by task frames, primary controls,
   action grammar, region semantics, dialog/window return semantics,
@@ -64,6 +69,9 @@ Collect the lightest fit-for-risk UI evidence:
 - UI work mode: `greenfield`, `source_based`, or `mixed`, including which
   scope ids are greenfield and which are source-based;
 - product goal and user workflow;
+- required user-visible capability inventory from the product goal, user task
+  list, source authority, or accepted scope; for greenfield work this comes
+  from intended user tasks, not from a source baseline;
 - source authority inventory when work is source-based or mixed, such as an
   existing app, prototype, design file, screenshot, product spec, customer
   workflow, manual observation, runtime observation, or other declared source;
@@ -90,6 +98,8 @@ Collect the lightest fit-for-risk UI evidence:
   error, recovery, validation, and success text when available;
 - user-visible feature contracts from the product or functional model when an
   implemented/runnable UI claim is made;
+- capability-to-feature/task/journey/control/event/function/evidence bindings,
+  plus output contracts for result-producing capabilities;
 - user task inventory: every supported feature, every task a user can perform,
   task-to-feature links, UI path links, primary controls, required feedback,
   cancel/error behavior, keyboard/focus expectations, and scoped-out tasks;
@@ -135,6 +145,46 @@ Known-bad hazards:
 - an enabled visible control is treated as covered because its label matches;
 - a blindspot has no owner, reason, or follow-up validation boundary.
 
+## Stage 0A: Functional Capability Coverage
+
+For non-trivial UI work, or whenever an agent claims the UI is implemented,
+runnable, complete, button-wired, or covers user-visible functionality, build a
+`UIFunctionalCapabilityInventory` before broad UI confidence. This applies to
+greenfield, source-based, and mixed UI work. Source-based work may populate the
+inventory from a declared source authority; greenfield work populates it from
+accepted user tasks and product scope.
+
+Use `UIFunctionalCapabilityInventory`, `UIFunctionalCapability`,
+`UICapabilityOutputContract`, `UICapabilityCoverageBinding`, and
+`review_ui_functional_capability_coverage(...)` when the package API is
+available.
+
+Each required user-visible capability must map to:
+
+- a `UIFeatureContract`;
+- a `UIUserTaskFrame` or task ledger entry;
+- a UI journey, visible control, or modeled event;
+- a functional chain, code owner, code contract, implementation run, or test
+  evidence;
+- an output contract when the capability produces visible/result state such as
+  a chart, table, file, generated artifact, saved item, refreshed list, status
+  update, navigation result, or deletion result.
+
+If a capability is intentionally out of scope, deferred, blocked, manual-only,
+or pure UI-only, the row must state owner, reason, validation boundary, and
+rationale. Empty scoped-out lists do not satisfy completeness.
+
+Known-bad hazards:
+
+- the UI has a button inventory but no inventory of what functions the user
+  actually needs to perform;
+- a result-producing capability only proves that a button or API route exists;
+- a chart/table/file/status result is visible as a container but has no output
+  assertion or evidence;
+- a greenfield UI invents a small task list and silently omits other accepted
+  user functions;
+- a source-based UI preserves labels while losing source workflow semantics.
+
 ## Stage 1: UI Interaction Model
 
 Represent the UI as:

.flowguard/project.toml

@@ -1,6 +1,6 @@
 [flowguard]
 repository = "https://github.com/liuyingxuvka/FlowGuard"
-adopted_package_version = "0.47.1"
+adopted_package_version = "0.47.2"
 schema_version = "1.0"
 last_verified_at = "2026-06-13T09:56:24+00:00"
 last_verified_by = "FlowGuard project-upgrade"

CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## v0.47.2 - 2026-06-13
+
+UI functional capability coverage.
+
+- Added UI functional capability inventories, capability/output contracts,
+  capability bindings, and coverage review so required user-visible UI
+  functions cannot disappear before broad UI completion claims.
+- Wired capability coverage into implementation validation, human-operability,
+  PlanDetailing, Model-Miss Review, DevelopmentProcessFlow, RiskEvidenceLedger,
+  AgentWorkflowRehearsal, and ClosureContract without creating a parallel UI
+  route.
+- Updated UI skills, public templates, docs, API/field inventory, OpenSpec
+  artifacts, and regression tests so greenfield, source-based, and mixed UI
+  work use the same generic capability layer.
+
 ## v0.47.1 - 2026-06-13
 
 Plan discussion handoff hardening.