sample run.json

sample-run.json

{
  "contract_version": "2.0",
  "id": "management-dashboard",
  "status": "complete",
  "stage": "shape",
  "hook": "audit",
  "target": "management-dashboard",
  "intent": {
    "problem": "Audit the existing management dashboard for admin governance and executive visibility",
    "outcome": "Platform admins can reach trusted adoption, cost, and health signals with clear empty, failure, and permission states",
    "users": [
      "platform-admin",
      "component-author",
      "harness-developer"
    ],
    "critical_promises": [
      {
        "id": "shared-view",
        "promise": "Household members see the same consolidated balance for linked accounts",
        "criticality": "critical",
        "source": "user",
        "confidence": "high",
        "relevance_reason": "Required for the current design slice"
      }
    ],
    "success_signals": [
      "Shared balance visible after link"
    ],
    "constraints": [
      "Mobile-first"
    ],
    "scope": {
      "in": [
        "link account",
        "view budget"
      ],
      "out": [
        "tax filing"
      ]
    }
  },
  "decisions": {
    "assumptions": [
      {
        "id": "monthly",
        "class": "reversible_default",
        "statement": "Budget periods are monthly",
        "criticality": "supporting",
        "source": "user",
        "confidence": "high",
        "relevance_reason": "Required for the current design slice"
      }
    ],
    "forks": []
  },
  "actors": [
    {
      "id": "owner",
      "name": "Owner",
      "role": "household owner",
      "goal": "Keep household budget accurate",
      "authority": "link accounts and set limits",
      "entry_path": "mobile app sign-in",
      "criticality": "critical",
      "source": "user",
      "confidence": "high",
      "relevance_reason": "Required for the current design slice"
    },
    {
      "id": "member",
      "name": "Member",
      "role": "household member",
      "goal": "See shared spend",
      "authority": "view household projection",
      "entry_path": "invite accept",
      "criticality": "supporting",
      "source": "user",
      "confidence": "high",
      "relevance_reason": "Required for the current design slice"
    }
  ],
  "entities": [
    {
      "id": "household",
      "name": "Household",
      "identity": "household id owned by primary member",
      "attributes": [
        {
          "name": "id",
          "contract": "stable id"
        }
      ],
      "relationships": [
        {
          "to": "entity.account-link",
          "type": "has_many",
          "cardinality": "1:n",
          "lifecycle": "cascade-archive"
        }
      ],
      "lifecycle_consequences": [
        "archive hides linked balances"
      ],
      "states": [
        "active",
        "archived"
      ],
      "criticality": "critical",
      "source": "user",
      "confidence": "high",
      "relevance_reason": "Required for the current design slice"
    },
    {
      "id": "account-link",
      "name": "Account link",
      "identity": "provider account linkage per household",
      "attributes": [
        {
          "name": "status",
          "contract": "linked|error|revoked"
        }
      ],
      "relationships": [],
      "lifecycle_consequences": [
        "revoke removes projections"
      ],
      "states": [
        "unlinked",
        "linked",
        "error",
        "revoked"
      ],
      "criticality": "critical",
      "source": "user",
      "confidence": "high",
      "relevance_reason": "Required for the current design slice"
    }
  ],
  "operations": [
    {
      "id": "link-account",
      "name": "Link account",
      "actor_refs": [
        "actor.owner"
      ],
      "enforces": [
        "invariant.owner-only-link"
      ],
      "preconditions": [
        "Actor is authenticated owner"
      ],
      "failures": [
        "Provider denies OAuth",
        "Member attempts link"
      ],
      "recovery": "Remain unlinked and offer retry",
      "transitions": [
        {
          "entity_ref": "entity.account-link",
          "from": "unlinked",
          "to": "linked"
        }
      ],
      "outcome": "Account appears in household budget",
      "criticality": "critical",
      "source": "user",
      "confidence": "high",
      "relevance_reason": "Required for the current design slice"
    },
    {
      "id": "view-budget",
      "name": "View consolidated budget",
      "actor_refs": [
        "actor.owner",
        "actor.member"
      ],
      "enforces": [
        "invariant.household-scope"
      ],
      "preconditions": [
        "Actor belongs to household"
      ],
      "failures": [
        "Unauthenticated",
        "Non-member"
      ],
      "recovery": "Show sign-in or access denied",
      "effects": [
        "Render household projection"
      ],
      "transitions": [],
      "outcome": "Shared balances and limits are shown",
      "criticality": "critical",
      "source": "user",
      "confidence": "high",
      "relevance_reason": "Required for the current design slice"
    }
  ],
  "workflows": [
    {
      "id": "link-and-view",
      "name": "Link account and view budget",
      "actor_ref": "actor.owner",
      "steps": [
        {
          "operation_ref": "operation.link-account",
          "actor_ref": "actor.owner",
          "dependency_refs": [
            "dependency.oauth"
          ]
        },
        {
          "operation_ref": "operation.view-budget",
          "actor_ref": "actor.owner",
          "dependency_refs": []
        }
      ],
      "terminal_outcomes": [
        "Shared budget visible",
        "Link failed with recovery"
      ],
      "criticality": "critical",
      "source": "user",
      "confidence": "high",
      "relevance_reason": "Required for the current design slice"
    }
  ],
  "invariants": [
    {
      "id": "owner-only-link",
      "rule": "Only owner may link accounts",
      "criticality": "critical",
      "source": "user",
      "confidence": "high",
      "relevance_reason": "Required for the current design slice"
    },
    {
      "id": "household-scope",
      "rule": "Members only see their household projection",
      "criticality": "critical",
      "source": "user",
      "confidence": "high",
      "relevance_reason": "Required for the current design slice"
    }
  ],
  "dependencies": [
    {
      "id": "oauth",
      "type": "data",
      "from": "operation.link-account",
      "to": "entity.account-link",
      "unmet_behavior": "Show recoverable link error and keep account unlinked",
      "criticality": "supporting",
      "source": "user",
      "confidence": "high",
      "relevance_reason": "Required for the current design slice"
    }
  ],
  "surfaces": [
    {
      "id": "budget-home",
      "name": "Budget home",
      "purpose": "Inspect shared balances and account link status",
      "primary_actor_refs": [
        "actor.owner"
      ],
      "workflow_refs": [
        "workflow.link-and-view"
      ],
      "operation_refs": [
        "operation.link-account",
        "operation.view-budget"
      ],
      "contract": [
        "Show shared balance",
        "Show link status"
      ],
      "graph_refs": [
        "promise.shared-view"
      ],
      "criticality": "critical",
      "source": "user",
      "confidence": "high",
      "relevance_reason": "Required for the current design slice"
    }
  ],
  "scenarios": [
    {
      "id": "link-failure",
      "risk_key": "provider_failure",
      "when": {
        "operation_ref": "operation.link-account"
      },
      "given": [
        "OAuth provider returns error"
      ],
      "then": [
        "Account remains unlinked",
        "User sees recoverable error"
      ],
      "covers": [
        "operation.link-account",
        "workflow.link-and-view"
      ],
      "criticality": "critical",
      "source": "user",
      "confidence": "high",
      "relevance_reason": "Required for the current design slice"
    },
    {
      "id": "empty-budget",
      "risk_key": "empty_state",
      "when": {
        "operation_ref": "operation.view-budget"
      },
      "given": [
        "No linked accounts"
      ],
      "then": [
        "Empty state explains next step to link"
      ],
      "covers": [
        "operation.view-budget",
        "invariant.household-scope"
      ],
      "criticality": "critical",
      "source": "user",
      "confidence": "high",
      "relevance_reason": "Required for the current design slice"
    },
    {
      "id": "member-denied-link",
      "risk_key": "permission_denied",
      "when": {
        "operation_ref": "operation.link-account"
      },
      "given": [
        "Actor is member not owner"
      ],
      "then": [
        "Link is denied without changing state"
      ],
      "covers": [
        "operation.link-account",
        "invariant.owner-only-link",
        "workflow.link-and-view"
      ],
      "criticality": "critical",
      "source": "user",
      "confidence": "high",
      "relevance_reason": "Required for the current design slice"
    }
  ],
  "proof_budget": {
    "strategy": "smallest_complete_slice",
    "max_critical_promises": 3,
    "max_active_operations": 10,
    "max_active_workflows": 6,
    "max_active_dependencies": 6,
    "max_active_surfaces": 6,
    "max_proofs": 12,
    "rationale": "One household link-and-view slice."
  },
  "proofs": [
    {
      "id": "shared-view",
      "promise_refs": [
        "promise.shared-view"
      ],
      "operation_refs": [
        "operation.link-account",
        "operation.view-budget"
      ],
      "workflow_ref": "workflow.link-and-view",
      "invariant_refs": [
        "invariant.household-scope",
        "invariant.owner-only-link"
      ],
      "dependency_refs": [
        "dependency.oauth"
      ],
      "surface_refs": [
        "surface.budget-home"
      ],
      "given": [
        "Owner links an account"
      ],
      "then": [
        "Member and owner see the same consolidated balance"
      ],
      "evidence_levels": [
        "boundary",
        "journey"
      ],
      "test_requirements": [
        "restart_or_reload",
        "responsive",
        "accessibility"
      ],
      "action": "Owner completes account link then opens budget home",
      "authoritative_state": "account-link.status=linked and household projection refreshed",
      "visible_outcome": "Shared balance matches for owner and member",
      "recovery": "On provider failure, account stays unlinked with retry",
      "criticality": "critical",
      "source": "user",
      "confidence": "high",
      "relevance_reason": "Required for the current design slice"
    }
  ],
  "persona_findings": [
    {
      "id": "pf-harness-developer",
      "persona_ref": "harness-developer",
      "classification": "risk",
      "finding": "Needs a reliable path through the audited flow without silent failure",
      "source": "persona_hypothesis",
      "severity": "high"
    },
    {
      "id": "pf-component-author",
      "persona_ref": "component-author",
      "classification": "risk",
      "finding": "Needs distinct recovery and trust cues when the primary path breaks",
      "source": "persona_hypothesis",
      "severity": "high"
    }
  ],
  "traceability": [
    {
      "promise_ref": "promise.shared-view",
      "graph_refs": [
        "actor.owner",
        "entity.household",
        "operation.link-account",
        "operation.view-budget",
        "workflow.link-and-view",
        "invariant.household-scope",
        "surface.budget-home",
        "scenario.link-failure"
      ]
    }
  ],
  "findings": [
    {
      "id": "finding-failure-recovery",
      "title": "Make empty/failure/permission recovery explicit",
      "severity": "high",
      "fix_target": "product",
      "evidence": "Audit of Audit the existing management dashboard for admin governance and executive visibility: failure and empty states are unclear or missing before the critical redirect.",
      "acceptance": [
        "Empty, failure, and permission states are visible before leaving the surface",
        "User can retry or recover without a dead end"
      ],
      "summary": "Missing recovery on the audited flow"
    },
    {
      "id": "finding-prioritized-checkout-trust",
      "title": "Prioritize trust and feedback before external checkout",
      "severity": "high",
      "fix_target": "product",
      "evidence": "Drop-off risk before external checkout needs clearer status, totals honesty, and mutation sequencing.",
      "acceptance": [
        "Status and totals remain truthful while mutations settle",
        "Checkout CTA waits for authoritative cart state"
      ],
      "summary": "Trust gap before external handoff"
    },
    {
      "id": "finding-ops-funnel-telemetry",
      "title": "Separate storefront vs external checkout drop-off in telemetry",
      "severity": "medium",
      "fix_target": "ops",
      "evidence": "High drop-off reported before Shopify/external checkout without stage separation.",
      "acceptance": [
        "Funnel events distinguish cart open, checkout click, and external redirect"
      ],
      "summary": "Ops measurement gap"
    }
  ],
  "evidence": []
}