Product maturity (instance-level, anti-warehouse)¶
Status: fleet probe + improve gate (2026-07). v3 anti-gaming + hard densify
stop (#1637). Fleet residual 0/12, densify_allowed=0 under wi_floor,
orphan densify *_ops residue consolidated.
Probe: python scripts/example_product_maturity.py
Companion: framework UX maturity (primitives / defaults).
The question¶
Framework UX maturity asks: does Dazzle make the data-right UI the default? Product maturity asks of each example app:
Would a domain user recognise this as a product for their job — or as a spreadsheet warehouse with auth?
Completeness (every entity has list/create/edit) is not the goal. Persona jobs, answer-first landings, and contained CRUD are.
Metrics (v1 — structural, machine-checkable)¶
| Metric | Pass when | Residual when |
|---|---|---|
| Answer-first landing | Each product persona has default_workspace → real workspace with ≥1 region |
Missing / empty / platform workspace for a product persona |
| Warehouse density | list_surfaces / (list_surfaces + product_workspaces) ≤ 0.70 |
Density > 0.70 (deepen) or ≥ 0.85 with ≤1 product workspace (thin/critical) |
| Job coverage | Each product persona has bound stories or multi-region default workspace | Uncovered product personas |
| CRUD without jobs | Product workspaces exist when many list surfaces | Lists only, no product personas/workspaces |
| Nav list share | Compiled persona sidebars are not mostly entity lists | Avg entity-list link share > 0.70 (deepen) / ≥ 0.85 (heavier) |
Nav list share uses build_persona_nav (same source as the live shell): for
each product persona, entity_list_links / (entity_list + workspace links).
Auto-discover still emits entity list links; the probe credits accessible
product workspaces (and the landing workspace) so apps with strong job desks
are not false-flagged solely because the sidebar still lists region sources.
Product personas exclude platform ids: admin, platform_admin, superuser, …
Product workspaces exclude _platform_* / admin_* prefixes.
Tiers¶
| Tier | Meaning |
|---|---|
ok |
Structural product path present |
deepen |
Landings OK but warehouse-heavy or thin jobs |
thin |
High density / weak job surface |
critical |
No answer-first path or warehouse-only |
Higher score = higher residual priority for improve.
Playbook when residual¶
- Do not add more
mode: listsurfaces to “pass” completeness. - Add job workspaces (queues + metrics + open-to-hub) per product persona.
- Set
default_workspaceto that desk (not one shared mega-workspace). - Gate access so each persona has ≥2–3 accessible product workspaces when auto-nav is list-heavy (nav list share).
- Align stories
given:and stems with the new defaults; refreshSPECIFICATION.md“Where work happens” + fingerprint.
Warehouse Index (WI) — continuous inverse-utility gradient¶
After residual is 0, improve minimizes WI (0–1, higher = more warehouse). Intent: a single statistic that maps inversely to product utility as expressed in DSL structure — not a claim about runtime UX or sales demos.
python scripts/example_product_maturity.py --warehouse-index
python scripts/example_product_maturity.py --next-wi
# Sibling / real apps (not only examples/):
python scripts/example_product_maturity.py --warehouse-index \
--paths ../cyfuture ../pennydreadful ../AegisMark
| Component | Weight | What it measures | Anti-gaming (v3, #1637) |
|---|---|---|---|
| D | 0.30 | list shells vs job-backed desks | Denominator is effective job weight on desks that are persona default_workspace, story executed_by, or non-orphan named product desks. Isomorphic multi-mode filter clones (high_ops / medium_ops / …) credit once. Orphan *_ops densify residue does not dilute D. Scale-capped by entity count. |
| N | 0.25 | nav list-link share | Compiled build_persona_nav; credits accessible product workspaces |
| L | 0.25 | landing thinness | Signal richness: unique (mode_family, source) pairs (cap 5). Six list regions of one entity ≈ one signal |
| J | 0.10 | unbound stories / uncovered personas | Co-evolve story binds with desks; orphan desks do not improve J |
| G | 0.10 | lists without open-via | Platform admin lists excluded |
WI = 0.30D + 0.25N + 0.25L + 0.10J + 0.10G. Hard floor wi_floor=0.25
(#1637): when residual=0 and wi_fleet ≤ wi_floor, status reports
densify_allowed=0 and --next-wi is empty. Explore must not grind D with
isomorphic enum ops desks. Mode families collapse list/queue so parallel
listish pads do not stack.
Additional residual / process signals (v3):
| Signal | When | Action |
|---|---|---|
desk_sprawl |
product workspaces / product personas ≥ 10 | Consolidate desks; prefer filters/segments |
orphan_ops_desks |
≥5 unbacked *_ops workspaces |
Delete or bind to default/story; stop densify |
scoreboard_language |
≥3 hits of WI D / densify / soft-cap skip prose in DSL |
Strip scoreboard comments — the measure must not colonize the medium |
Interpretation: high WI ⇒ list-primary shells, thin/padded landings, soup nav, unbound jobs, no graph hops. Low WI is necessary for product shape, not sufficient for utility (see antagonist demo bar / agent acceptance below).
What this does not score (yet)¶
- Visual kinship to Jira/Linear/GitHub Issues (needs design review or trial)
- Conversation-thread quality vs field form
- Action cost (≤N clicks) without a browser walk
- Authored
product_jobs.toml(future: explicit job registry) - Whether seeded data makes desks useful at runtime (
demo quality/ trials) - Explicit
uses navthat lists workspaces ahead of entity lists (probe already credits access; authored nav would improve felt UX further)
Structural pass can still feel warehouse if the live shell never surfaces the job desk in the sidebar — prefer multi-workspace access + clear default landings.
Antagonist demo bar (#1626)¶
Structural product maturity is necessary but not sufficient. An independent artifact-only bake-off (QA screenshots + landings vs category SaaS) scored the example fleet:
| Checkpoint | Fleet mean | Trio mean | Pass (≥5.5 fleet) |
|---|---|---|---|
| Original | ~2.8 | ~3.0 | Fail |
| 21 Jul | ~3.8 | ~5.9 | Fail |
| 31 Jul (post recapture) | ~5.1 | ~5.7 | Still fail (~0.4 short) |
Pass line for “keep watching a sales demo” = 7.0 commercial; P0 fleet target = ≥ 5.5. Tracking: GitHub #1626.
Agent residual queue (R1–R6, hero stills, messaging):
docs/reference/antagonist-agent-brief-1626.md
| P0 | Failure | Owner altitude |
|---|---|---|
| P0-1 | Builder chrome (Reset / Saved / + Add Card) on business desks | Framework workspace shell |
| P0-2 | CTA verbs from list titles (New Contact List) |
Framework list adapter + surface titles |
| P0-3 | Raw JSON 403 / wrong landing (e.g. finance on _platform_admin) |
Framework error path + QA capture + seeds |
| P0-4 | Platform nav pollution for product personas | Nav builder / admin injection |
| P0-5 | Story-grade demo seeds (one coherent company) | Example blueprints |
| P0-6 | Empty hero stills as happy-path QA names | QA capture + seed gate |
| P0-7–9 | False domain views (org chart, gallery, timeline); invoice desks empty | Example honesty + seeds |
Improve priority: after structural residual is empty, drain #1626 residual queue (agent brief R1–R6) before STALE Tier-1 noise. Do not add entity list surfaces to “fix” commercial bake-off. Do not claim fleet ≥5.5 until a human still re-score (or explicit demotion) says so.
Agent loop (/improve)¶
| Force path | Strategy | Probe |
|---|---|---|
/improve example-apps product_maturity |
improve/strategies/product_maturity.md |
example_product_maturity.py |
/improve example-apps demo_fleet |
improve/strategies/demo_fleet.md |
demo_fleet_bar.py |
/improve example-apps journey_dogfood |
improve/strategies/journey_dogfood.md |
example_journey_maturity.py |
/improve example-apps story_walk |
improve/strategies/story_walk.md |
story_walk_bar.py (landing stories ↔ walks) |
/improve example-apps agent_acceptance_panel |
improve/strategies/agent_acceptance_panel.md |
trial_verdict_bar.py + dazzle qa trial |
Every example-apps OBSERVE (and /improve --status) starts with the unified suite:
python scripts/improve_example_probes.py --status
# product → demo → journey → felt → story_walk → trial_verdict
# warehouse_index … densify_allowed=0|1
Agents should also score felt demo quality (persona-home seeds, metric/list current_user residual #1632, + still floors) via the single bar — structural residual alone can be green while desks are empty or KPIs lie:
dazzle demo quality -p examples/simple_task
dazzle demo quality -p examples --app support_tickets --json
# MCP: product_quality(operation="score", project_root="examples/invoice_ops")
scripts/improve_example_probes.py folds product_quality into OBSERVE so
residual_total is not falsely 0 when persona homes or empty-hero stills remain.
Selection order inside the lane: product_maturity → demo_fleet → journey_dogfood → felt (product_quality, including presentation residual) → story_walk → trial_verdict / agent_acceptance → Tier 1.
When felt residual is presentation (ref_as_repr / person_as_text), force
framework-ux hyperpart_presentation (not demo_fleet). MCP:
presentation(operation=cognition|opportunities|residual|shapes); doctrine
hyperpart-presentation.md; counter-prior ref_as_repr.
Hard stop: if status shows densify_allowed=0, do not run WI D densify
explore. Prefer story_walk residual, then agent_acceptance_panel, then
COGNITION / HYGIENE STALE — not isomorphic *_ops desks.
Maps vs sensors (dig contracts): stories, stems, SPEC, claims, and stills are
efficient maps (context). Only some are outcome residual sensors today.
Design for dig contracts (must cite maps + fire CLI/MCP actuators), divergence
pairs, and epistemic “unproven” residual—without premature “SPEC truth” or full
still-quality bars—lives in
docs/superpowers/specs/2026-07-21-improve-dig-contracts-and-process-sensors-design.md.
Agent-first customer acceptance¶
Human orgs accept products with a panel of QA testers who already know the user stories. Agent-first loops still need that function — without making humans the quality definition (humans stay L4 on the agent QA ladder).
| Human panel | Agent-first substitute |
|---|---|
| Prior knowledge of requirements | Authored stories + stems + trial.toml adoption_criteria |
| Independent of implementers | Separate dig / strategy (agent_acceptance_panel), not the densify commit |
| Multiple perspectives | ≥2 personas or panel seats (story steward + pilot buyer [+ coverage]) |
| Accept / reject | submit_verdict + criteria_scores + friction ownership |
| Backlog feed | JSON auto_seed → improve PENDING (product only) |
When residual=0 and densify is closed, acceptance is the right continuous
improvement surface — not another typography_ops desk. Full playbook:
improve/strategies/agent_acceptance_panel.md. Ladder doctrine:
docs/recipes/agent-qa-ladder.md.
Do not treat low WI as customer acceptance. Low WI means “not a warehouse of lists (or of orphan ops desks).” Acceptance means “a careful multi-role pilot would run a two-week trial.”
Antagonist residual classes (after structural green)¶
| Class | Symptom | Fix altitude |
|---|---|---|
platform_admin_landing |
product admin default_workspace: _platform_admin |
Example DSL: land on a product desk + access |
| Persona-home seed residual | current_user region hits = 0 for stable demo UUID |
Assignment-aware *.jsonl seeds |
| Empty-hero still | Happy-path screenshot < byte floor | Re-seed + dazzle qa capture after seeds |
label_glue |
Queue/card meta runs together (Amount:xCurrency:y) |
Framework queue/list meta templates (R1 — highest leverage to 5.5) |
cta_add_double |
CTA New Add Person / New Add Department |
human_create_cta_label + surface titles (R3) |
hero_http_error |
Happy-path desk shows product 500 shell | Region compute / example desk (R2 ops Active Alerts) |
capture_desk_timeout |
Default desks never still (pay_desk / my_invoices hang) | Capture readiness + per-persona recapture (R4) |
Human residual order and hero still paths:
antagonist-agent-brief-1626.md.
Acceptance (showcase ready, per app): no builder chrome on business desks; human singular CTAs; no raw JSON errors in browser; no platform-only nav for non-admin personas; happy-path stills non-empty with story data.
Probe (partial, machine-checkable):
Checks P0-4 nav isolation, P0-5 blueprint min rows, P0-6 empty-hero byte floors
(including non-trio heroes after 31 Jul), and “not only _platform_admin_*
stills”. Full visual re-score still needs fresh dazzle qa capture after seeds
— use scripts/recapture_demo_fleet_1626.py (per-persona serve restart).
Relationship to other gates¶
| Gate | Altitude | Optimises |
|---|---|---|
| validate / lint / conformance | compile | DSL completeness |
| HM surface audit | emit | pure Hyperpart markup |
| journey maturity | stories | bound agent journeys |
| product maturity | product path | jobs + landing + anti-warehouse |
| ux-maturity | framework | primitive defaults |
| qa trial | live instance | friction on whatever UI exists |
Improve (example-apps lane) prefers product maturity residuals before
STALE Tier-1 noise (lint field completeness) when both are open. Journey
maturity residual is next.
CLI¶
# Unified /improve OBSERVE (product + demo + journey)
python scripts/improve_example_probes.py --status
python scripts/improve_example_probes.py --next
python scripts/improve_example_probes.py --strict
# Product only
python scripts/example_product_maturity.py
python scripts/example_product_maturity.py --status
python scripts/example_product_maturity.py --next
python scripts/example_product_maturity.py --app support_tickets --json
python scripts/example_product_maturity.py --strict # CI / improve gate (exit 1 if residual)
# Demo fleet (#1626 floors)
python scripts/demo_fleet_bar.py --status
python scripts/demo_fleet_bar.py --strict
# Felt product quality (probes + persona homes + stills)
dazzle demo quality -p examples
dazzle demo quality -p examples/simple_task --strict
dazzle demo quality -p examples --app invoice_ops --json
Design intent (reward structure)¶
Deprecate as success metric: every entity has list/detail/create/edit. Promote: every product persona lands on a job surface; warehouse lists are secondary (admin / settings / power-user).
Entity mode: list remains correct for CRUD (ux-maturity R1). Product
maturity scores whether those lists are the primary product path.