busya/ss-tools
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity
Files
d874a4dca6bee2c72a07cbc129eb1e66816783a0
ss-tools/specs/038-dashboard-scenario-model/contracts/openapi-traceability.md
busya d874a4dca6 feat(speckit): workflow architecture upgrades + rework 038 spec per new flow 
Add prototype/openapi/validate/resume commands, wire edge-failure matrix into UX,
enforce traceability + validation gates, mandate C4/C5 belief-runtime verification.
Rework 038-dashboard-scenario-model artifacts: applicability, structured edge cases,
24-class UX state matrix, interactive HTML prototype, standardized OpenAPI 3.1 (7 ops),
full RTM with coverage gate, 56-task backlog, and PASS validation report.
2026-07-31 11:25:43 +03:00

3.2 KiB
Raw Blame History

#region DashboardScenarioModel.OpenApiTraceability [C:3] [TYPE ADR] [SEMANTICS openapi,traceability,scenario] @defgroup OpenAPI Trace OpenAPI operationId → data-model → spec → UX contract drift map for feature 038.

Operation Traceability

operationId Spec Requirement Data Model UX Contract Status
compileDashboardScenario AGSCN-FR-001, FR-002, FR-008, FR-009 DashboardTestScenario, ScenarioStep api-ux.md: compile ✅
validateDashboardScenario AGSCN-FR-004, FR-005 ScenarioValidationResult api-ux.md: validate ✅
resolveDashboardScenario AGSCN-FR-005 (params) ScenarioParameter, ScenarioRef api-ux.md: resolve ✅
compileScenarioDraftPack AGSCN-FR-009 (templates) DraftPack, ArtifactPlan api-ux.md: draft-pack ✅
captureScenarioScreenshot AGSCN-FR-010 ScreenshotCaptureSpec api-ux.md: capture ✅
analyzeScenarioScreenshot AGSCN-FR-011 VlmFinding, VlmAnalysis api-ux.md: vlm ✅
disposeVlmFindings AGSCN-FR-012 HumanDisposition api-ux.md: disposition ✅

Schema Traceability

Schema Source Purpose
CompileRequest data-model.md: ScenarioParameter + research §2 Compile request body
ScenarioResponse data-model.md: DashboardTestScenario Compiled graph + validation
ValidationResult data-model.md: ScenarioValidationResult Complete findings
DraftPack data-model.md: DraftPack Template-compiled draft
CaptureSpec data-model.md: ScreenshotCaptureSpec Screenshot capture config
VlmFinding data-model.md: VlmFinding Typed VLM output
ErrorEnvelope ux_reference.md §4 Standard error envelope

Drift Detection (manual review)

  • Every operationId maps to at least one spec requirement
  • Every spec requirement with an API touchpoint maps to an operationId
  • Pydantic schema names match OpenAPI schema names (data-model.md ↔ openapi.yaml)
  • Error response shapes match ux_reference.md promises (401/403/404/409/422/429/5xx)
  • Auth requirements match ADR-0005 RBAC model (scenario.compile/resolve/draft/execute)
  • Edge & Failure matrix state classes (E6 409, E7 422, E8 403, E9 429, E10 5xx, E11 stale prompt) map to response classes

Coverage Gate

  • Success examples for every operation (compile shown; others reference same envelope)
  • Error examples for every response class (401/403/409/422/429/500 + STALE_PROMPT/DOUBLE_DISPOSITION)
  • operationId on every operation (7 unique)
  • Reusable schemas (no inline anonymous schemas; ErrorEnvelope/SuccessEnvelope shared)
  • All mutating operations declare security (compile/validate/resolve/draft-pack/capture/vlm/disposition)

Validation Command

python -c "import yaml,sys; d=yaml.safe_load(open('specs/038-dashboard-scenario-model/contracts/openapi.yaml')); assert d['openapi'].startswith('3.1'); ids=[o['operationId'] for p in d['paths'].values() for m,o in p.items() if isinstance(o,dict) and 'operationId' in o]; assert len(ids)==len(set(ids))==7, ids; print('openapi-ok', len(ids))"

#endregion DashboardScenarioModel.OpenApiTraceability