diff --git a/.bootstrap/.cache/brainstorm/studio-v2-domain-model-2026-07-03/state.md b/.bootstrap/.cache/brainstorm/studio-v2-domain-model-2026-07-03/state.md new file mode 100644 index 00000000..39e69f09 --- /dev/null +++ b/.bootstrap/.cache/brainstorm/studio-v2-domain-model-2026-07-03/state.md @@ -0,0 +1,331 @@ +# Brainstorm Session — Studio v2 Domain Model + +**Session ID:** studio-v2-domain-model-2026-07-03 +**Date:** 2026-07-03 +**Rounds:** 50 +**Mode:** inline / normal +**SIMPLE_MODE:** normal +**BRAINSTORM_MAX_ROUNDS:** 10 (exceeded — continued by user choice) +**PANEL_MODE:** inline + +--- + +## Panel + +| ID | Persona | Focus | +|---|---|---| +| E1 | Domain Architect | Core graph, aggregate boundaries, invariants | +| E2 | Product Strategist | Killer workflows, user-persona coverage, ROI | +| E3 | Integration Engineer | Connectors, sync, events, external IDs | +| E4 | AI Systems Lead | Action engine, validators, cost routing | +| E5 | Enterprise Platform Lead | Workspace, RBAC/ABAC, policies, multi-tenancy | + +--- + +## Original Intent + +Разработать доменную модель для Studio v2 на основе вижена (STUDIO_VISION.md). + +--- + +## Topics Covered + +| Round | Topic | +|---|---| +| 1 | Aggregate boundaries — ShadowObject, ActionGraph, bounded contexts | +| 1C | Challenge round 1 — WorkerRun, Flow/FlowRun, GTS typeTag, versioning, Workspace | +| 2 | Connector model | +| 2C | Challenge round 2 — Connector as Worker, obj_ext, Kit permissions | +| 3 | Extensibility — vendor types, Kit, obj_ext | +| 3C | Challenge round 3 — obj_ext registry, Kit draft scope, smoke tests, WorkerImplementation | +| 4 | WorkerRun execution model | +| 4C | Challenge round 4 — sync/async, eta, checkpoint, dynamic dispatch, effectiveLimits | +| 5 | Object lifecycle & state transitions | +| 5C | Challenge round 5 — StatePolicy, x-gts-state-requires, external mapping, StateTransitionEvent | +| 6 | Role, Policy & Authorization | +| 6C | Challenge round 6 — PolicyOverride priority, condition cache, IdentityMapping, Worker→Worker, PolicyDelegation | +| 7 | AuditLog | +| 7C | Challenge round 7 — auditMode sync/async, SavedAuditQuery, write-ahead, retention, audit_exporter | +| 8 | Recommendation | +| 8C | Challenge round 8 — validationWorker, suggestedInput refresh, confidence, debounce, severityWorker | +| 9 | Events (→ Gears Events Broker) | +| 10 | Notifications | +| 10C | Challenge round 10 — NotificationRuleOverride, urgency, credentials in Settings, groupBy | +| 11 | Object type catalog (SDLC industry survey) | +| 11C | Challenge round 11 — dashboard→Insight, granularity, document base type, prompt→skill, secret_reference | +| 12 | Critical vision gaps — Action, Validator, Evidence, Connector, Object base attrs | +| 13 | Validator loop — ValidationSession, escalation, WorkerRun states | +| 14 | Flow Library — 12 Analyzers + 2 Flows | +| 15 | Killer Workflows traceability | +| 16 | Staleness model | +| 17 | Human control points — Approval model | +| 18 | Connector details — FieldMapping, WriteBackPolicy, sync protocol | +| 19 | Expansion path — automationLevel, deploymentMode | +| 20 | AI cost routing (partial — wrapped before completion) | +| 21 | Worker semantic class — kind field, incident postmortem flow, SDLC Action Workers, connector sync Workers, catalog runtime/profile, WorkerRun.cost, action Worker approval gates | +| 22 | Master Worker Catalog (37 Workers) — bug fix flow placement, per-Kit event_handler, §25 Platform Workers | +| 23 | User scenarios — user-journeys.md created, connector annotations, cost tier, automation gate | +| 24 | Studio v2 vs LangGraph/LangChain — comparison and positioning (analysis round, no decisions) | +| 25 | LangGraph/LangChain borrowings — parallelOutputMerge, conditionalRoutes, pausePoints, fallback chain | +| 26 | Interactive Workers — WorkerInteraction Object, interactionModel, awaiting_input state, cancel(), events | +| 27 | RAG — Retriever as Worker (kind: utility), Gears Models owns infrastructure, chunks outside graph | +| 28 | Worker nomenclature — Worker = registry definition, WorkerRun = execution instance; kind-labels in user-facing docs | +| 29 | Overview section added — DO1–DO6 high-level diagrams + cardinality reference table | +| 30 | Flow = Worker (kind: orchestrator) — GTS chaining; FlowRun extends WorkerRun; Kit.packages workers[] only | +| 31 | Connector does NOT extend Worker (fails "produces WorkerRun" test); design rule formalized in §4 | +| 32 | Remove Worker.kind entirely; add requiresAutomationGate: boolean; "Action" = UI concept in metadata.action | +| 33 | Input resolution: Worker.inputBindings[], Contract x-gts-source: platform|never-user only, Flow.config.steps[].inputBinding override | +| 34 | Worker.trigger split: canInvokeOnDemand + eventTrigger on Worker, defaultSchedule in WorkerImplementation | +| 35 | Flow checklist+progress: FlowRun.stepStatus map, FlowRun.activeStepId, Flow.config.stepDependencies | +| 36 | AI cost routing: ModelRouter registry entity, PromptExperiment Object, Tenant.modelOverrides | +| 37 | Kit reference architecture: Kit.metadata.referenceArchitecture + deploymentPatterns, Tenant.allowedKitPatterns | +| 38 | Closed all remaining open questions: x-gts-traits.indexes, component kind taxonomy, PromptExperiment significance, fallbackWorkerId compatibility, conditionalRoutes JSONPath, Insight=external, automationLevel hook | +| 39 | Worker dependency graph: typed deps {workerId, required, mode}; circular dep = hard block at Kit install; depth limit = runtime backstop | +| 40 | Outbound events: EventSubscription Object (webhook/event-bus), CloudEvents format default | +| 41 | Approval chains: prerequisiteApprovalId, stepNumber/totalSteps, approvalSetId, distinctApprovers, delegation fields | +| 42 | Kit versioning: KitInstallation Object, semver convention (MAJOR/MINOR/PATCH), changelog required for MAJOR | +| 43 | Data residency: x-gts-traits.contains_pii annotation, DataErasureRequest Object (GDPR); dataResidency = infra concern | +| 44 | Gears deep integration: WorkerRun.trigger metadata, §26 Gears Integration Reference, Credentials Store vs Settings Service fix | +| 45 | Studio as MCP server: Kit.mcpTools?[] (opt-in), Tenant.mcpSettings? { enabled, allowedKits, mcpRole } | +| 46 | World Model: BenchmarkSample Object (human-approved training examples), Tenant.worldModelParticipation | +| 47 | AI Cost gap: CostReport schema (breakdown, costPerAcceptedChange), Tenant.aiCostBudget, WorkerRun.costAttributedTo | +| 48 | TraceabilityReport Object (coverage%, staleLinks, gaps, complianceReady); traceability_analysis typed output Contract | +| 49 | Analyzer output contracts: Output column in §22.1; stale_artifact_detection = write exception (updates stalenessScore) | +| 50 | Operations Workers: alert_to_incident_worker, incident_triage_worker, deployment_rollback_worker in §24; runbook = Flow | + +--- + +## Decisions (85) + +### Core Domain Model + +- **Object** = base type; all domain objects extend via GTS chaining +- **Object base attrs** = `id, typeId, tenantId, state, createdAt, updatedAt, ownerId, validationStatus, stalenessScore, externalRef` +- **Worker** = first-class Studio registry entity (NOT extends Gears serverless) +- **Validator extends Worker** = adds `maxRetries, escalateTo, abortOnLimit`; output always ValidationResult +- **Flow** = first-class Studio registry entity (constraint config) +- **Kit** = first-class Studio registry entity (extension unit) +- **Connector** = first-class Studio registry entity; uses Gears OAGW as networking infrastructure +- **WorkerRun extends Object** = execution record +- **FlowRun extends Object** = flow execution record +- **Action** = Worker with state-aware Contract (no separate type) +- **WorkerRun states** = `pending|running|done|failed|escalated|aborted` + +### GTS Conventions + +- vendor = `cf` (same as Gears) +- Studio base Object: `gts.cf.studio.core.object.v1~` +- Studio base Worker: `gts.cf.studio.core.worker.v1~` +- Studio base Validator: `gts.cf.studio.core.worker.v1~cf.studio.core.validator.v1~` +- Events extend Gears: `gts.cf.core.events.type.v1~cf.studio.core..v1~` +- Tenant extends Gears RG: `gts.cf.core.rg.type.v1~cf.core._.tenant.v1~cf.studio.core.tenant.v1~` +- User extends Gears AM: `gts.cf.core.am.user.v1~cf.studio.core.user.v1~` +- Permission extends Gears: `gts.cf.toolkit.authz.permission.v1~cf.studio.core.permission.v1~` + +### Validation Loop + +- **ValidationSession** = aggregates retry loop; `state: running|pass|fail|escalated|aborted` +- **ValidationResult** = per-attempt result; `state: pass|fail|superseded|revoked` +- **Evidence** = structured proof; `state: valid|superseded|revoked`; produced by Worker output Contract +- Escalation creates `Approval` Object linked to `ValidationSession` +- Validator retry policy: Kit → Tenant → call (three levels, narrowing only) + +### Connector + +- Uses Gears OAGW upstream as networking infrastructure +- **FieldMapping.kind** = `direct|lookup|transform` (transform via Worker) +- **WriteBackPolicy** = `{ allowedActions, requiresApproval, conflictStrategy: escalate (default) }` +- **syncProtocol** = `{ push?, pull?, preferred: push }` — both optional +- **rateLimit** → passed to OAGW upstream at Kit install +- **scopeFilter** per Tenant; schema from Connector Kit + +### State & Lifecycle + +- **StatePolicy** = separate registry entity (process vs data structure) +- Transitions per-property in StatePolicy (not in GTS type schema) +- `x-gts-state-requires: { state, strict: false (default) }` in Worker Contract +- `x-gts-state-sets` in Worker output Contract +- **StateTransitionEvent** = computed projection over WorkerRun tree +- External state mapping = per Tenant config at Kit install (not in type schema) + +### Staleness + +- `stalenessScore = max(timeStaleness, dependencyStaleness, syncStaleness)` +- `stalenessPolicy: { timeTTL, dependencyTypes, recommendationThreshold }` in `x-gts-traits` +- `stale_artifact_detection` Analyzer updates asynchronously (15min cron + onEvent debounce 5m) +- Recommendation created when `stalenessScore >= threshold` + +### Authorization + +- Role = Object in graph (lifecycle, audit, Tenant-scoped) +- Policy = registry entity (Kit); PolicyOverride = Object (Tenant runtime) +- Priority: PolicyOverride > Policy (Override cannot expand beyond Policy) +- ABAC conditions = ref → Worker (returns `{ allowed, reason }`); cached with TTL (default 60s) +- IdentityMapping.externalPattern = `{ provider: GTS Type ID, pattern: string }` +- Worker→Worker authz = implicit via dependencies (both Kits approved → call authorized) +- PolicyDelegation = explicit downward grant with optional `expiresAt` + +### AuditLog + +- Materialized view over WorkerRun (CQRS + Event Sourcing) +- `auditMode: sync|async` per Worker (Tenant can override) +- Write-ahead: `externalEvents` recorded before Worker begins +- Kit Views + `SavedAuditQuery extends Object` +- `retentionAction: archive|delete` (default: archive) +- Core `audit_exporter` pre-installed; vendor formats via Kits + +### Recommendation + +- `Recommendation extends Object`; `state: pending|accepted|executing|done|dismissed|invalidated` +- `validationWorker` for auto/manual Re-check (also refreshes `suggestedInput`) +- `confidence: full|partial|low` (partial = external systems unavailable) +- `severity` static + optional `severityWorker` for dynamic recompute +- Trigger modes: `schedule`, `onEvent (+ debounce)`, `onDemand` + +### Notifications + +- `NotificationRule` = registry (Kit); `NotificationRuleOverride extends Object` (runtime on/off + expiresAt) +- `NotificationSubscription.urgency: immediate|digest|muted` +- Kit declares `requiredSettings` (secret: true); Tenant fills via Gears Settings +- Template: primary Object only + Studio deep link +- `digest.groupBy: objectId|eventType|none` +- Vendor channels via Kits; credentials in Gears Settings + +### Flow Library + +- 12 Analyzer Workers: gap_analysis, traceability_analysis, contradiction_detection, bloat_detection, + stale_artifact_detection, ownership_gap_analysis, duplicate_work_detection, + architecture_drift_detection, security_impact_analysis, test_gap_detection, + operations_metrics_analysis, ai_cost_efficiency_analysis +- 2 Flows: `bug_to_fix_pr_flow` (3 mandatory Validators), `release_readiness_review` +- Runtime: `ownership_gap_analysis` → script; `contradiction_detection`, `duplicate_work_detection` → llm; rest → hybrid +- Profile: `realtime|scheduled|on_demand` +- Worker metadata: `displayName, description, category, icon, profile` + +### Killer Workflows + +- `pull_request`: `closesIssues`, `implementsRequirements`, `conformsToDesign`, `verifiedBy` +- `test_case.verifiesRequirements: requirement[]` + `verifiesFeature?: feature_spec` +- `pr_design_validator extends Validator` (SDLC Kit, hybrid, onEvent PR → review) +- `FlowRun` sufficient for Killer Workflow 1 (no separate type needed) + +### Approval & Human Control + +- Generic `Approval` with `kind` discriminator + typed `payload` per kind +- `customerImpact?: { scope, affectedUsers, rollbackPlan }` optional +- `security_exception` payload: `expiresAt, acceptedRisk, mitigations, secondaryApprover?, autoReviewAfter?` +- `indexes` in `x-gts-traits` → persistence layer reads at schema init + +### Expansion Path + +- `Tenant.automationLevel: readonly|recommendations|approved_automation|enterprise` +- `Tenant.approvedWorkerCategories: string[]` (granular per category) +- `Tenant.deploymentMode: cloud|private|on_prem` (independent of automationLevel) +- Raising automationLevel = `Approval (kind: architecture_decision)`; lowering = no approval +- Runtime check: `automationLevel >= approved_automation AND category in approvedWorkerCategories` + +### Worker Catalog (Rounds 21–22) + +- **Worker.kind** = `action | analyzer | validator | utility` — обязательное поле первого уровня +- **incident_to_postmortem_flow** добавлен в §22.2 (entryConstraints: incident state:resolved) +- **§24 SDLC Action Workers** — 14 action Workers с Contract-примерами и двумя approval gates +- **§25 Platform Workers** — 3 pre-installed utility Workers (audit_exporter, connector_inbound_sync_worker, connector_outbound_sync_worker), `pre-installed: true` +- **Connector sync Workers** = platform Workers; per-Kit event_handler_worker в Kit manifest с именованием `{vendor}_{connector}_event_handler` +- **Worker catalog** = runtime + profile во всех таблицах §22.1, §22.2, §22.3, §24 +- **WorkerRun.cost?** = `{ promptTokens, completionTokens, modelId, estimatedCostUSD }` для llm/hybrid +- **Action Worker approval gates** = Gate 1 (automationLevel check при создании WorkerRun) + Gate 2 (WriteBackPolicy.requiresApproval для Connector write-back) — независимые +- **Master Worker Catalog** = 37 Workers: 12 analyzer + 8 validator + 14 action + 3 utility + +### User Scenarios (Round 23) + +- **user-journeys.md** создан в v2/docs/ с 14 ALGORITHM-format сценариями +- Сценарии аннотированы: `[sync: connector_name]`, `cost tier: low|medium|high`, `automation gate: none|approved_automation` + +### Input Resolution (Round 33) + +- **Contract x-gts-source** — security annotations only: `platform` (auto-resolved, reject if user provides) and `never-user` (hard reject, audit-logged) +- **Worker.inputBindings[]** — runtime resolution hints per field: `source: graph | user | chain | platform | default`, optional `query`, `fromStep`, `default` +- **Flow.config.steps[].inputBinding** — per-step override of Worker.inputBindings; same schema +- **Priority**: Flow step binding > Worker.inputBindings defaults +- **Five sources**: `graph` (GTS type picker), `user` (form/WorkerInteraction), `chain` (from previous WorkerRun output), `platform` (session context), `default` (JSON Schema default) + +### Worker Taxonomy Revision (Round 32) + +- **Worker.kind removed** — no `kind` field on Worker base; inheritance was causing confusion +- **Worker.requiresAutomationGate: boolean** (default: false) — replaces `kind == action` check in Gate 1 +- **"Action" = UI concept** — `Worker.metadata.action?: { label, icon? }` — button label shown in Studio UI when `requiresAutomationGate = true` +- **Categorization via metadata.category** — `quality | security | ops | ai-cost | traceability | retrieval | platform` — used for UI grouping and `approvedWorkerCategories` matching +- **Validator + Flow** — structural subtypes expressed through GTS chaining only; no kind field +- **§24 renamed** from "SDLC Action Workers" to "SDLC Workers (producers)" +- **Gate 1 updated**: `Worker.requiresAutomationGate == true AND automationLevel >= approved_automation AND metadata.category in approvedWorkerCategories` + +### Flow = Worker (Round 30) + +- **Flow = Worker (kind: orchestrator)** — extends Worker via GTS chaining: `gts.cf.studio.core.worker.v1~cf.studio.core.flow.v1~` +- **Worker.kind** expanded: `action | analyzer | validator | utility | orchestrator` +- **FlowRun extends WorkerRun** — adds `completedSteps: Worker[]`, `skippedSteps: Worker[]` +- **Kit.packages** — single `workers[]` collection (Flows = Workers); no separate `flows[]` +- Flow.implementation = `runtime: orchestrator`, config contains mandatorySteps + allowedNextSteps + conditionalRoutes +- Flow fields not applicable: `fallbackWorkerId`, `interactionModel` + +### RAG (Round 27) + +- **Retriever = Worker (kind: utility)** — reuses Worker/dependency mechanism; no new registry entity +- **Three pre-built Retriever Workers** (§25.2): `object_graph_retriever`, `document_retriever`, `code_retriever` +- **WorkerImplementation.retrieval?** = `{ indexKind, scope, indexRef?, strategy, topK }` — config for Retriever Workers +- **Gears Models** = embedding generation + vector storage (tenant-isolated); Studio doesn't own vector store +- **document_chunk NOT an Object** — chunks live in Gears Models; `WorkerRun.externalEvents[].chunkRef` for audit trail +- **Indexing trigger**: onEvent object_created/object_updated for Objects with indexable content + +### Interactive Workers (Round 26) + +- **WorkerInteraction extends Object** — kind: input_request | menu | free_form_intent; state: pending | answered | timed_out | cancelled; max 1 pending per WorkerRun; free_form_intent available to any Worker (not restricted to llm/hybrid) +- **Worker.interactionModel?** = `{ canRequestInput, canPresentMenu, maxPendingInteractions, cancellable }` — no acceptsFreeFormIntent (Worker decides at runtime) +- **WorkerRun.state** добавлен `awaiting_input` (отличается от paused: paused = internal pausePoint, awaiting_input = waiting for WorkerInteraction response) +- **WorkerRun** добавлены: `interactions: WorkerInteraction[]`, `cancelledBy?`, `cancelCascade?` +- **cancel(workerRunId, cascade)** операция → state: aborted, active interaction → cancelled, cascade child WorkerRuns +- **3 новых event types**: `worker_run_cancelled`, `worker_interaction_created`, `worker_interaction_answered` +- **pre-installed NotificationRule** для `worker_interaction_created` с dynamic audience из `requiredRole` +- **Domain 20 — Worker Interactions** добавлен в Appendix A + +### LangGraph/LangChain Borrowings (Round 25) + +- **Worker.fallbackWorkerId?** + `fallbackCondition: on_error | on_budget_exceeded | on_timeout` +- **WorkerImplementation.parallelOutputMerge** = `last | append | merge_by_key | custom` (default: last) — merge strategy для параллельных DAG-веток +- **WorkerImplementation.pausePoints?** = lightweight pause внутри Worker, создаёт `WorkerRun.state: paused` (не Approval Object) +- **Flow.conditionalRoutes?** = JSONPath condition для dynamic routing по runtime-результату; `allowedNextSteps` остаётся как fallback +- **WorkerRun.state** расширен: `pending | running | paused | done | failed | escalated | aborted` + +### Tech Stack & SBOM + +- Tech stack: `library`, `library_version`, `framework`, `runtime`, `database`, `database_instance`, `third_party_service`, `cloud_service`, `tech_dependency` +- SBOM: `sbom`, `sbom_component`, `sbom_relationship`, `sbom_license`, `sbom_checksum` +- Relationship kinds: `CONTAINS|DEPENDS_ON|DESCRIBES|GENERATED_FROM|VARIANT_OF` + +### Component & Release + +- `component_version`, `component_dependency (kind: uses|implements|extends|calls)` +- `release_component` join: which `component_version` in which `release` + +--- + +## Open Questions + +1. **AI cost routing** — `ModelRouter` registry entity; `PromptExperiment` A/B testing; `performance_benchmark` for AI Workers; custom enterprise models via Gears Models Registry (WorkerRun.cost field — ЗАКРЫТ в Round 21) +2. **Insight layer** — how Vision Insight layer (Connectors + Data + Analytics + Benchmarking) maps to Gears Analytics vs Studio domain +3. **Kit reference architecture** — `deploymentPattern` and `referenceArchitecture` attributes in Kit manifest +4. **`indexes` in x-gts-traits** — full spec for persistence layer (which fields, compound indexes) +5. **`automationLevel` runtime check** — exact hook point in Worker execution engine +6. **`component` kind values** — need exhaustive taxonomy (service, library, module, subsystem, frontend, backend, data-pipeline, etc.) +7. **`PromptExperiment`** — statistical significance model, traffic split mechanics +8. **Worker.fallbackWorkerId Contract compatibility** — how Registry verifies output Contract compatibility between primary and fallback Workers at Kit install time +9. **Flow.conditionalRoutes condition language** — JSONPath sufficient or needs richer expression (CEL, OPA)? + +--- + +## Output Artifacts + +- Domain model: `v2/docs/domain-model.md` +- User journeys: `v2/docs/user-journeys.md` +- Decisions: ~118 across 26 rounds +- Last session commits: `a67bb590` (diagrams), `b6523f6d` (rounds 21–22), `a3bd6632` (user-journeys.md), `82617a7e` (round 25) diff --git a/.gitignore b/.gitignore index ec020468..17149fb7 100644 --- a/.gitignore +++ b/.gitignore @@ -431,3 +431,4 @@ prompt-instruction-severity-low-med.md prompt-instruction-severity-table.md outputs/ .debug-skill/ +v2/poc/ui-1/.vite/ diff --git a/v2/docs/STUDIO_VISION.md b/v2/docs/STUDIO_VISION.md new file mode 100644 index 00000000..8d1f03cb --- /dev/null +++ b/v2/docs/STUDIO_VISION.md @@ -0,0 +1,763 @@ +--- +marp: true +theme: rose-pine-moon +paginate: true +size: 16:9 +--- + + + +> NOTE: Constructor Studio is one of the 3 main Elements of Constructor Fabric. Please read @CONSTRUCTOR_FABRIC_VISION.md first! + +# Studio + +## AI control plane for Software Engineering + +AI made code generation faster. + +Studio helps professional software development teams safely move from **product intent to production**. + +Constructor Studio is an integrated workspace – bringing together all scenarios in one place. +- It is implemented as: + - A web application in a browser + - A desktop application for macOS, Linux, Windows, iOS/Android + - A CLI that can be used from other tools (less beneficial because all the existing tools were created for developers and will not benefit all other roles) +- It is intended for: + - Product Management (CPO, Product Owner, Product Manager, Program Manager) + - UX Team (UX designers, UI designers) + - R&D (CDO, CTO, Chief Architect, Dev Manager, Developer) + - QA (QA engineers, performance engineers) + - DevOps /DCO (SRE, DevOps) + - GTM (CRO, CMO, Regional GM, Marketing Manager, Marketing Communications Manager) + + +
+For 5–500 person SaaS and service-provider teams adopting AI, but unwilling to lose control, security, traceability, or delivery quality. +
+ +--- + +# Executive Summary + +- **Market shift:** AI coding agents are making code generation cheap and fast +- **New bottleneck:** validation, coordination, governance, and production readiness +- **Product:** Studio is an open-core control plane over existing SDLC systems +- **How it works:** Studio builds a shadow SDLC graph and runs validated actions over it +- **Moat:** Open core adoption + Insight data + Studio automation + Gears kits + custom AI models and World Model +- **Customer promise:** no migration, no vendor lock-in, own your SDLC graph and workflows + +--- + +# The Problem + +AI coding tools help teams generate more code faster. +But complex software delivery still breaks across handoffs: + +- Modern AI tools were created with the R&D in mind. Other organizations and functions - Product Management, GTM - are having a hard time adopting AI using R&D-centric tools (IDEs - such as Cursor or GitHub are not the native Product Management tools for example and they require a very steep learning curve and do not provide convinient and efficient collaboration capabilities). +- Which AI work creates value vs. cost +- Which agents, models, and prompts are efficient +- Whether requirements, architecture, decisions, tests, and releases stay connected +- Whether production feedback updates future decisions + +
+The strategic problem is controlling the full AI-assisted delivery system: value, cost, architecture, decisions, validation, and production readiness. +
+ +--- + +# Why Now + +The entire software industry is adjusting to AI-assisted delivery. Automation will emerge across many categories of software development: + +- Business research + - **Identify the opportunity** - Understand what changes in the market, customer behavior, technology, or business creates an opportunity. + - **Understand the problem** - Determine which problems are worth solving. + - **Define target customers** - Decide who the product is for. + - **Quantify the value** - Estimate whether solving the problem matters. + - **Explore solution space** - Evaluate possible approaches without committing. + - **Define strategic positioning** - Decide why the product should win - identify the "magic sauce" - unique differentiators (special skills, key people, relationships, ecosystem, channel) + - **Formulate intent** - Convert research into a clear decision - should we do it or not and why +- Product and requirements work +- Architecture and design +- Coding and code review +- Testing and validation +- Release and operations +- Cost, quality, and governance control + +
+We bring 20+ years of experience building highly scalable and secure SaaS platforms — and see a major opportunity to turn AI momentum into governed, validated, production-grade SaaS software delivery. +
+ +--- + +# Initial Customer Segment + +## AI-assisted SaaS and service-provider teams + +5–500 person engineering teams that: + +- Already use AI coding tools and agents +- Have fragmented delivery systems and context +- Build production-grade, multi-tenant SaaS apps & platforms +- Need security, governance, approvals, and auditability +- Prefer open standards and no vendor lock-in + +## Buyer + +CTO, VP Engineering, Head of Platform, Head of R&D. + +--- + +# Studio Positioning + +Studio is **not** the primary system of record. + +It is the **open-core control plane for AI-native software delivery**. + +Core graph, connectors, actions, validators, and SDKs are open-source; enterprise teams can extend them without lock-in. + +```text +Existing tools stay in place +Jira | ADO | GitHub | GitLab | Bitbucket | Confluence | Office | Teams | CI | Cloud | IDEs + | + | sync / events / connectors + v +Studio shadow SDLC graph +Objects | attributes | relationships | states | history | evidence + | + | recommendations / validated actions / approved automation + v +Controlled write-back +create ticket | update doc | open PR | run CI | assign owner | create release task +``` + +--- + +# Core Idea + +## Shadow objects. Validated actions. Human-controlled automation. + +Studio mirrors work from existing systems, links it into a graph, and applies registered actions to move work forward. + +```text +PRD -> Design -> Decomposition -> Agent / Human Work -> Validation -> Release -> Operations +``` + +Every transition can be: + +- Deterministic script +- AI-assisted transformation +- Human task + +Every transition can be validated before the next step. + +--- + +# Shadow SDLC Graph + +Studio mirrors SDLC objects, intent, context, and attributes. + +
+
+ +**Objects** + +- Requirement / PRD / Design / ADR +- Task / Epic / Bug / Decision +- Repo / File / Branch / Commit / PR +- Test / Build / Release / Deployment +- Alert / Incident / Runbook / Postmortem +- Person / Team / Role / Approval + +
+
+ +**Tracked attributes** + +- Source system and external ID +- Owner, team, state, version +- Last sync and change history +- Related objects and dependencies +- Validation status and evidence +- Staleness and risk signals + +
+
+ +--- + +# Actions Are Executable Edges + +Objects are nodes. Actions are executable edges. + +```text +PRD -------- create_design() --------> Design +Design ----- decompose_feature() ----> Tasks +Task ------- implement_code() -------> Pull Request +Bug -------- create_repro_test() ----> Failing Test +PR --------- run_ci() ---------------> Build Result +Release ---- deploy() ---------------> Deployment +Incident --- create_postmortem() ----> Postmortem + Prevention Tasks +``` + +Studio is not only an analytics layer. It can recommend, prepare, validate, and execute approved actions through connectors. + +--- + +# Validated Action Graph + +Studio combines objects, relationships, actions, validators, policies, and evidence. + +```text +Object(s) + Context + Rules + | + v +Action / Transformation + | + v +Candidate Object(s) + Evidence + | + v +Validators + | + pass / fail / retry / escalate +``` + +Studio does not just generate artifacts. It validates whether work is ready to move to the next state. + +--- + +# Validator Loops + +```text + Candidate artifact + | + v + Validators + | + pass | fail + +-----------+-----------+ + | | + v v + Next task Fix / retry + | + retry < limit? + / \ + yes no + | | + v v + Candidate Human escalation + or abort +``` + +Validator loops create trust, auditability, and bounded automation. + +--- + +# First Killer Workflow + +## Bug report → reproduction → failing test → fix PR + +This is the best first demo because success is measurable. + +```text +Bug report + -> validate bug description + -> find suspected component + -> deploy test environment + -> reproduce bug + -> create failing test + -> confirm test fails on baseline + -> implement fix + -> confirm test passes after fix + -> run CI + -> create PR +``` + +--- + +# Second Killer Workflow + +## PRD → Design → Tasks → PR validation + +```text +PRD in Confluence / Office / Git + | create_design(PRD, repo, SaaS kit, templates, rules) + v +Candidate Design + | validators: coverage, architecture, security, multi-tenancy, RBAC/ABAC + v +Approved Design + | decompose_feature(Design, PRD, repo, team capacity) + v +Candidate Tasks + | validators: missing requirements, duplicates, ownership, task size + v +Jira / ADO / Linear tasks + | validate PRs against design and acceptance criteria + v +Release-ready implementation +``` + +--- + +# Studio Flow Library + +Studio ships with smart predefined flows. + +
+
+ +- Gap analysis +- Traceability analysis +- Contradiction detection +- Bloat detection +- Stale artifact detection +- Ownership-gap analysis +- Duplicate-work detection + +
+
+ +- Architecture-drift detection +- Security-impact analysis +- Test-gap detection +- Release-readiness review +- Incident-to-postmortem automation +- Operations metrics analysis +- AI-cost efficiency analysis + +
+
+ +--- + +# Example: Gap Detection + +```text +Requirement R-17 exists + | + v +No design section references R-17 + | + v +No task implements R-17 + | + v +No test covers R-17 + | + v +Studio recommends: +- update design +- create task +- add test case +- assign owner +``` + +--- + +# Human-Centric Automation + +Studio is designed to **assist and advise people**, not blindly replace them. + +
+
+ +**Studio can** + +- Detect gaps +- Recommend fixes +- Explain risks +- Prepare actions +- Validate artifacts +- Summarize context +- Automate approved changes + +
+
+ +**Humans control** + +- Product intent +- Strategic direction +- Architecture tradeoffs +- Security exceptions +- Release approvals +- Risk acceptance +- Customer-impacting actions + +
+
+ +--- + +# Platform Architecture + +```text +┌──────────────────────────────────────────────┐ +│ Studio UI │ +│ Dashboards | Graph | Recommendations | Flows │ +└─────────────────────┬────────────────────────┘ + │ +┌─────────────────────v────────────────────────┐ +│ Studio Control Plane │ +│ Shadow Graph | Actions | Validators | SDKs │ +└─────────────────────┬────────────────────────┘ + │ +┌─────────────────────v────────────────────────┐ +│ Insight: operational intelligence layer │ +│ Connectors | Data | Analytics | Benchmarking │ +└─────────────────────┬────────────────────────┘ + │ +┌─────────────────────v────────────────────────┐ +│ Existing Systems │ +│ Jira | Git | CI | Docs | Teams | IDE | Cloud │ +└──────────────────────────────────────────────┘ +``` + +--- + +# Insight Integration Advantage + +Studio integrates with **Insight**, the connector, analytics, and benchmarking layer. + +Insight can collect data from hundreds of systems: + +- Git, GitHub, GitLab, Bitbucket +- MS Office, Teams, Zoom +- Jira, ADO, Linear, Confluence +- Jenkins, GitHub Actions, GitLab CI +- Claude Code, Windsurf, IDE tools +- Cloud, observability, security, and analytics tools + +
+Insight provides cross-vendor data. Studio turns it into SDLC intelligence, recommendations, and validated actions. +
+ +--- + +# SaaS Development Kits + +Studio includes predefined kits for serious SaaS development. + +Kits package reusable delivery knowledge: + +- Reference architecture +- Templates and examples +- Actions and validators +- Rules and policies +- Recommended flows +- Deployment patterns +- Gears building blocks + +Kits can be **open-source defaults** or proprietary vendor/team packs — extensible without platform lock-in. + +--- + +# Gears Building Blocks + +Gears are reusable OSS/BSS modules, platform engines, and developer/SRE tooling. + +
+
Identity
IdP, SSO, tenant identity, user lifecycle
+
Authorization
RBAC, ABAC, granular roles, delegated administration
+
Events
event bus, schemas, routing, audit events
+
Serverless
functions, workflows, safe runtime, connectors
+
GenAI
model gateway, routing, prompts, evaluation
+
Platform
audit, billing, notifications, APIs, integrations
+
+ +--- + +# Higher Segment Than Lovable + +Studio targets higher Lovable-customers' segments where teams need: + +- Production-grade multi-tenant SaaS +- Multi-tier service-provider platforms +- Rich RBAC and ABAC +- Tenant isolation +- Granular roles and delegated administration +- Auditability and governance +- Public cloud, private cloud, and on-prem options +- Integration-heavy delivery automation + +
+Studio competes above the prototype segment: scalable, secure, governed SaaS. +
+ +--- + +# AI Cost Efficiency + +Studio is designed for AI cost control, not just AI usage. + +- Model routing by task type +- Small models for classification and extraction +- Non-GPU models for simple checks +- Large models only for hard reasoning +- Own models for repeated enterprise tasks +- Prompt/version A/B testing +- Incremental analysis & revalidation +- Quality/cost benchmarking + +
+Goal: lower AI cost per accepted change, not just more AI activity. +
+ +--- + +# Developer Experience + +Studio starts close to developer workflows. + +- CLI tools +- IDE plugins +- MCP servers +- Notifications & dashboards +- Review and acceptance assistance + +
+No migration first. Read-only analysis first. Recommendations next. Approved write-back after trust is built. +
+ +--- + +# ROI Metrics + +Studio should be measured by delivery outcomes. + +
+
+ +**Speed** + +- Faster PRD-to-task cycle +- Faster bug-to-PR cycle +- Faster release readiness review +- Less reviewer time wasted + +
+
+ +**Quality and control** + +- Higher requirement-to-test coverage +- Fewer stale design/code mismatches +- Fewer rejected AI-generated artficats +- Lower AI cost per accepted change + +
+
+ +Use these as customer proof points and pilot success metrics. + +--- + +# Business Model + +Open-core model: + +- Core graph, actions, validators, connectors, and SDKs are open-source +- SaaS subscription per active R&D user +- Platform fee for team/company workspace +- Enterprise/private deployment premium +- Proprietary connector, kit, policy, and benchmark packs +- AI usage optimization or usage margin +- Professional services for proprietary kits and workflow rollout + +Expansion path: + +```text +Read-only insights -> recommendations -> approved automation -> enterprise control plane +``` + +--- + +# Moat Flywheel + +```text +Open-source core adoption + -> more connectors and community flows + -> richer shadow SDLC graph + -> better validators + -> better recommendations + -> more accepted automations + -> more workflow evidence + -> stronger kits, benchmarks, and enterprise pull +``` + +
+The moat is not one model or one agent. It is open-core distribution plus the SDLC graph, validated workflows, reusable kits, and accumulated evidence. +
+ +--- + + + +# Competitor Landscape + +| Category | Examples | Main strength | Studio angle | +|---|---|---|---| +| AI app builders | Lovable, Bolt, v0 | Fast prototypes | Higher segment: secure SaaS, no lock-in | +| AI coding tools | Cursor, Claude Code, Windsurf | Developer productivity | Govern across tools, keep user choice | +| Repo platforms | GitHub Copilot, GitLab Duo | Code, PR, DevSecOps | Cross-vendor graph and validation | +| Work systems | Atlassian Rovo | Jira/work-item centered execution | Tool-agnostic open control plane | +| DevOps platforms | GitLab, Harness, GitHub | CI/CD, security, deployment | Improve work across systems | +| Autonomous agents | Devin-like systems | Task execution | Evidence, validators, human control | + +--- + +# Competitive Map + +```text + Production / Governance Focused + ^ + | + GitLab / Harness | Studio + GitHub / Atlassian | cross-SDLC control plane + | +Single-tool / ecosystem --------------+-------------- Cross-tool / vendor-neutral + | + Cursor / Windsurf | emerging gap + Claude Code | + | + Lovable / Bolt / v0 | + v + Prototype Focused +``` + +Studio should not fight every tool directly. It should orchestrate and govern across them — with open-core trust and no vendor lock-in. + +--- + + + +# Studio vs Lovable + +| Dimension | Lovable-style tools | Studio | +|---|---|---| +| Prototype speed | Strong | Good | +| Production SaaS | Partial | Core focus | +| Multi-tenancy | Limited | Core focus | +| RBAC / ABAC | Basic | Rich model | +| Service providers | Not primary | Core focus | +| Existing tool control | Limited | Core focus | +| On-prem/private deployment | Limited | Supported | +| Open core / no lock-in | Limited | Core focus | +| SDLC graph | Limited | Core architecture | +| Validators | Basic | Core architecture | + +**Studio competes above prototypes: production SaaS, extensible core, no lock-in.** + +--- + + + +# Studio vs AI Coding Tools + +| Dimension | Cursor / Windsurf / Claude Code | Studio | +|---|---|---| +| Developer coding | Strong | Integrated | +| Local context | Strong | Strong via plugins | +| Cross-tool SDLC graph | Limited | Core | +| Product-to-code flow | Partial | Core | +| Validation loops | Partial | Core | +| Management visibility | Limited | Core | +| Governance | Limited | Core | +| Connector write-back | Limited | Core | +| Open workflow layer | Limited | Open core | + +Studio should integrate with these tools, not replace them — users keep their IDE and model choices. + +--- + + + +# Studio vs DevOps Platforms + +| Dimension | GitHub / GitLab / Harness | Studio | +|---|---|---| +| CI/CD | Strong | Integrates | +| Repo / PR workflows | Strong | Integrates | +| Product and design context | Partial | Strong | +| Cross-vendor graph | Limited | Core | +| SaaS kits | Limited | Core | +| AI cost routing | Partial | Core | +| Shadow object model | Limited | Core | +| Human recommendation layer | Partial | Core | +| Vendor lock-in | High ecosystem pull | Avoided by open core | + +Studio does not need to beat them at CI/CD. Studio improves work across them while reducing ecosystem lock-in. + +--- + +# Credible Wedge + +#### Phase 1: Studio CLI PoC + +- Repo-local CLI setup and IDE agent integration +- SDLC kit: PRD → DESIGN → decomposition → FEATURE → implementation +- Deterministic checks for artifacts, traceability, language, and links +- Dependency map across documents, code, tests, and reviews + +#### Phase 2: Validated actions + +- Gap analysis +- Contradiction detection +- Autonomous bug-fixing +- PR validation + +--- + +# Expansion Roadmap + +#### Phase 3: Centralized automation + +- Team and role-based workspaces and collaboration +- Visual workflow builder and flow catalog +- UI/UX for workflows, approvals, exceptions, evidence, and handoffs +- Notifications and alerts for gaps, risks, stale work, and failures +- Dashboards for delivery health, AI cost, and release readiness + +#### Phase 4: Enterprise control plane + +- Insight integration at scale +- Private/on-prem deployment +- Advanced AI and world model +- Operations automation + +--- + +# Key Investor Objections + +## “This is too broad.” + +Start with one wedge: validated workflows over existing tools for AI-assisted SaaS teams. + +## “GitHub, GitLab, Atlassian will build this.” + +They optimize their own ecosystems. Studio is open-core, cross-vendor, and integrates with Insight and Gears to complete development automation. + +## “How do you prove ROI?” + +Measure accepted PR rate, AI cost per accepted change, PRD-to-task cycle time, test coverage, release-readiness time, and review time saved. + +--- + +# Closing + +Studio is the **AI control plane for Software Engineering**. + +It works with existing tools, not against them. + +Its open core gives teams ownership, extensibility, and no vendor lock-in. + +It mirrors the SDLC, detects gaps, recommends improvements, and runs validated actions across the lifecycle. + +
+Studio helps serious SaaS and service-provider teams build faster — without losing control, security, traceability, or production quality. +
diff --git a/v2/docs/domain-model.md b/v2/docs/domain-model.md new file mode 100644 index 00000000..634a39cc --- /dev/null +++ b/v2/docs/domain-model.md @@ -0,0 +1,4140 @@ +# Studio v2 — Domain Model + +> Status: **draft** — result of a brainstorm session, requires final validation. + +--- + +## Overview + +Studio v2 is built on two fundamental worlds: + +- **Registry entities** — definitions, rules, and configurations that live *outside* the Object graph. They describe what can happen: what Workers exist, what Flows constrain them, how Connectors integrate external systems, what Policies govern access. Registry entities are code and configuration — versioned, packaged in Kits, installed by Tenants. +- **Objects** — runtime instances that live *inside* the Object graph. They record what is happening and what happened: WorkerRuns, FlowRuns, Recommendations, Approvals, Evidence, user-created artifacts. Every Object belongs to exactly one Tenant and carries a GTS Type ID. + +These two worlds are connected by execution: a Worker (definition) produces WorkerRun instances (execution records). A Flow (definition) produces FlowRun instances. Connectors sync external data as Objects. Workers modify Objects and emit Events that drive the next round of automation. + +--- + +### DO1 — Three-Tier Architecture + +```mermaid +flowchart TB + subgraph GEARS["Gears Platform — Infrastructure"] + G["Events Broker · Notifications · Account Management · RBAC/ABAC\nOAGW · Models Gateway · Settings\nTenant (Gears RG) · User (Gears AM)"] + end + + subgraph REGISTRY["Registry Layer — Definitions (outside graph)"] + R["Worker · Flow · Kit · Connector\nStatePolicy · Policy · NotificationRule\nWorkerImplementation · obj_ext"] + end + + subgraph GRAPH["Object Graph — Runtime Instances\n(gts.cf.studio.core.object.v1~ base)"] + O["Workspace · Role · WorkerRun · FlowRun\nRecommendation · Approval · ValidationSession\nEvidence · WorkerInteraction\n…all domain types (task, PR, incident, design, …)"] + end + + REGISTRY -->|executes / produces| GRAPH + REGISTRY -->|uses as infrastructure| GEARS + GRAPH -->|emits events / extends| GEARS + GRAPH -->|governed by| REGISTRY +``` + +--- + +### D1 — Registry vs Object Graph (entities) + +```mermaid +flowchart TD + subgraph Registry["Registry Entities (outside graph)"] + Worker["Worker\n(contract + deps)"] + WI["WorkerImplementation\n(runtime config)"] + Flow["Flow\n(constraint config)"] + Kit["Kit\n(extension unit)"] + end + + subgraph Graph["Object Graph"] + Object["Object\n(base type)"] + WorkerRun["WorkerRun\nextends Object"] + FlowRun["FlowRun\nextends Object"] + end + + Worker -->|versioned by| WI + Worker -->|packaged in| Kit + Flow -->|packaged in| Kit + Worker -->|execution produces| WorkerRun + Flow -->|execution produces| FlowRun + WorkerRun -->|extends| Object + FlowRun -->|extends| Object +``` + +--- + +### DO1b — Layers with Entity Names + +``` +┌─────────────────────────────────────────────────────────────┐ +│ GEARS INFRASTRUCTURE │ +│ Events Broker · Notifications · Approvals · Jobs Manager │ +│ LLM Gateway · AI Agents Registry · Settings Service │ +└─────────────────────────────────────────────────────────────┘ + ▲ Studio builds on Gears +┌─────────────────────────────────────────────────────────────┐ +│ REGISTRY ENTITIES │ +│ │ +│ Worker ──────────── WorkerImplementation │ +│ Flow obj_ext Kit StatePolicy NotificationRule │ +│ Policy │ +└─────────────────────────────────┬───────────────────────────┘ + │ executes / produces + ▼ +┌─────────────────────────────────────────────────────────────┐ +│ GEARS INFRASTRUCTURE │ +│ Events Broker · Notifications · Approvals · Jobs Manager │ +│ LLM Gateway · AI Agents Registry · Settings Service │ +│ Tenant (gts.cf.core.rg.type.v1~...cf.studio.tenant.v1~) │ +│ User (gts.cf.core.am.user.v1~...cf.studio.user.v1~) │ +└─────────────────────────────────────────────────────────────┘ + ▲ Studio builds on Gears +┌─────────────────────────────────────────────────────────────┐ +│ REGISTRY ENTITIES │ +│ │ +│ Worker ──────────── WorkerImplementation │ +│ Flow obj_ext Kit StatePolicy NotificationRule │ +│ Policy │ +└─────────────────────────────────┬───────────────────────────┘ + │ executes / produces + ▼ +┌─────────────────────────────────────────────────────────────┐ +│ OBJECT GRAPH (gts.cf.studio.core.object.v1~) │ +│ │ +│ Workspace WorkerRun FlowRun Role │ +│ Requirement Task PullRequest Build │ +│ Design Incident Recommendation │ +│ IdentityMapping PolicyOverride PolicyDelegation │ +│ SavedAuditQuery NotificationRuleOverride NotificationSub │ +└─────────────────────────────────────────────────────────────┘ +``` + +--- + +### DO2 — Registry Entity Relationships + +```mermaid +classDiagram + class Kit { + scope + } + class Worker { + requiresAutomationGate: bool + } + class Flow + class Connector + class WorkerImplementation { + runtime: llm|script|hybrid + } + class Contract["Contract (GTS Schema)"] + class StatePolicy + class Policy + class NotificationRule + + Kit "1" --> "0..*" Worker : packages + Kit "1" --> "0..*" Flow : packages + Kit "1" --> "0..*" Connector : packages + Kit "1" --> "0..*" NotificationRule : packages + + Worker "1" --> "1" WorkerImplementation : implements via + Worker "1" --> "1" Contract : input + Worker "1" --> "1" Contract : output + Worker "0..*" --> "0..*" Worker : dependencies (static) + Worker "0..1" --> "0..1" Worker : fallback + + Flow "1" --> "1..*" Worker : mandatorySteps + Flow "1" --> "0..*" Worker : allowedNextSteps + + StatePolicy --> Worker : appliesTo (GTS type) +``` + +--- + +### DO3 — Object Graph Foundations + +Note: `Tenant` and `User` extend **Gears base types** (RG and AM respectively) via GTS +chaining — they do not extend `gts.cf.studio.core.object.v1~`. See §2.2. + +```mermaid +classDiagram + class Object { + id · typeId · tenantId + state · createdAt · updatedAt + ownerId · validationStatus + stalenessScore · externalRef + } + class GearsRG["Gears RG\n(gts.cf.core.rg.type.v1~)"] + class GearsAM["Gears AM User\n(gts.cf.core.am.user.v1~)"] + class Tenant["Tenant\n(extends Gears RG)"] + class User["User\n(extends Gears AM)"] + class Workspace + class Role + class WorkerRun + class FlowRun + class Recommendation + class Approval + class ValidationSession + class WorkerInteraction + class Evidence + + GearsRG <|-- Tenant + GearsAM <|-- User + Object <|-- Workspace + Object <|-- Role + Object <|-- WorkerRun + Object <|-- FlowRun + Object <|-- Recommendation + Object <|-- Approval + Object <|-- ValidationSession + Object <|-- WorkerInteraction + Object <|-- Evidence + + Tenant "0..*" --> "0..1" Tenant : parent (sub-tenant hierarchy) + Object "0..*" --> "1" Tenant : belongs to +``` + +--- + +### DO4 — Execution Model + +How definitions become execution records, and how execution records relate to each other. + +```mermaid +flowchart LR + W["Worker\n(definition)"] + F["Flow\n(definition)"] + C["Connector\n(definition)"] + + WR["WorkerRun\n(execution)"] + FR["FlowRun\n(execution)"] + OBJ["Object\n(domain artifact)"] + WI["WorkerInteraction\n0..* per run"] + EV["Evidence\n(immutable proof)"] + REC["Recommendation"] + VS["ValidationSession"] + + W -->|"1 definition\n→ 0..* executions"| WR + F -->|"1 definition\n→ 0..* executions"| FR + FR -->|"ordered steps\n1..* WorkerRuns"| WR + WR -->|"parent–child tree\n(sub-Worker calls)"| WR + C -->|"inbound sync\ncreates / updates"| OBJ + WR -->|"reads / writes"| OBJ + WR -->|"awaiting_input\n0..1 active at a time"| WI + WR -->|"produces on pass"| EV + WR -->|"creates on gap"| REC + WR -->|"aggregated by"| VS + VS -->|"on escalation\ncreates"| Approval["Approval"] +``` + +--- + +### DO5 — Authorization & Tenant Model + +```mermaid +classDiagram + class Tenant["Tenant\n(extends Gears RG)"] { + automationLevel + approvedWorkerCategories + deploymentMode + } + class User["User\n(extends Gears AM)"] + class Role + class Policy { + rules: Rule[] + } + class PolicyOverride["PolicyOverride\n(narrows Policy at runtime)"] + class PolicyDelegation["PolicyDelegation\n(parent grants rights downward)"] + class IdentityMapping["IdentityMapping\n(SSO → Role)"] + class Kit + + User "0..*" --> "0..*" Role : RoleAssignment + Role --> Policy : governed by + Policy <|-- PolicyOverride : narrows (Tenant override) + Tenant "1" --> "0..*" Tenant : sub-tenant hierarchy + Tenant "1" --> "0..*" PolicyDelegation : grants downward + Tenant "1" --> "0..*" IdentityMapping : SSO mapping + Tenant "0..*" --> "0..*" Kit : installed Kits (approved) +``` + +--- + +### DO6 — Cardinality Reference + +| Relationship | Cardinality | Notes | +|---|---|---| +| Tenant → Object | 1 : many | Every Object belongs to exactly one Tenant | +| Tenant → Tenant | 0..1 : many | Sub-tenant hierarchy; narrowing only | +| Tenant → Kit | many : many | Kit installed per Tenant with explicit approval | +| Kit → Worker | 1 : many | Kit packages and owns its Workers | +| Worker → WorkerImplementation | 1 : 1 | Versioned independently | +| Worker → Contract (input/output) | 1 : 1 each | Typed GTS Schema | +| Worker → Worker (dependencies) | many : many | Static, declared, security boundary | +| Worker → WorkerRun | 1 : many | One definition, many execution records | +| Flow → Worker (steps) | 1 : many | mandatorySteps + allowedNextSteps | +| Flow → FlowRun | 1 : many | | +| FlowRun → WorkerRun | 1 : many | Ordered step executions | +| WorkerRun → WorkerRun | 1 : many | Parent–child sub-Worker call tree | +| WorkerRun → WorkerInteraction | 1 : many | Max 1 pending at a time | +| ValidationSession → WorkerRun | 1 : many | Retry attempts | +| ValidationSession → Evidence | 1 : 0..1 | Final Evidence on pass | +| Recommendation → WorkerRun | many : 1 | sourceRunId (Analyzer that found gap) | +| User → Role | many : many | Via RoleAssignment | +| Role → Policy | many : many | | +| PolicyOverride → Policy | many : 1 | Narrows, never expands | + +--- + +The system consists of two categories of entities: + +- **Object** — data and artifacts that flow through the system (the graph) +- **Registry entities** — Worker, Flow, Kit, etc. (outside the graph; templates/configurations) + +## 1. Entities + +### 1.1 Object + +The base type for all domain objects in the system. + +``` +Object { + id: GTS Instance Identifier + typeId: GTS Type Identifier + tenantId: ref → Tenant + state: string + createdAt: datetime + updatedAt: datetime + // Vision-required attributes (gap analysis, staleness, ownership, external sync): + ownerId: ref team | person? + validationStatus: none|pending|pass|fail + stalenessScore: float? // 0.0 = fresh, 1.0 = stale + // = max(timeStaleness, dependencyStaleness, syncStaleness) + externalRef?: { + connectorId: ref Connector + externalId: string + externalUrl: string + lastSyncedAt: datetime + } + createdObjectIds?: ref → Object[] // Objects materialized by platform from this WorkerRun + // "Attached" WorkerRun = has createdObjectIds + // "Free-standing" = no Objects created (Analyzer runs, etc.) + // Inverse of Object.createdByRunId + + // --- PROVENANCE (system-managed, immutable after set) --- + // Distinct from links[] (semantic, user/Worker declared, mutable). + // Provenance = "who created/modified this Object" (system fact). + // Semantic links = "how this Object relates to others in business context". + createdByRunId?: ref → WorkerRun // WorkerRun that created this Object; null if user-created + lastModifiedByRunId?: ref → WorkerRun // WorkerRun that last modified; null if user-modified + // Cost attribution chain: Object → WorkerRun.cost → WorkerRun.costAttributedTo → User/Flow + + // --- CAPABILITIES (opt-in via x-gts-traits.capabilities) --- + // Object types declare which capabilities they support: + // "linkable" → links[], concurrentEditors, writeLock are meaningful + // "tracked" → createdByRunId, lastModifiedByRunId are set by platform + // "versioned" → supersedes pattern; state "superseded" reserved + // Execution records (WorkerRun, Evidence, etc.) and infra types declare no capabilities. + workspaceId?: ref → Workspace // workspace scope; set by platform from WorkerRun.costAttributedTo + // used by is_workspace_member_worker for ABAC conditions + // NOT applicable to execution records (WorkerRun, Evidence, ValidationSession, + // WorkerInteraction, FlowRun) — they are immutable or have specialized lifecycle + concurrentEditors?: [ // "you are not alone" — visibility of concurrent access + { + agentId: ref → Object // WorkerRun or User (both extend Object) + agentType: worker_run | user // discriminator + intent: read | write + since: datetime + expiresAt: datetime // safety timeout; platform expires if agent dies + } + ] + // Platform auto-registers WorkerRun on start; auto-deregisters on complete/fail + // Workers react via WorkerInteraction or queue; this is NOT a lock + writeLock?: { // optional hard exclusive lock + lockedBy: ref → Object // WorkerRun or User + lockedType: worker_run | user + lockedAt: datetime + expiresAt: datetime // auto-expires; prevents deadlock on Worker failure + // platform auto-releases on WorkerRun complete/fail + // other write attempts → ConflictError while lock held + } + links?: [ // Jira-style typed graph edges + // NOT applicable to execution records: + // WorkerRun, Evidence, ValidationSession, + // WorkerInteraction, FlowRun use specialized refs + { + targetId: ref → Object // any Object in the graph (typeId derived from target) + kind: GTS Type ID // link kind — all kinds are GTS Type IDs + // core kinds: gts.cf.studio.link.kind.v1~{name}.v1~ + // kit kinds: same format, registered in Types Registry at Kit install + // UI shows displayName from Types Registry + // source: exactly one of createdBy or sourceRunId must be set + createdBy?: ref → User // set when user-declared + sourceRunId?: ref → WorkerRun // set when platform-inferred from WorkerRun provenance + } + ] +} + +// Core LINK_KIND GTS Type IDs (pre-registered in Gears Types Registry): +// gts.cf.studio.link.kind.v1~derived_from.v1~ — B created from A (prd→design) +// gts.cf.studio.link.kind.v1~decomposes_into.v1~ — A breaks down into B items +// gts.cf.studio.link.kind.v1~implements.v1~ — A implements requirement B +// gts.cf.studio.link.kind.v1~references.v1~ — weak link: A uses B as context +// gts.cf.studio.link.kind.v1~incorporates.v1~ — A merges or extends B +// gts.cf.studio.link.kind.v1~validates.v1~ — A proves B correct +// gts.cf.studio.link.kind.v1~supersedes.v1~ — A replaces B (versioning) +// gts.cf.studio.link.kind.v1~informs.v1~ — A provides context for B +// +// Kit-extensible: Kit registers custom link kinds in Types Registry at install. +// Platform traverses core kinds in traceability computation; +// custom kinds stored and returned in queries but not analysed for gaps. +// +// Cross-workspace link rules: +// Cross-Tenant: FORBIDDEN — enforced at link creation (target.tenantId must == source.tenantId) +// Cross-workspace (same Tenant): ALLOWED — access to target subject to Policy checks +// Tenant-level Objects (workspaceId=null): implicitly shared — any workspace can link to them +// Recommended pattern for shared artifacts (PRDs, ADRs, architecture guidelines): +// create with workspaceId=null → no workspace restriction on linking + +// Two-layer model: +// Object.links[] = flexible, user- and platform-declared contextual links +// Spec-level fields (pull_request.conformsToDesign, test_case.verifiesRequirements) +// remain as explicit Contract fields — required by Validator Workers +// +// Graph traversal API (Gears platform): +// GET /objects/{id}/links?kind={GTS_kind_ID}&depth=N&direction=outgoing|incoming|both +// GET /objects/{id} + OData $filter for filtered Object queries +// effectiveLimits.depth = max traversal depth backstop per WorkerRun +// Workers maintain visited-set to prevent cycles; depth limit as safety net +``` + +### D2 — Object Base Hierarchy + +```mermaid +classDiagram + class Object { + id: GTS Instance ID + typeId: GTS Type ID + tenantId: ref Tenant + state: string + createdAt: datetime + updatedAt: datetime + } + class GearsRG["Gears RG base"] + class GearsAM["Gears AM User base"] + class Tenant["Tenant\n(extends Gears RG)"] + class User["User\n(extends Gears AM)"] + class Workspace + class WorkerRun + class FlowRun + class Role + class Recommendation + + GearsRG <|-- Tenant + GearsAM <|-- User + Object <|-- Workspace + Object <|-- WorkerRun + Object <|-- FlowRun + Object <|-- Role + Object <|-- Recommendation +``` + +Studio Objects derive from `gts.cf.studio.core.object.v1~` via GTS chaining. +`Tenant` and `User` are Gears-native types extended via GTS — see §2.2. + +### 1.2 Registry Entities + +Outside the graph. Describe rules and configurations, not data. + +| Entity | Purpose | +|---|---| +| `Worker` | **Definition** of a typed, reusable capability (not a process). Execution creates a WorkerRun. | +| `Validator` | Extends Worker; adds retry loop, escalation, maxRetries semantics | +| `WorkerImplementation` | Runtime configuration of a Worker (model, prompt, script) | +| `Flow` | Worker extension (GTS chain) — sequences mandatory steps; packaged in Kit alongside other Workers | +| `Connector` | Integration with external system via Gears OAGW (field mapping, write-back, sync) | +| `Kit` | Extension packaging unit (types, Workers of all kinds incl. orchestrators, Connectors) | +| `obj_ext` | Attribute extension for existing types | +| `StatePolicy` | Per-property transition rules (separate from type schema) | + +--- + +## 2. GTS Identifiers + +**Convention:** `gts.....v` + +Studio vendor = `cf` (same as Constructor Fabric Gears). + +### 2.0 GTS Type ID Versioning Policy + +| Change tier | Contract rule | typeId rule | Existing Objects | +|---|---|---|---| +| PATCH | WorkerImpl only; Contract unchanged | Same typeId | Unaffected | +| MINOR | Additive (optional fields only) | New typeId via **GTS subtype chaining** from previous | Backward compat; v1 readable as v2 | +| MAJOR | Breaking (required fields, removals, renames) | New independent typeId; old Worker.deprecatedBy → new | Frozen at old typeId; never retroactively changed | + +**Execution records (WorkerRun, Evidence):** typeId is **immutable** after creation. WorkerRun.workerId always reflects the Worker version that produced it. Retroactive re-typing is forbidden — it violates the audit trail invariant. + +**Domain Objects (design, requirement, etc.) on MAJOR change:** Kit may provide an opt-in `migration_worker` that produces a new Object at the new typeId. The old Object survives unchanged. `migration_worker` cannot modify WorkerRun or Evidence. + +**MINOR enforcement:** Kit Registry rejects publish of a MINOR version whose new Contract typeId does not chain from the previous version typeId via GTS subtype chaining. + +**Active version discovery:** Query Gears Types Registry (`GET /types/active?workerId=X`) to enumerate all active Contract typeIds for a Worker. This is Gears infrastructure — not a domain model field. + +### 2.1 Studio Base Types + +Studio-owned base types: + +``` +gts.cf.studio.core.object.v1~ ← base Object (all Studio domain objects) +gts.cf.studio.core.worker.v1~ ← base Worker (definition) +gts.cf.studio.core.worker.v1~cf.studio.core.validator.v1~ + ← Validator = Worker extension via GTS chaining +gts.cf.studio.core.worker.v1~cf.studio.core.flow.v1~ + ← Flow = Worker extension via GTS chaining (orchestration semantics) +gts.cf.studio.core.connector.v1~ ← registry entity; uses Gears OAGW as infrastructure +gts.cf.studio.core.kit.v1~ ← extension packaging unit +gts.cf.studio.core.obj_ext.v1~ ← attribute extension +gts.cf.studio.link.kind.v1~ ← base type for all Object link kinds (core + Kit-extensible) +``` + +Studio event types extend the **Gears platform event base type**: + +``` +gts.cf.core.events.type.v1~ ← Gears platform event base type (DO NOT redefine) +``` + +### 2.2 Gears Base Types Extended by Studio + +Studio extends existing Gears base types where applicable: + +| Studio Type | Extends Gears Type | Chained GTS ID | +|---|---|---| +| `Tenant` | `gts.cf.core.rg.type.v1~cf.core._.tenant.v1~` | `gts.cf.core.rg.type.v1~cf.core._.tenant.v1~cf.studio.core.tenant.v1~` | +| `User` | `gts.cf.core.am.user.v1~` | `gts.cf.core.am.user.v1~cf.studio.core.user.v1~` | +| `Permission` | `gts.cf.toolkit.authz.permission.v1~` | `gts.cf.toolkit.authz.permission.v1~cf.studio.core.permission.v1~` | + +### 2.3 Studio Core Object Types (derived from Studio base) + +``` +gts.cf.studio.core.object.v1~cf.studio.core.workspace.v1~ +gts.cf.studio.core.object.v1~cf.studio.core.requirement.v1~ +gts.cf.studio.core.object.v1~cf.studio.core.task.v1~ +gts.cf.studio.core.object.v1~cf.studio.core.pull_request.v1~ +gts.cf.studio.core.object.v1~cf.studio.core.build.v1~ +gts.cf.studio.core.object.v1~cf.studio.core.incident.v1~ +gts.cf.studio.core.object.v1~cf.studio.core.design.v1~ +gts.cf.studio.core.object.v1~cf.studio.core.worker_run.v1~ +gts.cf.studio.core.object.v1~cf.studio.core.flow_run.v1~ +gts.cf.studio.core.object.v1~cf.studio.core.role.v1~ +gts.cf.studio.core.object.v1~cf.studio.core.recommendation.v1~ +gts.cf.studio.core.object.v1~cf.studio.core.identity_mapping.v1~ +gts.cf.studio.core.object.v1~cf.studio.core.policy_override.v1~ +gts.cf.studio.core.object.v1~cf.studio.core.policy_delegation.v1~ +gts.cf.studio.core.object.v1~cf.studio.core.saved_audit_query.v1~ +gts.cf.studio.core.object.v1~cf.studio.core.notification_rule_override.v1~ +gts.cf.studio.core.object.v1~cf.studio.core.notification_subscription.v1~ +gts.cf.studio.core.object.v1~cf.studio.core.worker_interaction.v1~ +gts.cf.studio.core.object.v1~cf.studio.core.prompt_experiment.v1~ +gts.cf.studio.core.object.v1~cf.studio.core.event_subscription.v1~ +gts.cf.studio.core.object.v1~cf.studio.core.kit_installation.v1~ +gts.cf.studio.core.object.v1~cf.studio.core.data_erasure_request.v1~ +``` + +### 2.4 Vendor (Kit) Extensions + +``` +// Narrowing — new semantic type: +gts.cf.studio.core.object.v1~cf.studio.core.task.v1~jira.studio.core.jira_task.v1~ + +// Attribute extension via obj_ext: +gts.cf.studio.core.obj_ext.v1~jira.studio.core.jira_task_ext.v1~ +``` + +--- + +## 3. Contract + +Contract = **GTS Type Schema** (JSONSchema + `x-gts-*` extensions). + +Describes what a Worker expects as input and what it produces as output. +Object type references use `$ref` → GTS Type Identifier. Scalar properties +use standard JSON Schema fields. **GTS does not duplicate JSON Schema features:** +required fields use the standard `required` array, not a custom annotation. + +`x-gts-*` extensions are only for concepts JSON Schema does not have: state +awareness (`x-gts-state-requires`, `x-gts-state-sets`), platform security +(`x-gts-source: platform | never-user`), traits + indexes (`x-gts-traits`), +output materialization (`x-gts-creates`). + +`x-gts-creates: boolean` — on output Contract fields: platform materializes Object in graph +on WorkerRun completion. Worker returns raw data; platform creates Object with full security +context (tenantId, workspaceId, ownerId, createdByRunId auto-set): + +```json +// Output Contract example: +{ + "properties": { + "design": { + "$ref": "gts://...design.v1~", + "x-gts-creates": true // platform creates design Object in graph + }, + "debug_info": { "type": "string" } // no x-gts-creates → raw data only + } +} +``` + +Materialization flow (order matters; non-atomic; idempotent): + 0. Check WorkerRun.createdObjectIds: if already populated → skip step 1 (idempotent retry) + 1. x-gts-creates: create new Objects; set Object.createdByRunId, workspaceId, ownerId + 2. x-gts-state-sets: update input Object states + 3. Auto-create `derived_from` links (confidence: inferred, sourceRunId: WorkerRun) from new Objects + to input Objects marked with `x-gts-link: true` (OPT-IN — not all $ref fields): + "prd": { "$ref": "...prd.v1~", "x-gts-link": true } // → derived_from link created + "workspace": { "$ref": "...workspace.v1~" } // → no link (default; context field) + Analyzer Workers typically have no x-gts-link: true fields → no exponential auto-links. + 4. WorkerRun.createdObjectIds = [new Object ids] + +`x-gts-traits.capabilities` — opt-in Object capabilities declaration: + +```json +"x-gts-traits": { + "capabilities": ["linkable", "tracked"] +} +``` + +- `linkable` — Object supports `links[]`, `concurrentEditors`, `writeLock` +- `tracked` — Object supports `createdByRunId`, `lastModifiedByRunId` +- `versioned` — SDLC artifact; uses supersedes pattern when content changes: + create new Object + `links[kind=supersedes]` + old Object.state → `superseded`. + Evidence and links remain accurate for old version. + `traceability_analysis` excludes `superseded` Objects from coverage computation. + Applies to: prd, design, requirement, decomposition, feature_spec, adr. + Auto-transition: platform sets old Object.state → superseded when supersedes link added. + StatePolicy may require Approval for superseded transition on critical types (prd, design). +- Execution records and infra types declare no capabilities. +- Platform uses capabilities to apply appropriate behaviors. + +**Reserved `Object.state` value:** `superseded` — Object replaced by newer version. +Available to `versioned` types. Excluded from default traceability queries. + +**Two versioning strategies:** +- SDLC Artifacts (versioned): create new Object + supersedes link + old → superseded. + Preserves Evidence integrity for old version. +- Operational Entities (task, bug, pull_request): mutable via StatePolicy; no versioning. + +`x-gts-traits.indexes` — hint to persistence layer which fields to index: + +```json +"x-gts-traits": { + "indexes": [ + { "fields": ["tenantId", "state"], "unique": false }, + { "fields": ["workerId"], "unique": false }, + { "fields": ["externalRef.externalId", "externalRef.connectorId"], "unique": true } + ] +} +``` + +`x-gts-traits.contains_pii` — marks Object types that carry personally identifiable information: + +```json +"x-gts-traits": { + "contains_pii": true, + "pii_fields": ["assignee", "description", "externalRef.externalId", "payload.*"] + // dot-notation paths; wildcard * = all fields within that prefix +} +``` + +Platform applies strict retention policy to Objects of PII-annotated types. +WorkerRuns whose input/output Objects are PII-annotated inherit strict TTL enforcement. + +```json +{ + "$id": "gts.cf.studio.core.worker.v1~cf.studio.core.create_design_input.v1~", + "type": "object", + "required": ["requirement", "workspace"], + "properties": { + "requirement": { + "$ref": "gts://cf.studio.core.object.v1~cf.studio.core.requirement.v1~" + }, + "workspace": { + "$ref": "gts://cf.studio.core.object.v1~cf.studio.core.workspace.v1~", + "x-gts-source": "platform" + }, + "style": { "type": "string", "enum": ["detailed", "sketch"] }, + "language": { "type": "string" } + } +} +``` + +Contract carries two security-scoped `x-gts-source` values only: + +| Value | Meaning | Enforcement | +|---|---|---| +| `platform` | Always resolved by platform (tenantId, workspace, timestamps). Reject if user provides. | Contract validation rejects user-supplied values | +| `never-user` | Must not originate from user input under any circumstances. | Hard reject; audit-logged if attempted | + +All other resolution hints (graph picker, chain, form) live in `Worker.inputBindings[]` — not in Contract. + +--- + +## 4. Worker + +**Worker = registry definition.** WorkerRun (§5) = execution instance. + +**Design rule — when to extend Worker:** +> A registry entity extends Worker (via GTS chaining) *if and only if* it autonomously +> produces a WorkerRun upon execution. Entities that are configuration read by Workers +> remain separate registry entities. +> +> - `Validator` → extends Worker ✅ (produces WorkerRun) +> - `Flow` → extends Worker ✅ (produces FlowRun which extends WorkerRun) +> - `Connector` → separate entity ✅ (execution delegated to platform Workers) +> - `StatePolicy`, `Kit`, `Policy` → separate entities ✅ (no execution) + +A Worker is a typed, reusable capability registered in the Studio registry. It defines +what it consumes and produces (Contract), how it runs (WorkerImplementation), and what +it is allowed to call (dependencies). Workers do not execute themselves — execution +creates a WorkerRun. + +**Categorization:** Workers have no `kind` field. Structural subtypes (Validator, Flow) +are expressed through GTS chaining. Behavioral policy is carried by two fields: + +- `requiresAutomationGate` — `true` when execution requires `automationLevel >= + approved_automation`. Replaces the old `kind == action` check. +- `metadata.category` — semantic label for UI grouping and `approvedWorkerCategories` + matching: `quality | security | ops | ai-cost | traceability | retrieval | platform`. + +**"Action" is a UI concept,** not a type. A Worker appears as a clickable "Action" +button in Studio UI when `requiresAutomationGate = true` and the user has permission. +This is declared in `metadata.action`: + +``` +Worker { + id: GTS Type Identifier (gts.cf.studio.core.worker.v1~...) + input: Contract (GTS Type Schema) + output: Contract (GTS Type Schema) + dependencies: [ // static list — security boundary + { + workerId: ref → Worker + required: boolean // default: true; false = optional call + // enforced for runtime: script|hybrid (DAG execution) + // advisory only for runtime: llm (LLM decides dynamically) + } + ] + // mode (sync|async) per dependency → WorkerImplementation.dependencyModes + // Kit Registry validates DAG acyclicity at install — circular deps = hard block + // Runtime backstop: WorkerRun.effectiveLimits.depth caps transitive call depth + scope: local | project | workspace | published + implementationId: ref → WorkerImplementation + requiresAutomationGate: boolean // default: false + // true = Gate 1 applies (automationLevel check) + canInvokeOnDemand: boolean // default: true + // false = only schedule/event can activate + eventTrigger?: { // capability: which event activates this Worker + pattern: GTS Type Identifier + debounce: duration // default: 0 + } + // schedule → WorkerImplementation.defaultSchedule (deployment config, Tenant-overridable) + inputBindings?: [ // runtime input resolution hints (per field) + { + field: string // matches a property name in input Contract + source: graph | user | chain | platform | default + query?: object // filter for source: graph (e.g. { state: "approved" }) + fromStep?: string // for source: chain — which Flow step's output + default?: any // fallback value when source unavailable + } + ] + // Flow.config.steps[].inputBinding overrides Worker.inputBindings per step + deprecation?: { // set on MAJOR contract change + successorId: ref → Worker // new Worker replacing this one + deprecatedAt: datetime + gracePeriodEndsAt: datetime // after this date platform warns on new WorkerRun creation + } + // deprecated Workers remain in Registry; old WorkerRuns and Evidence are valid forever + fallbackWorkerId?: ref → Worker // output Contract must be compatible with primary + // Kit Registry validates at install: fallback output + // must be GTS subtype or exact match of primary output + // incompatible fallback → Kit install warning (not block) + fallbackCondition?: on_error | on_budget_exceeded | on_timeout + interactionModel?: { + canRequestInput: boolean // can emit input_request WorkerInteraction + canPresentMenu: boolean // can emit menu WorkerInteraction + maxPendingInteractions: int // default: 1 + cancellable: boolean // default: true + } + metadata: { + displayName: string + description: string + category: quality | security | ops | ai-cost | traceability | retrieval | platform + icon?: string + profile: realtime | scheduled | on_demand + action?: { + label: string // UI button label, e.g. "Fix Bug", "Create Design" + icon?: string + } + } +} +``` + +### D4 — Worker & Contract + +```mermaid +classDiagram + class Worker { + id: GTS Type ID + scope: local|project|workspace|published + implementationId: ref WorkerImpl + } + class WorkerImplementation { + version: semver + runtime: llm|script|hybrid + auditMode: sync|async + } + class Contract { + GTS Type Schema + x-gts-state-requires? + x-gts-state-sets? + } + class WorkerRun { + state: pending|running|done|failed + parentRunId: ref WorkerRun? + } + + Worker "1" --> "1" WorkerImplementation : implementationId + Worker "1" --> "1" Contract : input + Worker "1" --> "1" Contract : output + Worker "many" --> "many" Worker : dependencies + Worker ..> WorkerRun : execution produces +``` + +### 4.1 WorkerImplementation + +Runtime configuration, versioned independently from the contract. + +``` +WorkerImplementation { + id: string + version: semver + runtime: llm | script | hybrid + config: { + // llm: { model: GTS Model ID, prompt, temperature, ... + // modelRouterId?: ref → ModelRouter // dynamic model selection + // } + // script: { entrypoint, language, ... } + // hybrid: { steps[] } + } + dependencyModes?: map + // per-dependency call mode; default: sync + // overrides Worker.dependencies default without changing Worker schema + checkpoint: { + enabled: boolean + ttl: duration + } + auditMode: sync | async // default: async + retentionPolicy: { + inputTTL: duration + outputTTL: duration + metadataTTL: duration + retentionAction: archive | delete // default: archive + } + defaultSchedule?: cron string // Kit-declared default schedule + // Tenant can override at Kit install time + parallelOutputMerge?: last | append | merge_by_key | custom + // default: last; applies when DAG branches run in parallel + retrieval?: { // only for Workers with metadata.category: retrieval + indexKind: object_graph | document_index | code_index + scope: workspace | tenant // tenant-isolation boundary + indexRef?: string // Gears Models index ID + strategy: dense | sparse | hybrid // vector / BM25 / combined + topK: int // default: 5 + } + pausePoints?: [ + { + afterStep: string // step name within hybrid Worker + prompt: string // shown to user at pause + requiresRole: RolePattern? + timeoutAction: continue | abort + } + ] // creates WorkerRun.state: paused (not Approval) +} +``` + +### 4.2 ModelRouter + +Registry entity for dynamic model selection at WorkerRun creation time. + +``` +ModelRouter { + id: string + defaultModelId: GTS Type ID // Gears Models Registry ref; used when no rule matches + rules: [ + { + condition: { + tenantTier?: string // e.g. enterprise | pro | free + inputTokens?: { gt?: int, lt?: int } + category?: string // Worker metadata.category + } + modelId: GTS Type ID + priority: int // higher value = evaluated first + } + ] +} +``` + +**Model selection priority (highest to lowest):** +``` +1. Tenant.modelOverrides[workerId] ← enterprise custom model +2. ModelRouter.rules[] (first match) ← dynamic routing +3. WorkerImplementation.config.llm.model ← Kit default +``` + +### 4.3 PromptExperiment + +A/B test between two `WorkerImplementation` versions on live traffic. + +``` +PromptExperiment extends Object { + typeId: gts.cf.studio.core.object.v1~cf.studio.core.prompt_experiment.v1~ + workerId: ref → Worker + variants: [ + { + implementationId: ref → WorkerImplementation + trafficWeight: int // relative weight e.g. [70, 30]; must sum > 0 + } + ] + state: running | paused | concluded + startedAt: datetime + concludedAt?: datetime + winnerImplementationId?: ref → WorkerImplementation + minRunsPerVariant?: int // default: 100; platform waits before suggesting winner + significanceThreshold?: float // default: 0.1 (10% difference in avgCostUSD or quality) + metrics?: [ // one entry per variant, same order as variants[] + { + totalRuns: int + avgCostUSD: float + avgInputTokens: int + avgOutputTokens: int + } + ] +} +``` + +Worker link (platform routes to variant when experiment is running): + +``` +Worker { + ... + activeExperimentId?: ref → PromptExperiment +} +``` + +### 4.4 Composability + +A Worker may call other Workers from its `dependencies` list. +An LLM-Worker may call them in any order, conditionally, iteratively — +but **only from the declared list**. Calls outside the list are forbidden. + +The system automatically builds a **DAG** from dependencies and executes +independent branches in parallel. + +--- + +## 5. WorkerRun + +A record of a specific Worker execution. **Extends Object.** + +``` +WorkerRun extends Object { + typeId: gts.cf.studio.core.object.v1~cf.studio.core.worker_run.v1~ + workerId: ref → Worker + parentRunId: ref → WorkerRun? + inputData: any + outputData: any + state: pending | running | awaiting_input | paused | done | failed + progress: { + message: string? + percent: 0..100? + eta: datetime? // strictly optional + } + effectiveLimits: { + timeout: duration + depth: int + token_budget: int + source: kit | tenant | call + } + externalEvents: [ + { + source: string // e.g. "connector:jira", "retriever:document_retriever" + type: string + externalId: string + url: string + chunkRef?: string // Gears Models chunk ID when source is a Retriever Worker + score?: float // similarity score for retrieval events + } + ] + checkpointExpiresAt: datetime? + interactions: WorkerInteraction[] // history of all interactions (immutable once answered) + cancelledBy?: ref → User + cancelCascade?: boolean // were child WorkerRuns also cancelled + costAttributedTo?: { // platform sets at creation from trigger context + userId?: ref → User + workspaceId?: ref → Workspace + parentFlowRunId?: ref → WorkerRun // enables per-Flow cost aggregation + // (FlowRun extends WorkerRun; use WorkerRun ref) + } + trigger: { // immutable after set; platform sets at creation + kind: scheduled | onEvent | onDemand + // scheduled: Gears Jobs Manager created this run from Worker.defaultSchedule + // onEvent: Worker.eventTrigger pattern matched a Gears Events Broker event + // onDemand: user action (Action button, API call, Flow step) + // sub-Worker calls: detected via parentRunId != null (no separate kind needed) + parentEventId?: string // Gears Event ID (for kind: onEvent) + scheduleName?: string // Gears Jobs Manager schedule name (for kind: scheduled) + } + cost?: { + promptTokens: int + completionTokens: int + modelId: string // GTS Type ID from Gears Models Registry + estimatedCostUSD: float + } // only populated for runtime: llm | hybrid + staticChildren: WorkerRun[] +} +``` + +### 5.1 WorkerRun Lifecycle (Write-Ahead) + +``` +1. START → WorkerRun created, state: pending +2. WRITE-AHEAD → externalEvents recorded (before any reads) +3. EXECUTE → Worker runs (DAG, parallel branches) +4. COMPLETE → outputData written, state: done | failed +``` + +### D5 — WorkerRun Execution Lifecycle + +```mermaid +flowchart TD + START([START]) --> WA[Write-Ahead\nexternalEvents recorded] + WA --> EXEC[Execute\nDAG parallel branches] + EXEC --> DONE([done]) + EXEC --> FAILED([failed]) + + FAILED --> CHK{checkpoint\nenabled?} + CHK -->|yes + TTL valid| RETRY[Checkpoint-based\nRetry] + CHK -->|no / TTL expired| FULL[Full Restart] + RETRY --> EXEC + FULL --> WA + + EXEC --> LIMITS["effectiveLimits applied\nkit → tenant → call"] +``` + +### 5.2 Retry + +- **Checkpoint-based** (`checkpoint.enabled = true`): successful sub-Workers + not re-executed; results reused until `checkpointTTL` expires. +- **Full restart** (`checkpoint.enabled = false` or TTL expired). +- Every WorkerRun is **idempotent** by `id`. + +### 5.3 Limits (three levels, each can only narrow) + +``` +Kit defaults: timeout, depth, token_budget +Tenant max limits: ← ceiling +Call (at invocation): ← can narrow, not exceed Tenant +``` + +### D18 — WorkerRun Cross-References + +```mermaid +classDiagram + class WorkerRun { + workerId: ref Worker + parentRunId: ref WorkerRun? + state: pending|running|done|failed + } + class Worker { + id: GTS Type ID + } + class Object { + id: GTS Instance ID + } + class FlowRun { + flowId: ref Flow + } + + WorkerRun --> Worker : workerId + WorkerRun --> WorkerRun : parentRunId (sub-call tree) + WorkerRun --> Object : inputData references + WorkerRun --> Object : outputData produces + FlowRun --> WorkerRun : completedSteps +``` + +--- + +## 6. Flow + +**Flow = Worker extension (via GTS chaining).** A Flow is not a separate registry +entity — it extends Worker through GTS chaining. Flows have `runtime: orchestrator` +(declarative constraint config, no LLM/script code) and sequence mandatory steps. +`requiresAutomationGate` on a Flow depends on whether its mandatory steps require it. + +``` +// GTS type: gts.cf.studio.core.worker.v1~cf.studio.core.flow.v1~ + +Flow extends Worker { + // no kind field — structural identity expressed through GTS type + input: Contract[] // entryConstraints + output: Contract // { completedSteps, skipped } + implementationId: WorkerImplementation { + runtime: orchestrator + config: { + steps: [ + { + workerId: ref → Worker + required: boolean // default: true; false = optional step + // mandatorySteps = steps.filter(required == true) + inputBinding?: { // overrides Worker.inputBindings for this step + // field → { source, query?, fromStep?, default? } + // e.g. "prd": { source: "chain", fromStep: "step-0" } + } + } + ] + // mandatorySteps: Worker[] — deprecated; derived from steps.filter(required == true) + stepDependencies?: map + // explicit deps for UI dependency graph; + // if absent: steps assumed sequential per steps[] order + allowedNextSteps: map + conditionalRoutes?: [ + { + fromWorker: ref → Worker + condition: string // JSONPath expression over outputData + // Phase 1-2: JSONPath; Phase 3+: CEL considered + nextWorker: ref → Worker + } + ] // evaluated after allowedNextSteps; wins on match + } + } + scope: local | project | workspace | published + // Not applicable to orchestrators: fallbackWorkerId, interactionModel +} +``` + +### 6.1 FlowRun + +FlowRun extends WorkerRun — the execution record of an orchestrator Worker. + +``` +FlowRun extends WorkerRun { + // inherits all WorkerRun fields + typeId: gts.cf.studio.core.object.v1~cf.studio.core.flow_run.v1~ + // orchestrator step tracking: + completedSteps: Worker[] + skippedSteps: Worker[] + activeStepId?: ref → Worker // currently executing step; null when idle + stepStatus?: map + // updated by platform on each child WorkerRun state change + // source of truth: child WorkerRun tree + // note: outputData = { completedSteps, skipped } (FlowRunResult, not a domain Object) +} +``` + +--- + +## 7. Tenant + +Recursive hierarchy. Extends Gears Resource Group tenant type. + +``` +Tenant { + typeId: gts.cf.core.rg.type.v1~cf.core._.tenant.v1~cf.studio.core.tenant.v1~ + parentId: ref → Tenant? + name: string + checkpointTTL: duration // default: 24h + modelOverrides?: map + // Enterprise: override model per Worker + // priority: Tenant override > ModelRouter > WorkerImpl default + allowedKitPatterns?: [ + saas_multitenant | service_provider | enterprise_private | hybrid_cloud | on_prem | any + ] // soft governance: Kit with incompatible deploymentPattern + // requires Approval (kind: architecture_decision) to install + mcpSettings?: { + enabled: boolean // default: false; MCP access disabled unless explicitly enabled + allowedKits?: string[] // null = all installed Kits with mcpTools; whitelist otherwise + mcpRole: ref → Role // MCP clients authenticate with permissions of this Role only + // Role survives DataErasureRequest; avoids full User identity + } + aiCostBudget?: { + monthly_usd: float // monthly AI spending cap + alert_threshold_pct: float // default: 0.8; Recommendation(severity: warning) at threshold + // on limit reached: new WorkerRun creation blocked for runtime: llm | hybrid + } + worldModelParticipation: opted_in | opted_out | not_configured + // opted_in: BenchmarkSamples may be used (anonymized) for cross-tenant World Model training + // opted_out: strictly private; BenchmarkSamples used only for this Tenant's models + // not_configured (default): org-private training only; no cross-tenant sharing +} +``` + +### BenchmarkSample + +``` +BenchmarkSample extends Object { + typeId: gts.cf.studio.core.object.v1~cf.studio.core.benchmark_sample.v1~ + workerRunId: ref → WorkerRun // the run whose output is the approved example + workerId: ref → Worker + approvedBy: ref → User // human who verified this as a high-quality example + approvedAt: datetime + qualityScore?: float // 0.0–1.0; optional human quality rating + includeInTraining: boolean // consent to use for Worker fine-tuning + // Platform feeds approved BenchmarkSamples to Gears Model Runtime Controller + // for fine-tuning WorkerImplementation.config.llm.model per Tenant +} +``` + +### World Model flywheel + +``` +WorkerRun (output) → human review → BenchmarkSample (if quality approved) + → Gears Model Runtime Controller (fine-tuning job) + → new model version in Gears Models Registry + → Tenant.modelOverrides[workerId] = fine-tuned model + → next WorkerRun uses org-adapted model +``` +``` + +Every Object belongs to exactly one Tenant (`tenantId`). +Isolation enforced via ABAC policies using GTS wildcard patterns. + +### D3 — Tenant Hierarchy & Isolation + +```mermaid +classDiagram + class Tenant["Tenant\n(extends Gears RG, NOT Studio Object)"] { + parentId: ref Tenant? + name: string + checkpointTTL: duration + } + class Object { + tenantId: ref Tenant + } + class PolicyDelegation { + fromTenant: ref Tenant + toTenant: ref Tenant + expiresAt: datetime? + } + class PolicyOverride { + policyId: ref Policy + tenantId: ref Tenant + } + class IdentityMapping { + externalPattern: object + roleId: ref Role + } + + Tenant "1" --> "0..1" Tenant : parentId (sub-tenant) + Tenant "1" --> "many" Object : owns + Tenant "1" --> "many" PolicyDelegation : fromTenant + Tenant "1" --> "many" PolicyOverride : scoped to + Tenant "1" --> "many" IdentityMapping : scoped to +``` + +--- + +## 8. User + +Extends Gears Account Management user type. + +``` +User { + typeId: gts.cf.core.am.user.v1~cf.studio.core.user.v1~ + // inherits: id, email, display_name from Gears AM + tenantId: ref → Tenant +} +``` + +--- + +## 9. Workspace + +Multi-repo configuration. **Extends Object.** + +**Shared artifact pattern:** Objects created with `workspaceId = null` are Tenant-level — +implicitly shared across all workspaces in the Tenant. Use this for platform-wide artifacts: +PRDs, ADRs, architecture guidelines, shared design templates. Any workspace member can +create `links[]` to Tenant-level Objects without cross-workspace permission issues. + +``` +Workspace extends Object { + typeId: gts.cf.studio.core.object.v1~cf.studio.core.workspace.v1~ + name: string + sources: [ + { + repositoryId?: ref → repository // link to synced repo Object (Connector active) + path?: string // local filesystem path (CLI / local context) + url?: string // remote URL — fallback when repo not yet synced + branch?: string // branch override; default: repository.defaultBranch + role: main | docs | platform | shared | test | config + adapter?: string // hint: git | github | gitlab | local + // constraint: at least one of repositoryId, path, or url required + } + ] +} +``` + +When a Connector (GitHub/GitLab) syncs a repository, the platform resolves +`repositoryId` automatically by matching `url`. Before Connector setup, `path` +or `url` alone is sufficient (CLI-only or unsynced workspace). + +### D27 — Workspace & Kit Cross-References + +```mermaid +classDiagram + class Workspace { + name: string + tenantId: ref Tenant + sources: SourceEntry[] + } + class SourceEntry { + repositoryId: ref repository? + path: string? + url: string? + branch: string? + role: main|docs|platform|shared|test|config + adapter: string? + } + class repository { + url: string + defaultBranch: string + } + class Kit { + scope: local|project|workspace|published + requiredPermissions: Permission[] + } + class Tenant { + parentId: ref Tenant? + } + + Workspace "1" --> "many" SourceEntry : sources + SourceEntry "0..1" --> "0..1" repository : repositoryId (auto-resolved by Connector) + Tenant "1" --> "many" Kit : installed Kits + Workspace --> Tenant : tenantId +``` + +--- + +## 10. Extensibility (Kit) + +### 10.1 Kit — the only extension unit + +A Kit packages: new Object types, Workers of all kinds (including orchestrators / Flows), +obj_ext definitions. + +``` +Kit scopes: + local ← developer's machine + project ← project repository + workspace ← workspace configuration + published ← marketplace / Registry +``` + +### 10.2 Two type extension mechanisms + +**Narrowing** (new semantic type) → GTS derived type via chaining: +``` +gts.cf.studio.core.object.v1~cf.studio.core.task.v1~jira.studio.core.jira_task.v1~ +``` + +**Attribute extension** → `obj_ext` registry entity: +``` +obj_ext { + // GTS ID: gts.cf.studio.core.obj_ext.v1~jira.studio.core.jira_task_ext.v1~ + x-gts-traits: { + extends: [ "gts.cf.studio.core.object.v1~cf.studio.core.task.v1~" ] + } + properties: GTS Type Schema +} +``` + +### D15 — Kit Extensibility (GTS Chaining) + +```mermaid +flowchart TD + B1["gts.cf.studio.core.object.v1~\n(Studio base)"] + B2["cf.studio.core.task.v1~\n(Studio canonical)"] + B3["jira.studio.core.jira_issue.v1~\n(Jira Kit)"] + B4["cf.studio.core.pull_request.v1~\n(Studio canonical)"] + B5["github.studio.core.github_pr.v1~\n(GitHub Kit)"] + + B1 -->|narrows to| B2 + B2 -->|narrows to| B3 + B1 -->|narrows to| B4 + B4 -->|narrows to| B5 + + OE["obj_ext\n(attribute extension)\nno new type ID needed"] -.->|extends attrs of| B2 +``` + +### 10.3 Compatibility + +- Vendor declares `compatibleWith` in Kit manifest +- Registry verifies via GTS compatibility rules at installation +- Smoke tests not run (too costly for LLM Workers) + +### 10.3a Kit Semver Convention + +| Semver | Change type | Examples | +|---|---|---| +| PATCH | WorkerImplementation only (same Contract) | prompt tweak, model upgrade | +| MINOR | Additive — new optional fields, new Workers, new Flows | new Worker added | +| MAJOR | Breaking — required Contract fields changed, Worker removed, FieldMapping changed | new required input field | + +`changelog` in `Kit.metadata` is **required** for MAJOR version bumps. +Kit Registry rejects MAJOR publish without a non-empty changelog. + +### 10.3b KitInstallation + +Tenant→Kit relationship is tracked as a first-class Object: + +``` +KitInstallation extends Object { + typeId: gts.cf.studio.core.object.v1~cf.studio.core.kit_installation.v1~ + kitId: string // Kit registry ID + kitVersion: semver // currently installed version + tenantId: ref → Tenant + installedAt: datetime + installedBy: ref → User + updatePolicy: auto | notify | manual // default: notify + // auto = PATCH only (non-breaking) + // notify = MINOR + PATCH + // MAJOR always requires explicit Approval regardless of policy + state: active | update_available | rolling_back | failed + availableVersion?: semver // set when update is detected + rollbackVersion?: semver // previous version (for rollback) +} +``` + +Update flow for breaking changes: +1. Registry detects MAJOR update → `KitInstallation.state: update_available` +2. Tenant admin notified (NotificationRule) +3. Admin reviews `Kit.metadata.changelog` +4. Approval (kind: architecture_decision) required for MAJOR update +5. On approval: `rollbackVersion` saved → Kit updated +6. On failure: rollback to `rollbackVersion` (also requires Approval) + +### 10.4 Permissions + +``` +Kit manifest: + requiredPermissions: + - read: [ GTS Type Identifier, ... ] + - write: [ GTS Type Identifier, ... ] + - call: [ GTS Type Identifier, ... ] + requiredSettings: + - { key: string, secret: boolean } // secrets stored in Gears Credentials Store +``` + +- Tenant explicitly approves at installation +- Expanding permissions in new version → blocks auto-update, requires re-approval +- Reducing permissions → auto-update + +### 10.5 Kit Discovery Metadata + +Optional metadata for Kit marketplace discovery and governance filtering. + +``` +Kit manifest: + metadata: + displayName: string + description: string + version: semver + referenceArchitecture?: { + name: string // e.g. "Artifact-first SDLC", "Multi-tenant SaaS Platform" + description: string + url?: string // link to architecture documentation + } + deploymentPatterns?: [ + saas_multitenant | service_provider | enterprise_private + | hybrid_cloud | on_prem | any + ] // default: [any] if omitted + tags?: string[] // free-form discovery tags + targetTeamSize?: { min?: int, max?: int } + changelog?: string // REQUIRED for MAJOR version bumps; Kit Registry rejects without it + mcpTools?: [ // opt-in MCP tool declarations (not auto-exposed) + { + workerId: ref → Worker + toolName: string // MCP tool name, e.g. "studio_create_design" + description?: string // overrides Worker.metadata.llmDescription + exposed: boolean // default: true + } + ] +``` + +`Tenant.allowedKitPatterns` (see §7) acts as a soft governance filter: installing +a Kit whose `deploymentPatterns` do not intersect `allowedKitPatterns` requires +an explicit Approval (kind: architecture_decision) — same gate as raising automationLevel. + +--- + +## 11. System Overview + +See D1 and DO1–DO6 in the Overview section above for high-level diagrams. + +### D31 — Full Object Reference Map (top-level) + +```mermaid +flowchart TD + subgraph Requirements + REQ["requirement"] --> TASK["task"] + end + subgraph Code + TASK --> PR["pull_request"] + PR --> CMT["commit"] + CMT --> REPO["repository"] + end + subgraph CICD + CMT --> BUILD["build"] + BUILD --> ART["build_artifact"] + ART --> DEP["deployment"] + end + subgraph Ops + DEP --> INC["incident"] + INC --> PM["postmortem"] + PM --> TASK + end +``` + +--- + +## 12. Object Lifecycle & State Transitions + +### 12.1 StatePolicy + +Registry entity — separates process (transitions) from data (type schema). + +``` +StatePolicy { + appliesTo: GTS Type Identifier + scope: tenant | kit | global + transitions: { + "": [ + { + from: value + to: value + requiresApproval?: { + role: RolePattern + escalateAfter?: duration + escalateTo?: RolePattern | "reject" + } + } + ] + } +} +``` + +### D6 — StatePolicy & Transitions + +```mermaid +flowchart LR + SP["StatePolicy\n(registry entity)"] -->|appliesTo| OT["Object Type\n(GTS ID)"] + SP -->|declares| TR["Transition\nfrom → to"] + TR -->|optional| RA["requiresApproval\n{role, escalateAfter,\nescalateTo}"] + + WC["Worker Contract"] -->|x-gts-state-requires| REQ["Required State\n(soft/strict)"] + WC -->|x-gts-state-sets| SET["Resulting State"] + + REQ -->|gates| WD["Worker Discovery\n= type match\n+ state match"] +``` + +Tenant StatePolicy overrides Kit StatePolicy (tenant > kit > global). + +### 12.2 Worker Contract — State Awareness + +```json +// input Contract +"task": { + "$ref": "gts://cf.studio.core.object.v1~cf.studio.core.task.v1~", + "x-gts-state-requires": { + "state": "in_progress", + "strict": false // default: warning + override; true = hard block + } +} + +// output Contract +"task": { + "$ref": "gts://cf.studio.core.object.v1~cf.studio.core.task.v1~", + "x-gts-state-sets": { "state": "review" } +} +``` + +**Worker Discovery** = GTS type match + state match. Contracts are always +vendor-agnostic — external states are mapped to Studio states at Kit +installation time (per Tenant config). + +### 12.3 State Transition History + +`StateTransitionEvent` is a **computed projection** over the WorkerRun tree. + +``` +StateTransitionEvent (projection) { + objectId: from WorkerRun input/output diff + property: derived + fromValue: WorkerRun.inputData[property] + toValue: WorkerRun.outputData[property] + workerRunId: WorkerRun.id + timestamp: WorkerRun.timestamp + evidence?: WorkerRun.outputData[evidence] +} +``` + +--- + +## 13. Role, Policy & Authorization + +### D7 — Authorization Model + +```mermaid +classDiagram + class Policy { + id: GTS Type ID + version: semver + rules: Rule[] + } + class PolicyOverride { + policyId: ref Policy + overrides: Rule[] + } + class Role { + name: string + tenantId: ref Tenant + } + class User { + tenantId: ref Tenant + } + class Kit { + requiredPermissions: Permission[] + } + + User --> Role : has + Role --> Policy : governs via + Policy <|-- PolicyOverride : overrides + Kit --> Policy : Worker authz via requiredPermissions +``` + +### 13.1 Role + +``` +Role extends Object { + typeId: gts.cf.studio.core.object.v1~cf.studio.core.role.v1~ + name: string + tenantId: ref → Tenant +} +``` + +### 13.2 Permission + +Extends Gears authz permission base type. + +``` +Permission { + typeId: gts.cf.toolkit.authz.permission.v1~cf.studio.core.permission.v1~ + resource_type: GTS Type Identifier (wildcard ok) + action: string + display_name: string +} +``` + +### 13.3 Policy & PolicyOverride + +**`Policy`** — registry entity (Kit, versioned as code). +**`PolicyOverride`** — Object in graph (Tenant runtime corrections). +Priority: `PolicyOverride > Policy` (Override cannot expand beyond Policy). + +``` +Policy (registry) { + id: GTS Type Identifier + version: semver + rules: [ + { + principal: Role pattern + action: "run" | "read" | "write" | "delete" + target: GTS Type Identifier (wildcard ok) + condition?: ref → Worker // { principal, object, action } → { allowed, reason } + // pre-built: is_assigned_to_principal_worker, + // is_workspace_member_worker, is_object_owner_worker + conditionCache: { ttl: duration } // default: 60s + // Phase 3 TODO: allowedFields?: string[] — field-level restriction (not yet implemented) + } + ] +} + +PolicyOverride extends Object { + typeId: gts.cf.studio.core.object.v1~cf.studio.core.policy_override.v1~ + policyId: ref → Policy + tenantId: ref → Tenant + overrides: Policy.rules[] // can only narrow +} +``` + +### 13.4 Authorization Model + +| Subject | Mechanism | +|---|---| +| **User** | `Role` + `Policy` / `PolicyOverride` | +| **Worker** | `Kit.requiredPermissions` (approved at Kit installation) | + +Worker→Worker: implicit via `dependencies` — both Kits approved by Tenant → call authorized. + +### 13.5 IdentityMapping + +``` +IdentityMapping extends Object { + typeId: gts.cf.studio.core.object.v1~cf.studio.core.identity_mapping.v1~ + externalPattern: { + provider: GTS Type Identifier // from SSO Kit, GitHub Kit, etc. + pattern: string + } + roleId: ref → Role + tenantId: ref → Tenant + active: boolean +} +``` + +### D28 — Role & Identity Cross-References + +```mermaid +classDiagram + class User { + tenantId: ref Tenant + } + class Role { + tenantId: ref Tenant + name: string + } + class RoleAssignment { + userId: ref User + roleId: ref Role + assignedBy: ref User + } + class IdentityMapping { + externalPattern: object + roleId: ref Role + tenantId: ref Tenant + } + class PolicyOverride { + policyId: ref Policy + tenantId: ref Tenant + } + + User "many" --> "many" Role : via RoleAssignment + IdentityMapping --> Role : maps external identity to + Role --> PolicyOverride : governed by + Tenant --> IdentityMapping : scoped to +``` + +### 13.6 Tenant Policy Hierarchy + +Sub-Tenant inherits parent Policy. Default: **narrowing only**. + +`PolicyDelegation` — parent explicitly grants specific rights downward: + +``` +PolicyDelegation extends Object { + typeId: gts.cf.studio.core.object.v1~cf.studio.core.policy_delegation.v1~ + fromTenant: ref → Tenant + toTenant: ref → Tenant + permissions: [ { action: string, target: GTS Type Identifier } ] + expiresAt: datetime? +} +``` + +--- + +## 14. AuditLog + +### 14.1 Storage Model + +Materialized view over WorkerRun tree (CQRS + Event Sourcing). +Source of truth: WorkerRun tree. + +Critical events: `auditMode: sync`. Others: `auditMode: async` (default). +Tenant can override per Worker via PolicyOverride. + +Materialized view: `WorkerRun tree → AuditLog`. + +### D8 — AuditLog & History + +```mermaid +flowchart TD + WR["WorkerRun\n(source of truth)"] -->|async materialization| AL["AuditLog\n(materialized view)"] + WR -->|write-ahead| EV["externalEvents\n{source, type, externalId, url}"] + + AL -->|query| API["Query API\n{target GTS pattern,\naction, principal, timeRange}"] + API -->|filtered by| POL["Policy check\n(Role boundary)"] + + KV["Kit View\n(named query)"] -->|named query over| API + SAQ["SavedAuditQuery\nextends Object"] -->|user query over| API +``` + +### 14.2 Query API & Views + +``` +auditLog.query({ + target: GTS pattern, + action?: string, + principal?: string, + timeRange?: { from, to } +}) +``` + +| View Type | Source | Creator | +|---|---|---| +| Kit View | Named queries in Kit | Vendor | +| User View | `SavedAuditQuery extends Object` | User via UI | + +``` +SavedAuditQuery extends Object { + typeId: gts.cf.studio.core.object.v1~cf.studio.core.saved_audit_query.v1~ + name: string + query: { target, action?, principal?, timeRange? } + tenantId: ref → Tenant + createdBy: ref → User +} +``` + +### D29 — AuditLog & SavedQuery Cross-References + +```mermaid +classDiagram + class WorkerRun { + workerId: ref Worker + inputData: any + outputData: any + externalEvents: ExternalEvent[] + } + class ExternalEvent { + source: string + externalId: string + url: string + } + class SavedAuditQuery { + createdBy: ref User + tenantId: ref Tenant + query: QuerySpec + } + class AuditLog { + materialized view + over WorkerRun tree + } + + WorkerRun "1" --> "many" ExternalEvent : write-ahead + WorkerRun ..> AuditLog : materializes into + SavedAuditQuery ..> AuditLog : queries +``` + +### 14.3 Retention + +Declared per Worker in Kit. Tenant can override globally. +Default `retentionAction: archive` (cold storage). Hard delete only when +explicitly configured or required by compliance. + +### 14.4 Export + +Core `audit_exporter` Worker pre-installed in every Tenant (webhook, JSON). +Vendor-specific formats (Splunk, Datadog, Elastic) via Kits. + +--- + +## 15. Recommendation + +### 15.1 Recommendation Object + +``` +Recommendation extends Object { + typeId: gts.cf.studio.core.object.v1~cf.studio.core.recommendation.v1~ + state: pending | accepted | executing | done | dismissed | invalidated + sourceRunId: ref → WorkerRun + suggestedWorker: ref → Worker + suggestedInput: Contract data // refreshed on Re-check + reason: string + severity: info | warning | critical + severityWorker?: ref → Worker // dynamic severity recompute + confidence: full | partial | low // partial = external systems unavailable + validationWorker?: ref → Worker // auto/manual invalidation +} +``` + +### D9 — Recommendation Lifecycle + +```mermaid +flowchart TD + AW["Analyzer Worker\n(defaultSchedule/eventTrigger)"] -->|creates| REC["Recommendation\nextends Object"] + + REC -->|state| S1[pending] + S1 -->|user accepts| S2[accepted] + S2 -->|Worker runs| S3[executing] + S3 --> S4[done] + S1 -->|user dismisses| S5[dismissed] + S1 -->|Re-check / auto| S6[invalidated] + + REC -->|validationWorker| VW["Validation Worker\n(re-check + refresh input)"] + REC -->|suggestedWorker| SW["Suggested Worker\n(actionable fix)"] +``` + +### 15.2 Analyzer Workers + +Detect gaps and create Recommendations. Use `eventTrigger` (capability binding) +and `WorkerImplementation.defaultSchedule` (deployment default). `canInvokeOnDemand: true`. + +Read external systems via `dependencies` (standard composability). +On external system unavailability → `confidence: partial` instead of failure. + +### 15.3 Re-check & Accepting + +**Re-check** (manual or automatic via `validationWorker`): +- Checks if gap still exists +- Refreshes `suggestedInput` to current Object state +- Recomputes `severity` if `severityWorker` set + +**Accepting**: +``` +User accepts → Re-check runs → diff shown if inputs changed + → user confirms → suggestedWorker launched → state: executing → done +``` + +### D26 — Recommendation Cross-References + +```mermaid +classDiagram + class Recommendation { + sourceRunId: ref WorkerRun + suggestedWorker: ref Worker + validationWorker: ref Worker? + severityWorker: ref Worker? + confidence: full|partial|low + } + class WorkerRun { + workerId: ref Worker + } + class Worker { + id: GTS Type ID + } + class Object { + id: GTS Instance ID + } + + Recommendation --> WorkerRun : sourceRunId (Analyzer that found gap) + Recommendation --> Worker : suggestedWorker (actionable fix) + Recommendation --> Worker : validationWorker (re-check) + WorkerRun --> Object : gap detected in (input/output) + Worker --> Object : fix will produce (output Contract) +``` + +--- + +## 16. Events + +Studio is built on **Constructor Fabric Gears**. Event infrastructure +(bus, routing, delivery, backpressure, authz filtering) — Gears Events Broker. +Studio defines event types via GTS. + +### D10 — Events & Notifications + +```mermaid +flowchart LR + OBJ["Object change"] -->|emits| EB["Gears Events Broker\n(GTS-typed events)"] + EB -->|authz filtered| NR["NotificationRule\n(registry, from Kit)"] + NR -->|delivers via| NS["Gears Notifications\nService"] + NS -->|channels| CH["in_app / email\nwebhook / Slack..."] + + NSU["NotificationSubscription\nextends Object"] -->|personal filter| EB + NRO["NotificationRuleOverride\nextends Object"] -->|on/off + expiresAt| NR +``` + +### 16.1 Studio Event Types + +Studio event types extend the Gears platform event base type +`gts.cf.core.events.type.v1~` — Studio does **not** define its own base +event type. + +``` +// Object lifecycle +gts.cf.core.events.type.v1~cf.studio.core.object_created.v1~ +gts.cf.core.events.type.v1~cf.studio.core.object_updated.v1~ +gts.cf.core.events.type.v1~cf.studio.core.object_deleted.v1~ + +// State transitions +gts.cf.core.events.type.v1~cf.studio.core.state_changed.v1~ + +// WorkerRun +gts.cf.core.events.type.v1~cf.studio.core.worker_run_started.v1~ +gts.cf.core.events.type.v1~cf.studio.core.worker_run_completed.v1~ +gts.cf.core.events.type.v1~cf.studio.core.worker_run_cancelled.v1~ +gts.cf.core.events.type.v1~cf.studio.core.worker_interaction_created.v1~ +gts.cf.core.events.type.v1~cf.studio.core.worker_interaction_answered.v1~ + +// Recommendations +gts.cf.core.events.type.v1~cf.studio.core.recommendation_created.v1~ +gts.cf.core.events.type.v1~cf.studio.core.recommendation_invalidated.v1~ + +// Kit lifecycle +gts.cf.core.events.type.v1~cf.studio.core.kit_installed.v1~ +gts.cf.core.events.type.v1~cf.studio.core.kit_updated.v1~ + +// EventSubscription delivery +gts.cf.core.events.type.v1~cf.studio.core.event_delivery_failed.v1~ +``` + +Wildcard-based authz example (per Gears GTS guidelines): +``` +gts.cf.core.events.type.v1~cf.studio.core.* ← all Studio events +gts.cf.core.events.type.v1~cf.studio.core.object_* ← only Object lifecycle events +``` + +Gears Events Broker has built-in authz — subscribers receive only events +for Objects they have Policy rights to read. + +--- + +## 17. Notifications + +Studio defines rules; Gears Notifications Service delivers. + +### 17.1 NotificationRule + +Registry entity from Kit. + +``` +NotificationRule (registry) { + id: GTS Type Identifier + trigger: { onEvent: GTS pattern, debounce?: duration } + audience: RolePattern + channel: "in_app" | "email" | "webhook" | GTS Type Identifier (vendor) + template: string // primary Object data + Studio deep link only + digest?: { + window: duration + maxItems: int + groupBy: "objectId" | "eventType" | "none" // default: "none" + } +} +``` + +### 17.2 NotificationRuleOverride + +Runtime on/off without Kit release. + +``` +NotificationRuleOverride extends Object { + typeId: gts.cf.studio.core.object.v1~cf.studio.core.notification_rule_override.v1~ + ruleId: ref → NotificationRule + active: boolean + expiresAt: datetime? +} +``` + +### 17.3 NotificationSubscription + +Personal user subscriptions on top of Kit rules. + +``` +NotificationSubscription extends Object { + typeId: gts.cf.studio.core.object.v1~cf.studio.core.notification_subscription.v1~ + userId: ref → User + tenantId: ref → Tenant + filter: { + eventPattern: GTS pattern + severity?: string[] + objectFilter?: GTS pattern + } + channel: "in_app" | "email" | "webhook" | GTS Type Identifier + urgency: immediate | digest | muted + active: boolean +} +``` + +### D30 — Notification Cross-References + +```mermaid +classDiagram + class NotificationRule { + trigger: EventPattern + audience: RolePattern + channel: string + } + class NotificationRuleOverride { + ruleId: ref NotificationRule + active: boolean + expiresAt: datetime? + } + class NotificationSubscription { + userId: ref User + tenantId: ref Tenant + urgency: immediate|digest|muted + } + class User { + tenantId: ref Tenant + } + + NotificationRuleOverride --> NotificationRule : ruleId + NotificationSubscription --> User : userId + User --> NotificationSubscription : personal subscriptions + NotificationRule --> NotificationRuleOverride : overridden by +``` + +### 17.4 Channels + +**Core (Gears, pre-installed):** `in_app`, `email`, `webhook` + +**Vendor Kits** register additional channels. Kit declares `requiredSettings` +for credentials; Tenant fills via Gears Credentials Store. No secrets in Kit. +// Note: Gears Settings Service = preferences/feature flags (not secrets) + +--- + +## 18. Validator & Validation Loop + +### 18.1 Validator + +Derived from Worker. Adds retry/escalation semantics. + +``` +Validator extends Worker { + // GTS: gts.cf.studio.core.worker.v1~cf.studio.core.validator.v1~ + maxRetries: int // default: 3 (Kit) → Tenant override → call + escalateTo: RolePattern? // who decides on limit reached + abortOnLimit: boolean // default: false + // output Contract always includes ValidationResult +} +``` + +Three-level policy: Kit defaults → Tenant override (narrowing only) → call (narrowing only). + +### 18.2 ValidationSession + +Aggregates the full retry loop for one Validator run on one Object. + +``` +ValidationSession extends Object { + typeId: gts.cf.studio.core.object.v1~cf.studio.core.validation_session.v1~ + validatorId: ref Validator + targetId: ref Object // what is being validated + state: running|pass|fail|escalated|aborted + retryCount: int + maxRetries: int + runs: WorkerRun[] // all attempts + evidenceId: ref Evidence? // final Evidence on pass +} +``` + +### 18.3 ValidationResult + +Output of one Validator WorkerRun. Independent lifecycle. + +``` +ValidationResult extends Object { + typeId: gts.cf.studio.core.object.v1~cf.studio.core.validation_result.v1~ + sessionId: ref ValidationSession + validatorId: ref Validator + targetId: ref Object + workerRunId: ref WorkerRun + state: pass|fail|superseded|revoked + reason: string + evidenceId: ref Evidence? + revokedBy: ref User? + revokedAt: datetime? +} +``` + +### 18.4 Evidence + +Structured proof that an action or validation occurred and is valid. + +``` +Evidence extends Object { + typeId: gts.cf.studio.core.object.v1~cf.studio.core.evidence.v1~ + workerRunId: ref WorkerRun // who produced it + targetId: ref Object // what it proves + kind: validation|approval|execution|review + payload: GTS Type Schema // structured proof data + state: valid|superseded|revoked +} +``` + +Worker output Contract declares `produces: evidence` when it generates Evidence. + +### 18.5 WorkerRun State Machine (updated) + +``` +pending → running → awaiting_input (WorkerInteraction created; waiting for user) + → paused (pausePoint reached; awaiting human resume) + → done + → failed (error, can retry) + → escalated (awaiting Approval from human) + → aborted (limit reached or human rejected) + +awaiting_input → running (WorkerInteraction answered) +awaiting_input → aborted (timeoutAction: abort OR cancel()) +awaiting_input → escalated (timeoutAction: escalate) + +paused → running (human resumes) +paused → aborted (timeoutAction: abort OR cancel()) + +// cancel(workerRunId, cascade: boolean = true) +// → state: aborted, cancelledBy = User +// → active WorkerInteraction.state → cancelled +// → if cascade: child WorkerRuns → aborted +``` + +### 18.6 Escalation Flow + +``` +ValidationSession.retryCount >= maxRetries + → CREATE Approval { + kind: "risk_acceptance" | custom + sessionId: ref ValidationSession + requiredRole: Validator.escalateTo + question: "Validation failed N times. Proceed?" + } + → ValidationSession.state = escalated + → WorkerRun.state = escalated + +Human approves → resume → new WorkerRun +Human rejects → ValidationSession.state = aborted +``` + +### 18.x Gate Modes: Binary vs Score + +Studio gates have two operating modes, selected by the Worker's `profile`: + +**Binary gate** (`profile: validator`) +- Output: `pass | fail` +- Used for: deterministic checks with no ambiguity — CI build, schema validation, lint, test suite, security CVE scan +- On fail: retry the upstream producer Worker (as per §18 retry loop) +- On pass: flow advances to next step +- Evidence: binary ValidationSession result + +**Score gate** (`profile: analyzer, emits: score`) +- Output: `score: float (0.0–1.0)` + `findings: Finding[]` +- Used for: LLM-based review — design conformance, code quality, test coverage adequacy, PRD completeness +- Never "fails" in the binary sense — it always emits a score and findings +- Flow behaviour: if `score_improvement >= convergence_threshold`, loop back to the upstream producer (feed findings as context); if `improvement < threshold` or `maxIterations` reached, advance +- This replaces the separate "LoopPolicy" concept — the gate itself carries convergence config +- Evidence: scored ValidationSession with finding list attached + +**Finding** (emitted by score gate): +``` +Finding { + id: string + severity: 'critical' | 'major' | 'minor' + category: string // e.g. "design_conformance", "test_coverage", "security" + location: string? // file path or object reference + description: string // human-readable finding + suggestedFix: string? // LLM-proposed fix + resolved: boolean // true once upstream producer addressed it +} +``` + +**Key distinction:** +- Binary gate asks: "Is this correct?" → yes/no → CI, schema, lint +- Score gate asks: "How good is this?" → 0.0–1.0 + findings → LLM review, quality assessment + +A flow that ends with a score gate and has the producer Worker before it is an "iterative refinement flow" — no separate "loop" concept needed. The score gate's convergence config (`threshold`, `maxIterations`) controls when the loop terminates. This is exactly the LLM-based agentic loop pattern from Merouani et al. 2025. + +**Example gate configs:** + +```yaml +# Binary gate — deterministic +- workerId: ci_build_validator + profile: validator + mode: binary + maxRetries: 3 + onMaxRetries: escalate + +# Score gate — LLM review, produces findings like CodeRabbit +- workerId: code_quality_evaluator + profile: analyzer + mode: score + convergence: + metric: score # Evidence.payload.score + threshold: 0.05 # stop when improvement < 5% + maxIterations: 8 + budgetUsd: 5.00 + onExhaustion: accept_best +``` + +--- + +## 19. Connector + +Registry entity in Kit. Uses Gears OAGW as networking infrastructure. + +``` +Connector (registry) { + id: GTS Type Identifier (gts.cf.studio.core.connector.v1~...) + sourceSystem: string // "jira", "github", "datadog" + oagwUpstreamRef: string // Gears Outbound API Gateway upstream resource ID + // created at Kit install via Outbound API Interface + rateLimit: { + requestsPerHour: int + burstSize: int + retryAfter: duration + } + syncProtocol: { + push?: { + webhookPath: string + secret: ref requiredSettings + supportedEvents: string[] + } + pull?: { + interval: duration + pageSize: int + incremental: boolean + } + preferred: push|pull // default: push if available + } + fieldMappings: FieldMapping[] + writeBackPolicy: WriteBackPolicy + workerIds: Worker[] +} +``` + +### 19.1 FieldMapping + +``` +FieldMapping { + externalField: string + studioField: string // dot-notation: "obj_ext.jira_priority" + kind: direct|lookup|transform + lookupTable?: { [externalValue]: studioValue } + transformWorker?: ref Worker +} +``` + +### 19.2 WriteBackPolicy + +``` +WriteBackPolicy { + allowedActions: string[] // ["create:task", "update:task.state"] + requiresApproval: boolean // default: false + conflictStrategy: overwrite|skip|merge|escalate // default: escalate +} +``` + +### 19.3 Scope Filter (per Tenant) + +Configured at Kit installation time. Schema declared by Connector Kit via GTS Type Schema. + +``` +// example: Jira Connector scopeFilter +scopeFilter: { + "projects": ["STUDIO", "PLATFORM"], + "issueTypes": ["Bug", "Story", "Epic"], + "maxAge": "180d" +} +``` + +--- + +## 20. Staleness Model + +### 20.1 stalenessScore Formula + +``` +timeStaleness = (now - updatedAt) / type.stalenessPolicy.timeTTL +dependencyStaleness = 1.0 if any linked Object in dependencyTypes changed after updatedAt +syncStaleness = (now - externalRef.lastSyncedAt) / connector.syncExpectedInterval + // only for Objects with externalRef + +stalenessScore = max(timeStaleness, dependencyStaleness, syncStaleness) +``` + +### 20.2 Staleness Policy (in x-gts-traits) + +Declared per Object type. Tenant can override via `obj_ext`. + +```json +"x-gts-traits": { + "stalenessPolicy": { + "timeTTL": "14d", + "dependencyTypes": ["gts...design.v1~", "gts...requirement.v1~"], + "recommendationThreshold": 0.7 + } +} +``` + +### 20.3 Staleness Analyzer + +`stale_artifact_detection` Analyzer Worker (from Flow Library): +- Updates `stalenessScore` on affected Objects +- Profile: `realtime`; `defaultSchedule: "*/15 * * * *"`; `eventTrigger.debounce: 5m` +- Creates `Recommendation` when `stalenessScore >= recommendationThreshold` + +--- + +## 21. Approval & Human Control Points + +``` +Approval extends Object { + typeId: gts.cf.studio.core.object.v1~cf.studio.core.approval.v1~ + kind: risk_acceptance|security_exception|release_approval + |architecture_decision|custom + requiredRole: RolePattern + state: pending|approved|rejected|expired + payload: GTS Type Schema (typed per kind) + sessionId?: ref ValidationSession // if from Validator escalation + decidedBy: ref User? + decidedAt: datetime? + expiresAt: datetime? + customerImpact?: { + scope: none|internal|subset|all + affectedUsers: string? + rollbackPlan: string? + } + // Chain support: + prerequisiteApprovalId?: ref → Approval // blocked until prerequisite is approved + stepNumber?: int // 1-based position in chain + totalSteps?: int // total chain length + approvalSetId?: string // UUID; all Approvals in set must be approved + distinctApprovers?: boolean // default: true in sets; prevents single-person all-approval + // Delegation: + delegatedBy?: ref → User // original required approver + delegatedTo?: ref → User // delegate (platform validates role compatibility) + delegatedAt?: datetime +} +``` + +### 21.1 Security Exception Payload + +```json +{ + "expiresAt": "2026-10-01T00:00:00Z", + "acceptedRisk": "Known XSS in legacy component", + "mitigations": ["WAF rule", "monitoring alert"], + "secondaryApprover": "user-456", + "autoReviewAfter": "90d" +} +``` + +`autoReviewAfter` triggers a new `Approval` via scheduled Worker. + +--- + +## 22. Flow Library Catalog + +### 22.1 Analyzer Workers (12) — detect gaps → create Recommendations + +All Analyzers are read-only except `stale_artifact_detection` which also writes `Object.stalenessScore`. + +**Supersedes chain awareness:** `gap_analysis` and `traceability_analysis` understand the supersedes chain. +If requirement_v1 has ValidationSession (tested) and requirement_v2 supersedes requirement_v1: +→ Recommendation: "requirement R-17 v2 requires new validation" (not "untested"). +Analyzers traverse `links[kind=supersedes]` to find the versioning chain. + +| Name | Runtime | Profile | Input Objects | Output | +|---|---|---|---|---| +| `gap_analysis` | hybrid | scheduled | requirement, task, test_case, pull_request | Recommendation[] | +| `traceability_analysis` | hybrid | scheduled | requirement, design, task, pull_request, test_case | TraceabilityReport + Recommendation[] | +| `contradiction_detection` | llm | on_demand | document[] (any two or more) | Recommendation[] | +| `bloat_detection` | hybrid | on_demand | requirement[], task[] | Recommendation[] | +| `stale_artifact_detection` | script | realtime | Object (wildcard — any type) | **Object.stalenessScore updated** + Recommendation[] | +| `ownership_gap_analysis` | script | realtime | Object (wildcard — ownerId == null) | Recommendation[] | +| `duplicate_work_detection` | llm | on_demand | task[], requirement[] | Recommendation[] | +| `architecture_drift_detection` | hybrid | scheduled | component, component_dependency, design | Recommendation[] | +| `security_impact_analysis` | hybrid | scheduled | pull_request, vulnerability, security_finding | Recommendation[] | +| `test_gap_detection` | hybrid | scheduled | requirement, test_case | Recommendation[] | +| `operations_metrics_analysis` | hybrid | scheduled | slo, sli, metric_definition, alert | Recommendation[] | +| `ai_cost_efficiency_analysis` | script | scheduled | WorkerRun[] (runtime: llm\|hybrid) | CostReport + Recommendation[] | + +### 22.2 Flows — mandatory step sequences + +**Note on Runbook execution:** Runbook execution is implemented as a Kit-specific Flow +(kind: orchestrator). A `runbook` document defines the steps; a Kit packages a +corresponding Flow with `steps[]` derived from the runbook procedure. There is no +single `runbook_execution_worker` — each runbook step becomes a Flow step Worker. + +**`bug_to_fix_pr_flow`** — Killer Workflow 1: +``` +entryConstraints: bug (state: open) +mandatorySteps: bug_description_validator + confirm_test_fails_validator + confirm_test_passes_validator +allowedNextSteps: + bug_description_validator → find_suspected_component + find_suspected_component → deploy_test_environment + deploy_test_environment → reproduce_bug + reproduce_bug → create_failing_test + create_failing_test → confirm_test_fails_validator + confirm_test_fails_validator → implement_fix + implement_fix → confirm_test_passes_validator + confirm_test_passes_validator → create_pr +``` + +**`release_readiness_review`** — Killer Workflow 2 gate: +``` +entryConstraints: release (state: candidate) +mandatorySteps: gap_analysis_validator + test_coverage_validator (>= 80%) + security_scan_validator + tech_lead_approval +``` + +**`incident_to_postmortem_flow`** — Incident postmortem automation: +``` +entryConstraints: incident (state: resolved) +mandatorySteps: incident_summary_validator + postmortem_draft_worker + prevention_tasks_worker +allowedNextSteps: + incident_summary_validator → postmortem_draft_worker + postmortem_draft_worker → prevention_tasks_worker +``` + +### 22.3 Validator Workers + +Validators referenced by Flows and Killer Workflows: + +| Worker | Runtime | Profile | Flow / Scenario | +|---|---|---|---| +| `bug_description_validator` | hybrid | realtime | `bug_to_fix_pr_flow` mandatory step 1 | +| `confirm_test_fails_validator` | script | realtime | `bug_to_fix_pr_flow` mandatory step 2 | +| `confirm_test_passes_validator` | script | realtime | `bug_to_fix_pr_flow` mandatory step 3 | +| `gap_analysis_validator` | hybrid | realtime | `release_readiness_review` mandatory step 1 | +| `test_coverage_validator` | script | realtime | `release_readiness_review` mandatory step 2 | +| `security_scan_validator` | hybrid | realtime | `release_readiness_review` mandatory step 3 | +| `pr_design_validator` | hybrid | realtime | SDLC Kit: PR → design conformance (§23.3) | +| `incident_summary_validator` | hybrid | realtime | `incident_to_postmortem_flow` mandatory step 1 | + +### 22.4 Worker Metadata + +All Workers and Flows carry UI metadata: +``` +metadata: { + displayName: string + description: string + category: quality|security|ops|ai-cost|traceability + icon?: string + profile: realtime|scheduled|on_demand +} +``` + +--- + +## 23. Traceability Cross-References (Killer Workflows) + +Studio uses a **two-layer link model**: + +1. **`Object.links[]`** — generic Jira-style typed graph edges (see §1.1) for contextual + relationships. Used for: prd→design (derived_from), design→adr (references), etc. + Traversed via: `GET /objects/{id}/links?kind=...&depth=N&direction=outgoing|incoming` + +2. **Spec-level Contract fields** — explicit refs required by Validator Workers: + `pull_request.conformsToDesign`, `pull_request.implementsRequirements`, + `test_case.verifiesRequirements`. Contract inputs — NOT in `links[]`. + +**Mixed traversal pattern** (used by `traceability_analysis`): + +``` +// task.links = [{ targetId: requirement, kind: implements }] +// Direction: task ──→ requirement (task implements requirement) +// Traversal from requirement: GET /objects/{req_id}/links/incoming?kind=implements + +requirement ←──[links[]: implements]── task (task declares it implements requirement) + task ←── pull_request.closesIssues (spec-level Contract field) + pull_request.verifiedBy ──→ test_case (spec-level Contract field) +``` + +Note: `links[]` traversal uses **incoming direction** when starting from requirement. +Platform API: `GET /objects/{id}/links?direction=incoming|outgoing|both`. + +`traceability_analysis` uses BOTH mechanisms — they serve different purposes and +are not interchangeable. Platform provides unified Object fetch API for both paths. + +### D19 — SDLC Traceability Chain + +```mermaid +flowchart LR + REQ["requirement"] -->|implemented by| TASK["task"] + TASK -->|closed by| PR["pull_request"] + PR -->|triggers| BUILD["build"] + BUILD -->|produces| ART["build_artifact"] + ART -->|deployed as| DEP["deployment"] + DEP -->|targets| ENV["environment"] +``` + +### D20 — Design-to-Code Traceability + +```mermaid +flowchart LR + PRD["prd"] -->|elaborated by| DES["design"] + DES -->|decomposed into| DEC["decomposition"] + DEC -->|specifies| FS["feature_spec"] + FS -->|implemented in| SF["source_file"] + SF -->|lives in| REPO["repository"] +``` + +### 23.1 pull_request references + +``` +pull_request { + closesIssues: task[] // tasks resolved by this PR + implementsRequirements: requirement[] // requirements implemented + conformsToDesign: design[] // design documents validated against + verifiedBy: test_case[] // tests that verify the fix +} +``` + +### 23.2 test_case references + +``` +test_case { + verifiesRequirements: requirement[] // direct coverage link + verifiesFeature?: feature_spec // optional detailed spec +} +``` + +### 23.3 pr_design_validator (SDLC Kit) + +``` +pr_design_validator extends Validator { + runtime: hybrid + profile: realtime + trigger: { onEvent: { pattern: state_changed, filter: "pull_request → review" } } + input: { pull_request, design[], acceptance_criteria[] } + output: { validation_result, evidence } +} +``` + +--- + +## 24. SDLC Workers (producers) + +These Workers are the "executable edges" of the Studio graph — they drive state +transitions between Objects and may write back to external systems. All have +`requiresAutomationGate: true` and require Gate 1 before a WorkerRun is created. + +In Studio UI they appear as **Actions** (clickable buttons) when the user has +sufficient permissions and `automationLevel >= approved_automation`. + +### 24.1 Worker Catalog + +| Worker | Runtime | Profile | Input → Output | +|---|---|---|---| +| `create_design_worker` | llm | on_demand | prd → design | +| `decompose_feature_worker` | llm | on_demand | design → decomposition + task[] | +| `implement_code_worker` | llm | on_demand | feature_spec → source_file[] | +| `create_pr_worker` | hybrid | on_demand | source_file[], branch → pull_request | +| `deploy_worker` | script | on_demand | build_artifact, environment → deployment | +| `create_postmortem_worker` | llm | on_demand | incident → postmortem | +| `find_suspected_component` | hybrid | on_demand | bug → component[] | +| `deploy_test_environment` | script | on_demand | component → environment | +| `reproduce_bug` | hybrid | on_demand | bug, environment → WorkerRun (repro evidence) | +| `create_failing_test` | llm | on_demand | bug, reproduce output → test_case | +| `implement_fix` | llm | on_demand | bug, test_case → source_file[] | +| `postmortem_draft_worker` | llm | on_demand | incident, WorkerRun[] → postmortem | +| `prevention_tasks_worker` | hybrid | on_demand | postmortem → task[] | +| `alert_to_incident_worker` | hybrid | onEvent | alert [sync: datadog\|pagerduty] → incident (open) + on_call assignment; `eventTrigger.pattern: object_created, filter: typeId=alert.v1~` | +| `incident_triage_worker` | llm | on_demand | incident, alert[], recent WorkerRun[] → incident.severity updated + task[] (triage) | +| `deployment_rollback_worker` | script | on_demand | deployment (failed), build_artifact (previous) → deployment (rollback); Gate 2 for prod | + +### 24.2 Approval Gates + +Workers with `requiresAutomationGate: true` are governed by two independent gates: + +**Gate 1 — Studio execution gate** (checked at WorkerRun creation): +``` +Worker.requiresAutomationGate == true +AND automationLevel >= approved_automation +AND Worker.metadata.category in Tenant.approvedWorkerCategories +``` + +**Gate 2 — Connector write-back gate** (checked before external system write): +``` +WriteBackPolicy.requiresApproval == true +→ CREATE Approval { kind: "custom", requiredRole: ... } +→ await approval before executing write-back +``` + +Gate 1 controls whether Studio can run the Worker at all. +Gate 2 controls whether the Worker's output can be written back to an external system. +Both gates are independent and both may apply to the same WorkerRun. + +--- + +## 25. Platform Workers + +Platform Workers are pre-installed in every Tenant. They are not Kit Workers and do not require Kit approval. They are not subject to the `automationLevel` Gate 1. + +``` +pre-installed: true +requires_kit_approval: false +requiresAutomationGate: false +metadata.category: platform +``` + +| Worker | Runtime | Profile | Purpose | +|---|---|---|---| +| `audit_exporter` | script | on_demand | Export AuditLog (webhook, JSON). Vendor-specific formats via Kits. | +| `connector_inbound_sync_worker` | script | realtime | Receive Gears OAGW event → create/update Object in graph. Calls per-Kit `event_handler_worker` for custom mapping. | +| `connector_outbound_sync_worker` | script | on_demand | Object change → Connector write-back via WriteBackPolicy. | +| `data_erasure_worker` | script | on_demand | Process DataErasureRequest — anonymize or delete PII-containing Objects per GDPR request. Creates WorkerRun on request activation. | +| `is_assigned_to_principal_worker` | script | on_demand | ABAC condition: checks `object.ownerId == principal.id` (base field) then `object.assigneeId == principal.id` (type-specific, if present). Standard building block for Policy.rules.condition. | +| `is_workspace_member_worker` | script | on_demand | ABAC condition: `allowed = principal is member of object.workspaceId`. If `object.workspaceId == null` (Tenant-level Object) → `allowed: true` (no workspace restriction). | +| `is_object_owner_worker` | script | on_demand | ABAC condition: `allowed = object.ownerId == principal.id`. Owner-only write access pattern. | + +Per-Kit Connectors may register additional `event_handler_worker` Workers in their Kit manifest using the naming convention `{vendor}_{connector}_event_handler` (e.g. `jira_jira_event_handler`, `github_github_event_handler`). These are registered through the standard Worker registry and are not platform Workers. + +### 25.2 Retriever Workers + +Retriever Workers are pre-installed platform Workers (`metadata.category: retrieval`, `requiresAutomationGate: false`) that provide semantic retrieval for LLM Workers. Embedding generation and vector storage are owned by **Gears Models** (tenant-isolated); Studio Workers only call the retrieval interface. + +LLM Workers declare Retriever Workers in `dependencies[]`. Document chunks live outside the Object graph (in Gears Models); retrieval events are recorded in `WorkerRun.externalEvents[].chunkRef` for audit trail. + +| Worker | Index Kind | Scope | Purpose | +|---|---|---|---| +| `object_graph_retriever` | object_graph | workspace | Semantic search over Object attributes in the Studio graph | +| `document_retriever` | document_index | workspace | Chunk search over document content (PRD, design, specs, wiki) | +| `code_retriever` | code_index | workspace | Semantic code search over source_file content | + +Indexing is triggered automatically via `onEvent: object_created / object_updated` for Objects with indexable content fields. Chunking and embedding generation are handled by Gears Models indexing pipeline. + +--- + +## 26. Gears Integration Reference + +Studio v2 is a **Business Logic Gear** built on Constructor Fabric Gears. This table +maps Studio domain concepts to the Gears they depend on. + +| Studio concept | Gears gear | Integration pattern | +|---|---|---| +| `Tenant` | Resource Groups | Tenant extends Gears RG type via GTS chaining | +| `User` | Account Manager | User extends Gears AM user via GTS chaining | +| `Object graph` | Durable Objects (possible) | Object persistence MAY use Durable Objects as backend; architecture decision not finalized in domain model | +| `GTS Type IDs` | Types Registry | Schema storage and validation for all GTS types | +| Worker (runtime: llm) | LLM Gateway | All LLM calls → LLM Gateway; cost response → WorkerRun.cost | +| Worker model selection | Models Registry | `Worker.config.llm.model` = GTS Type ID from Models Registry | +| Worker (runtime: script) | Serverless Gateway + Runtimes | Script Workers run as Starlark/Python serverless functions | +| `PromptExperiment` | Prompts Registry | PromptExperiment uses Prompts Registry versioning + A/B rollout | +| `Worker.defaultSchedule` | Jobs Manager | Jobs Manager creates WorkerRuns on schedule; WorkerRun.trigger.kind: scheduled | +| `eventTrigger` | Events Broker | Events Broker fires WorkerRun on GTS event pattern match | +| Studio events | Events Broker | All Object lifecycle + WorkerRun events published to Events Broker | +| `EventSubscription` | Events Broker | Outbound delivery via Events Broker subscription | +| `NotificationRule` delivery | Notifications Service | Notifications Service handles in-app/email/webhook channels | +| `Approval` | Approvals gear (delivery only) | Studio Approval = rich Domain Object with own semantics (chains, delegation, payload); Gears Approvals used for notification delivery and SLA reminders only | +| `AuditLog` | Audit gear | WorkerRun audit trail → Gears Audit (immutable events) | +| `WorkerRun.cost` | Usage Collector | Usage Collector records LLM usage per tenant | +| `effectiveLimits.token_budget` | Quota Enforcer | Quota Enforcer checks budget before WorkerRun creation | +| `Kit.requiredSettings[secret=true]` | **Credentials Store** | Secrets stored in Gears Credentials Store (NOT Settings Service) | +| `Kit.requiredSettings[secret=false]` | Settings Service | Non-secret preferences stored in Gears Settings Service | +| `Connector.oagwUpstreamRef` | Outbound API Gateway | Reference to Gears Outbound API Gateway upstream resource | +| `connector_inbound_sync_worker` | Outbound API Interface | Inbound events received via Outbound API Gateway (push) | +| `Retriever Workers` (RAG) | Local Search Index | `document_retriever` + `code_retriever` use Local Search Index | +| `document_retriever` parsing | File Parser | File Parser (PDF/DOCX/Markdown) used for document ingestion | +| `Policy.condition` Worker | Policy Manager | ABAC condition evaluation via Gears Policy Manager | +| `Tenant Resolver` | Tenant Resolver | Multi-tenant hierarchy resolution | +| Studio API | API Gateway | All external HTTP traffic through Gears API Gateway | +| `WorkerRun` AI Agents | AI Agents Registry | LLM Workers can register as AI Agents in Gears registry | +| Studio as MCP | MCP Registry | Studio exposes tools via Gears MCP Registry | + +**Key distinction: Credentials Store vs Settings Service** + +- **Credentials Store** — API keys, tokens, secrets (`secret: true` in Kit.requiredSettings) +- **Settings Service** — tenant/user preferences, feature flags, non-secret configuration + +These are different Gears. Kit secrets always go to Credentials Store; never to Settings Service. + +--- + +## 27. Agentic Loop Runs + +### 27.1 Motivation + +Modern AI engineering increasingly relies on **agentic feedback loops** — autonomous systems where an LLM agent iteratively proposes solutions, receives structured feedback from validators and evaluators, and refines its approach until convergence or budget exhaustion. This pattern is described in recent research as "Agentic Auto-Scheduling" (Merouani et al. 2025) and underpins code optimization, design refinement, test generation, and any task where quality improves through iteration. + +Constructor Studio is designed to be the **control plane** for exactly this pattern. The concern that "loops burn tokens" is a real one; Studio treats token budget as a **first-class constraint**, not an afterthought. + +The canonical loop structure: + +1. **Propose** — LLM Worker generates a candidate artifact or transformation +2. **Validate** — Validator Worker checks structural/semantic correctness; invalid candidates cycle back without advancing the metric +3. **Evaluate** — Evaluator Worker measures a quality metric (coverage score, performance ratio, conformance grade) +4. **Synthesize feedback** — Feedback Worker packages Evidence + metric delta into a structured `suggestedInput` for the next iteration +5. **Convergence check** — compare metric improvement against `ConvergencePolicy.threshold` +6. **Loop or terminate** — continue if improvement ≥ threshold and budget allows; terminate with `terminationReason` otherwise + +### 27.2 Native Architecture Support + +Studio's existing primitives compose directly into this pattern without any new runtime. No new engine is needed — the orchestrator `Flow` already provides sequential step execution and loop semantics through its `runtime: orchestrator` + `loopPolicy` extension. + +| Loop concept | Studio primitive | +|---|---| +| Loop controller | `Flow` with `runtime: orchestrator` and `loopPolicy` attached | +| Proposal step | `Worker (runtime: llm, profile: on_demand)` | +| Validation step | `Worker (runtime: llm\|script, profile: validator)` | +| Evaluation step | `Worker (runtime: llm\|script, profile: analyzer)` | +| Feedback synthesis | `Worker (runtime: llm, profile: on_demand)` | +| One iteration boundary | `WorkerRun` group sharing a common `parentRunId = LoopRun.id` | +| Quality metric | `Evidence.payload.score` emitted by Evaluator Worker | +| Token spend per iteration | `WorkerRun.cost` (LLM Gateway → Usage Collector) | +| Accumulated loop spend | `LoopRun.totalCostUsd` (sum of all child `WorkerRun.cost`) | +| Hard budget cap | `effectiveLimits.token_budget` + `BudgetPolicy.maxTokensPerLoop` | +| Convergence history | `ValidationSession.iterations[]` | +| Loop termination record | `LoopRun.terminationReason` | +| Immutable audit trail | `AuditLog` — all WorkerRuns per iteration are immutable | + +### 27.3 Loop = Flow + LoopPolicy + +**A Loop is not a separate entity type. It is a Flow with a `loopPolicy` field set.** + +This is the key architectural decision: the same Flow registry, the same steps[] definition, the same Kit packaging — with one additional optional field that opts the Flow into iterative execution semantics. A Flow without `loopPolicy` runs its steps once and terminates. A Flow with `loopPolicy` runs its steps repeatedly until convergence or budget exhaustion. + +``` +Flow { + id, label, description, steps[], ... // same as §6 + loopPolicy?: LoopPolicy // optional — presence activates loop mode +} +``` + +In the Studio UI, when launching a Flow that has `loopPolicy` set, the user is presented with the Loop configuration panel (metric, threshold, budget) rather than the standard Flow launcher. The Flow's steps define *what* runs each iteration; the LoopPolicy defines *when to stop* and *how to pass feedback forward*. + +This means: +- **Loop catalog = subset of Flow catalog** filtered on `loopPolicy != null` +- **Launching a loop = launching a Flow** with LoopPolicy overrides (user may tune threshold/budget at launch time) +- **A Flow designed for loops** includes the evaluator step that emits `Evidence.payload.score` — the metric the LoopPolicy tracks +- **Existing Flows** can be "promoted" to loops by adding `loopPolicy` in the Kit definition — no code change + +### 27.3a LoopPolicy + +Attached to a `Flow` definition; governs convergence, budget, and feedback context. + +``` +LoopPolicy { + convergence: { + metric: string // Evidence field path to track (e.g. "score", "coverage", "speedup_ratio") + threshold: float // minimum improvement per iteration to continue (e.g. 0.05 = 5%) + minIterations: int // always run at least N iterations regardless of metric (default: 1) + maxIterations: int // hard stop even if still improving (default: 10) + windowSize: int // compare metric over last N iterations to detect plateau (default: 1) + direction: 'maximize' | 'minimize' // is higher or lower metric better? + } + budget: { + maxTokensPerLoop: int // total token budget for the whole loop (across all iterations) + maxCostUsd: float // cost cap enforced by Quota Enforcer (Gears) before each iteration + warningThreshold: float // emit BudgetWarning event at X% consumed (default: 0.80) + onExhaustion: 'escalate' | 'abort' | 'accept_best' + // escalate → create Approval; loop paused until approved or rejected + // abort → LoopRun.state: failed, best result discarded + // accept_best → LoopRun.state: done, bestIterationIdx result accepted + } + feedback: { + summarizeHistory: boolean // include prior iteration summaries in proposer context + maxHistoryIterations: int // how many prior iteration summaries to include (default: 3) + includeEvidencePayload: boolean // pass raw Evidence payload to next iteration's proposer + evidenceSizeLimit: int // max bytes of Evidence to include (prevents context bloat) + } +} +``` + +### 27.4 LoopRun + +`LoopRun` extends `FlowRun` with iteration-tracking fields. It is the single observable unit representing the entire agentic loop execution. + +``` +LoopRun extends FlowRun { + // Iteration tracking + iterations: IterationRun[] + currentIteration: int + bestScore: float + bestIterationIdx: int // 0-based index into iterations[] + + // Convergence + converged: boolean + terminationReason: 'converged' | 'maxIterations' | 'budgetExhausted' | 'failed' | 'escalated' | 'aborted' + + // Budget aggregates (live totals, updated after each WorkerRun completes) + totalCostUsd: float + totalTokens: int + budgetConsumedPct: float // 0.0–1.0; checked before each new iteration +} + +IterationRun { + iteration: int // 1-based + score: float // metric value this iteration + improvement: float // score − previousScore (direction-aware) + valid: boolean // passed validation step + costUsd: float // sum of all WorkerRun.cost this iteration + tokens: int + durationMs: int + proposerRunId: ref → WorkerRun + validatorRunIds: ref[] → WorkerRun + evaluatorRunId: ref → WorkerRun + feedbackRunId: ref → WorkerRun + evidenceId: ref → Evidence // Evidence emitted by evaluator +} +``` + +### 27.5 Loop Termination Conditions + +A LoopRun terminates when the **first** matching condition is true, checked in this order at the end of each iteration: + +| Condition | `terminationReason` | `LoopRun.state` | +|---|---|---| +| `improvement < threshold` for last `windowSize` iterations | `converged` | `done` | +| `currentIteration >= maxIterations` | `maxIterations` | `done` | +| `totalTokens >= maxTokensPerLoop` OR `totalCostUsd >= maxCostUsd` with `onExhaustion: accept_best` | `budgetExhausted` | `done` | +| Same budget exhausted with `onExhaustion: escalate` | `escalated` | `paused` → Approval required | +| Same budget exhausted with `onExhaustion: abort` | `budgetExhausted` | `failed` | +| Any mandatory step fails and `Flow.onStepFailure: abort` | `failed` | `failed` | + +### 27.6 Token Budget as a First-Class Constraint + +The "loops burning tokens" risk is addressed by multi-layer budget enforcement — not a single guard, but a defense-in-depth stack: + +``` +Layer 1 — Pre-loop: Quota Enforcer (Gears) checks effectiveLimits.token_budget + before the LoopRun is created. No LoopRun starts over quota. + +Layer 2 — Pre-iteration: budgetConsumedPct checked before each new iteration begins. + If >= 1.0, loop terminates per onExhaustion policy. + +Layer 3 — Per-WorkerRun: WorkerRun.cost recorded by LLM Gateway → Usage Collector + immediately after each LLM call. No post-hoc estimation. + +Layer 4 — Warning event: BudgetWarning Event emitted when budgetConsumedPct >= + warningThreshold (default 80%). NotificationRule can alert + the operator or trigger an Approval before exhaustion. + +Layer 5 — Audit: All WorkerRun.cost values are immutable in AuditLog. + Full cost breakdown per iteration always recoverable. +``` + +The key invariant: **the loop never starts an iteration it cannot afford**. Budget is checked before the proposer runs, not after. + +### 27.7 Architecture Diagram + +The complete agentic loop execution flow: + +```mermaid +sequenceDiagram + participant UI as Studio UI / API + participant LR as LoopRun (orchestrator) + participant QE as Quota Enforcer (Gears) + participant P as Proposer Worker (LLM) + participant V as Validator Worker + participant E as Evaluator Worker + participant F as Feedback Worker (LLM) + participant AL as AuditLog + + UI->>LR: startLoop(flowId, inputObject, loopPolicy) + LR->>QE: checkBudget(maxTokensPerLoop, maxCostUsd) + QE-->>LR: approved / rejected + + loop Each iteration i = 1..maxIterations + LR->>QE: checkBudget(remaining = max − totalCostUsd) + QE-->>LR: ok | warning | exhausted + + alt budgetConsumedPct >= warningThreshold + LR-->>UI: Event(BudgetWarning, pct, remaining) + end + alt budgetConsumedPct >= 1.0 + LR-->>UI: LoopRun{terminationReason: budgetExhausted} + end + + LR->>P: run(context + feedbackHistory[last N]) + P-->>LR: candidate + WorkerRun{cost, tokens} + LR->>AL: append(iteration i, proposerRun) + + LR->>V: validate(candidate) + V-->>LR: Evidence{valid: true|false, errors[]} + + alt invalid + LR->>F: synthesize_feedback(errors, history) + F-->>LR: suggestedInput (no score advance this iteration) + else valid + LR->>E: evaluate(candidate, metric) + E-->>LR: Evidence{score, breakdown} + LR->>F: synthesize_feedback(score, evidence, history) + F-->>LR: suggestedInput for next iteration + LR->>LR: updateBestScore(score) + end + + LR->>LR: convergenceCheck(improvement, threshold, windowSize) + note over LR: improvement < threshold for windowSize iters → converged + end + + LR-->>UI: LoopRun{terminationReason, bestScore, bestIterationIdx, totalCostUsd, totalTokens} + LR-->>AL: finalize(LoopRun) +``` + +### 27.8 State Machine: LoopRun + +```mermaid +stateDiagram-v2 + [*] --> pending : startLoop() + pending --> running : Quota approved + pending --> failed : Quota rejected + + running --> running : iteration complete, improvement ≥ threshold + running --> paused : budgetWarning + onExhaustion=escalate → Approval pending + running --> done : converged + running --> done : maxIterations reached + running --> done : budgetExhausted + onExhaustion=accept_best + running --> failed : step failure + onStepFailure=abort + running --> failed : budgetExhausted + onExhaustion=abort + + paused --> running : Approval granted (budget extended) + paused --> failed : Approval rejected + + done --> [*] + failed --> [*] +``` + +### 27.9 Monitor View: Iteration Tree + +The Monitor renders a LoopRun as a collapsible iteration tree. Each iteration shows its score, improvement delta (colour-coded), cost, and child WorkerRuns. + +``` +▼ LoopRun: code_quality_optimization_loop [converged] $0.56 4 iter + ▼ Iteration 1 score: 0.62 $0.14 8.2s + ✓ implement_code_worker done 1.2s $0.08 + ✓ pr_design_validator pass 0.3s $0.01 + ✓ code_quality_evaluator done 0.8s $0.02 + ✓ feedback_synthesizer_worker done 0.5s $0.03 + ▼ Iteration 2 +0.16 score: 0.78 $0.15 7.9s + ✓ implement_code_worker done 1.1s $0.07 + ✓ pr_design_validator pass 0.3s $0.01 + ✓ code_quality_evaluator done 0.7s $0.02 + ✓ feedback_synthesizer_worker done 0.4s $0.05 + ▼ Iteration 3 +0.06 score: 0.84 $0.13 7.4s + ✓ implement_code_worker done 1.0s $0.07 + ✓ pr_design_validator pass 0.3s $0.01 + ✓ code_quality_evaluator done 0.6s $0.02 + ✓ feedback_synthesizer_worker done 0.4s $0.03 + ▼ Iteration 4 ★ best +0.03 score: 0.87 $0.14 7.2s + ✓ implement_code_worker done 1.0s $0.07 + ✓ pr_design_validator pass 0.3s $0.01 + ✓ code_quality_evaluator done 0.6s $0.02 + ✓ feedback_synthesizer_worker done 0.4s $0.04 + → Converged: improvement 0.03 < threshold 0.05 (window=1) + → Budget used: $0.56 / $5.00 (11%) · 124k / 200k tokens (62%) +``` + +Budget bar and score chart are shown in the Monitor detail panel. + +### 27.10 Relationship to §18 Validator Loop + +§18 defines the **Validator Loop** — a single-step retry cycle for one Object state transition. §27 defines the **Agentic Loop** — a multi-step, multi-iteration optimisation loop with convergence semantics and budget tracking. They are complementary, not competing. + +| Aspect | §18 Validator Loop | §27 Agentic Loop | +|---|---|---| +| Purpose | Gate one state transition | Iteratively improve a proposal | +| Trigger | Object state-change attempt | Explicit `startLoop` call | +| Iterations | `maxRetries` per transition | `maxIterations` per loop | +| Success metric | binary pass/fail | continuous score (float) | +| Feedback | error list back to fix agent | structured Evidence payload | +| Budget | per-run `token_budget` | accumulated `maxTokensPerLoop` | +| Escalation | maxRetries exceeded → human | `budgetExhausted` + policy | +| Output | valid state transition | best proposal found so far | + +A Validator Loop (§18) MAY run **inside** an Agentic Loop (§27) as the validation step for each iteration. In this case `IterationRun.valid` is determined by the inner Validator Loop's `ValidationSession.state`. + +### 27.11 Example: Code Quality Optimization Loop + +A concrete SDLC Kit example demonstrating the full pattern: + +``` +Flow: code_quality_optimization_loop + input: pull_request (state: review) + output: pull_request (state: approved, validationStatus: pass) + + steps per iteration: + 1. implement_code_worker (proposer) — runtime: llm + 2. pr_design_validator (validator) — runtime: script + 3. code_quality_evaluator (evaluator) — runtime: llm; emits Evidence{score} + 4. feedback_synthesizer_worker (feedback) — runtime: llm; emits suggestedInput + + loopPolicy: + convergence.metric: "score" + convergence.threshold: 0.05 # stop when improvement < 5% + convergence.minIterations: 2 + convergence.maxIterations: 8 + convergence.direction: "maximize" + budget.maxTokensPerLoop: 200_000 + budget.maxCostUsd: 5.00 + budget.warningThreshold: 0.80 + budget.onExhaustion: "accept_best" + feedback.summarizeHistory: true + feedback.maxHistoryIter: 3 + + example run: + Iter 1: score=0.62 cost=$0.14 + Iter 2: score=0.78 (+0.16) cost=$0.15 ← improvement > 0.05, continue + Iter 3: score=0.84 (+0.06) cost=$0.13 ← improvement > 0.05, continue + Iter 4: score=0.87 (+0.03) cost=$0.14 ← improvement < 0.05, converged ★ + terminationReason: "converged" + totalCostUsd: $0.56 (11% of $5.00 budget) + totalTokens: 124_000 +``` + +### 27.12 Designer Guidance + +When designing an Agentic Loop in Studio: + +**Choose `onExhaustion: accept_best`** for most SDLC loops. The best result seen so far is almost always better than nothing — abandoning it on budget exhaustion wastes all prior work. + +**Set `minIterations: 2`** to avoid premature convergence. A single good-looking first result may be a local optimum. + +**Keep `maxHistoryIterations: 3`** unless your context window is very large. Including too much history inflates prompt size and increases cost per iteration geometrically. + +**Monitor `budgetConsumedPct`** live in the Monitor. If a loop consistently hits 80% before converging, either the metric threshold is too tight, the context is too large, or the task needs decomposition into smaller sub-loops. + +**Use `windowSize: 2` or `3`** for noisy evaluators (e.g. LLM-scored metrics). A single-iteration comparison is fragile when the evaluator has variance. + +--- + +## Appendix A — Studio v2 Object Type Catalog + +All types follow the pattern: +``` +gts.cf.studio.core.object.v1~cf.studio.core..v1~ +``` + +### Base Types (abstract) + +``` +cf.studio.core.document.v1~ // base for all textual/structured artifacts +cf.studio.core.infra_config.v1~ // base for all infrastructure configurations +cf.studio.core.prompt.v1~ // base for all AI prompt artifacts +``` + +### Domain 1 — Product / Requirements + +``` +cf.studio.core.prd.v1~ // → document +cf.studio.core.epic.v1~ +cf.studio.core.user_story.v1~ +cf.studio.core.requirement.v1~ // priority: critical|high|medium|low + // allCriticalRequirementsTraced computed from priority==critical +cf.studio.core.acceptance_criteria.v1~ +cf.studio.core.use_case.v1~ +cf.studio.core.user_persona.v1~ +cf.studio.core.product_roadmap.v1~ +cf.studio.core.feature_spec.v1~ // → document (Studio SDLC FEATURE) +cf.studio.core.decomposition.v1~ // → document (Studio SDLC DECOMPOSITION) +``` + +### Domain 2 — Architecture / Design + +``` +cf.studio.core.design.v1~ // → document (Studio SDLC DESIGN) +cf.studio.core.adr.v1~ // → document (Architecture Decision Record) +cf.studio.core.component.v1~ // architectural component + // kind: service|library|module|subsystem| + // frontend|backend|data-pipeline|sdk|plugin|cli|agent|gateway +cf.studio.core.component_version.v1~ // versioned snapshot of a component +cf.studio.core.component_dependency.v1~ // directed dependency between two components +cf.studio.core.interface_definition.v1~ +cf.studio.core.api_spec.v1~ // OpenAPI / GraphQL / gRPC +cf.studio.core.data_model.v1~ +cf.studio.core.architecture_diagram.v1~ +``` + +### D32 — Component Cross-References + +```mermaid +classDiagram + class component { + name: string + kind: service|library|module|subsystem|frontend|backend|data-pipeline|sdk|plugin|cli|agent|gateway + ownerId: ref team + repositoryId: ref repository + } + class component_version { + componentId: ref component + version: semver + commitId: ref commit + } + class component_dependency { + sourceId: ref component + targetId: ref component + kind: uses|implements|extends|calls + } + class team { + name: string + } + class repository { + url: string + } + + component "1" --> "many" component_version + component "1" --> "many" component_dependency : sourceId + component_dependency --> component : targetId + component --> team : ownerId + component --> repository : repositoryId +``` + +### D33 — Component ↔ Documentation & Architecture + +```mermaid +flowchart LR + COMP["component"] -->|documented by| DES["design\n→ document"] + COMP -->|decided by| ADR["adr\n→ document"] + COMP -->|specifies| IFACE["interface_definition"] + COMP -->|exposes| API["api_spec"] + COMP -->|visualized in| DIAG["architecture_diagram"] + COMP -->|traces to| REQ["requirement"] +``` + +### D38 — Dependency Graph Between Components + +```mermaid +flowchart LR + A["component A\n(frontend)"] -->|uses| B["component B\n(API gateway)"] + B -->|calls| C["component C\n(auth)"] + B -->|calls| D["component D\n(data)"] + D -->|extends| E["component E\n(shared lib)"] + C -->|extends| E +``` + +### Domain 3 — Source Code + +``` +cf.studio.core.repository.v1~ +cf.studio.core.source_file.v1~ +cf.studio.core.module.v1~ // package, namespace, library +cf.studio.core.complexity_metric.v1~ // cyclomatic/cognitive complexity +``` + +### Domain 3a — Technology Stack + +``` +cf.studio.core.tech_stack.v1~ // declared technology stack of a component/project +cf.studio.core.library.v1~ // software library / package (npm, PyPI, Maven, etc.) +cf.studio.core.library_version.v1~ // specific pinned version of a library +cf.studio.core.framework.v1~ // framework (React, Django, Spring, Rails, etc.) +cf.studio.core.runtime.v1~ // runtime environment (Node.js v20, Python 3.11, JVM 21) +cf.studio.core.database.v1~ // database technology (PostgreSQL, MongoDB, Redis, etc.) +cf.studio.core.database_instance.v1~ // specific deployed database instance +cf.studio.core.third_party_service.v1~ // external SaaS dependency (Stripe, SendGrid, Auth0) +cf.studio.core.cloud_service.v1~ // managed cloud service (AWS S3, GCP Pub/Sub, Azure SB) +cf.studio.core.tech_dependency.v1~ // directed: component uses library_version / database / service +``` + +### D39 — Technology Stack Types + +```mermaid +classDiagram + class tech_stack { + componentId: ref component + description: string + } + class library { + name: string + ecosystem: npm|pypi|maven|cargo|nuget|gem + } + class library_version { + libraryId: ref library + version: semver + licenseId: string? + } + class framework { + name: string + language: string + } + class runtime { + name: string + version: string + } + + tech_stack --> library_version : uses + tech_stack --> framework : uses + tech_stack --> runtime : targets + library_version --> library : libraryId +``` + +### D40 — Data & External Service Dependencies + +```mermaid +classDiagram + class tech_stack { + componentId: ref component + } + class database { + engine: postgres|mongo|redis|mysql|elastic + kind: relational|document|kv|search|timeseries + } + class database_instance { + databaseId: ref database + environmentId: ref environment + host: string + } + class third_party_service { + name: string + category: payments|email|auth|analytics|crm + url: string + } + class cloud_service { + provider: aws|gcp|azure + service: s3|pubsub|sqs|rds|bigquery + } + + tech_stack --> database : uses + tech_stack --> third_party_service : depends on + tech_stack --> cloud_service : uses + database "1" --> "many" database_instance + database_instance --> environment : deployed in +``` + +### D41 — Component ↔ Technology Stack + +```mermaid +flowchart LR + COMP["component"] -->|has| TS["tech_stack"] + TS -->|runtime| RUN["runtime\n(Node.js 20, JVM 21)"] + TS -->|framework| FW["framework\n(React, Django)"] + TS -->|libraries| LV["library_version\n(lodash 4.17)"] + TS -->|database| DB["database\n(PostgreSQL, Redis)"] + TS -->|external| SVC["third_party_service\n(Stripe, Auth0)"] + TS -->|cloud| CSC["cloud_service\n(AWS S3, GCP Pub/Sub)"] +``` + +### Domain 4 — Work Items + +``` +cf.studio.core.task.v1~ +cf.studio.core.bug.v1~ +cf.studio.core.spike.v1~ +cf.studio.core.tech_debt_item.v1~ +cf.studio.core.change_request.v1~ +``` + +### Domain 5 — Collaboration & Human Control + +``` +cf.studio.core.comment.v1~ +cf.studio.core.review_comment.v1~ +cf.studio.core.decision.v1~ +cf.studio.core.meeting_note.v1~ // → document +cf.studio.core.approval.v1~ // generic: kind=risk_acceptance|security_exception| + // release_approval|architecture_decision|custom + // payload typed per kind via GTS Type Schema +``` + +### Domain 6 — Version Control + +``` +// cf.studio.core.repository.v1~ // defined in Domain 3 +cf.studio.core.branch.v1~ +cf.studio.core.commit.v1~ +cf.studio.core.tag.v1~ +cf.studio.core.pull_request.v1~ // canonical (PR + MR) +cf.studio.core.diff.v1~ +cf.studio.core.merge_conflict.v1~ +``` + +### D21 — Version Control Cross-References + +```mermaid +classDiagram + class repository { + url: string + defaultBranch: string + } + class branch { + repositoryId: ref repository + name: string + } + class commit { + branchId: ref branch + sha: string + authorId: ref person + } + class pull_request { + repositoryId: ref repository + sourceBranch: ref branch + targetBranch: ref branch + } + class tag { + commitId: ref commit + name: string + } + + repository "1" --> "many" branch + branch "1" --> "many" commit + commit "many" --> "1" pull_request : included in + commit "1" --> "many" tag +``` + +### Domain 7 — CI/CD / Build + +``` +cf.studio.core.pipeline.v1~ // pipeline definition +cf.studio.core.pipeline_run.v1~ // execution instance +cf.studio.core.build.v1~ +cf.studio.core.pipeline_job.v1~ // job within pipeline +cf.studio.core.pipeline_step.v1~ // step within job +cf.studio.core.test_run.v1~ +cf.studio.core.test_case.v1~ +cf.studio.core.test_result.v1~ +cf.studio.core.code_coverage_report.v1~ +cf.studio.core.build_artifact.v1~ // binary, package, image +cf.studio.core.deployment.v1~ +cf.studio.core.deployment_status.v1~ +cf.studio.core.runner.v1~ // GitHub runner, Jenkins agent, GitLab runner +cf.studio.core.performance_benchmark.v1~ // k6, Locust, JMH +``` + +### D16 — CI/CD Object Relationships + +```mermaid +classDiagram + class pipeline { + definition: YAML ref + scope: string + } + class pipeline_run { + pipelineId: ref pipeline + state: pending|running|done|failed + triggeredBy: commit|schedule|manual + } + class pipeline_job { + runId: ref pipeline_run + runner: ref runner + } + class pipeline_step { + jobId: ref pipeline_job + state: string + } + class build_artifact { + jobId: ref pipeline_job + path: string + expiresAt: datetime? + } + class deployment { + artifactId: ref build_artifact + environment: ref environment + } + + pipeline "1" --> "many" pipeline_run + pipeline_run "1" --> "many" pipeline_job + pipeline_job "1" --> "many" pipeline_step + pipeline_job "1" --> "many" build_artifact + build_artifact "1" --> "many" deployment +``` + +### D22 — CI/CD Chain Cross-References + +```mermaid +flowchart TD + CMT["commit"] -->|triggers| PR["pipeline_run"] + PR -->|contains| JOB["pipeline_job"] + JOB -->|runs on| RUN["runner"] + JOB -->|executes| TST["test_run"] + JOB -->|produces| ART["build_artifact"] + TST -->|results in| TR["test_result"] + TR -->|references| TC["test_case"] +``` + +### D23 — Deployment & Environment Cross-References + +```mermaid +classDiagram + class deployment { + artifactId: ref build_artifact + environmentId: ref environment + state: pending|running|done|failed + } + class build_artifact { + jobId: ref pipeline_job + version: string + } + class environment { + name: dev|staging|prod + tenantId: ref Tenant + } + class deployment_status { + deploymentId: ref deployment + state: string + workerRunId: ref WorkerRun + } + + deployment --> build_artifact : artifactId + deployment --> environment : environmentId + deployment "1" --> "many" deployment_status +``` + +### Domain 8 — Artifacts / Packages + +``` +cf.studio.core.package.v1~ +cf.studio.core.package_version.v1~ +cf.studio.core.container_image.v1~ +cf.studio.core.container_image_tag.v1~ +``` + +### Domain 8a — SBOM (Software Bill of Materials) + +``` +cf.studio.core.sbom.v1~ // SBOM document (SPDX / CycloneDX / SWID) +cf.studio.core.sbom_component.v1~ // a package/library entry within an SBOM +cf.studio.core.sbom_relationship.v1~ // directed relationship between sbom_components + // kinds: CONTAINS, DEPENDS_ON, DESCRIBES, + // GENERATED_FROM, VARIANT_OF, PATCH_OF +cf.studio.core.sbom_license.v1~ // license declaration for an sbom_component + // (SPDX expression: MIT, Apache-2.0, GPL-3.0-only) +cf.studio.core.sbom_checksum.v1~ // cryptographic hash of an sbom_component + // (SHA256, SHA1, MD5, BLAKE2) +``` + +### D44 — SBOM Structure + +```mermaid +classDiagram + class sbom { + format: spdx|cyclonedx|swid + version: string + createdAt: datetime + artifactId: ref build_artifact + releaseId: ref release? + } + class sbom_component { + sbomId: ref sbom + name: string + version: string + supplier: string? + } + class sbom_relationship { + sbomId: ref sbom + sourceId: ref sbom_component + targetId: ref sbom_component + kind: CONTAINS|DEPENDS_ON|DESCRIBES|GENERATED_FROM|VARIANT_OF + } + + sbom "1" --> "many" sbom_component : DESCRIBES + sbom "1" --> "many" sbom_relationship + sbom_relationship --> sbom_component : sourceId + sbom_relationship --> sbom_component : targetId +``` + +### D45 — SBOM Component Details + +```mermaid +classDiagram + class sbom_component { + sbomId: ref sbom + name: string + version: string + } + class sbom_license { + componentId: ref sbom_component + spdxExpression: string + concluded: string? + declared: string? + } + class sbom_checksum { + componentId: ref sbom_component + algorithm: SHA256|SHA1|MD5|BLAKE2 + value: string + } + class library_version { + libraryId: ref library + version: semver + } + class dependency_vulnerability { + packageName: string + affectedVersions: string[] + } + + sbom_component "1" --> "many" sbom_license + sbom_component "1" --> "many" sbom_checksum + sbom_component --> library_version : maps to + sbom_component --> dependency_vulnerability : may have +``` + +### D46 — SBOM Cross-References + +```mermaid +flowchart LR + ART["build_artifact"] -->|generates| SBOM["sbom"] + REL["release"] -->|attaches| SBOM + SBOM -->|lists| COMP["sbom_component[]"] + COMP -->|license| LIC["sbom_license\n(MIT, Apache-2.0)"] + COMP -->|maps to| LV["library_version"] + LV -->|has| DV["dependency_vulnerability"] + DV -->|creates| TASK["task\n(remediation)"] +``` + +### D47 — SBOM ↔ Security & Compliance + +```mermaid +flowchart TD + SBOM["sbom"] -->|scanned by| SCAN["security_review\n(SCA scan)"] + SCAN -->|finds| DV["dependency_vulnerability[]"] + DV -->|references| CVE["cve"] + SBOM -->|license audit| CC["compliance_check\n(license policy)"] + CC -->|pass/fail| CCR["compliance_check_result"] + CCR -->|fail creates| PE["policy_exception\n(GPL in proprietary)"] +``` + +### Domain 9 — Release + +``` +cf.studio.core.release.v1~ +cf.studio.core.release_notes.v1~ // → document +cf.studio.core.changelog.v1~ // → document +cf.studio.core.version.v1~ +cf.studio.core.release_candidate.v1~ +cf.studio.core.release_component.v1~ // join: which component_version is included in a release +``` + +### D35 — Release Cross-References + +```mermaid +classDiagram + class release { + version: semver + state: draft|rc|published + repositoryId: ref repository + } + class release_component { + releaseId: ref release + componentVersionId: ref component_version + } + class component_version { + componentId: ref component + version: semver + commitId: ref commit + } + class build_artifact { + version: string + } + class deployment { + environmentId: ref environment + } + + release "1" --> "many" release_component + release_component --> component_version + component_version --> build_artifact : built as + build_artifact --> deployment : deployed as +``` + +### D36 — Release ↔ Work Items & Traceability + +```mermaid +flowchart LR + REL["release"] -->|includes| RC["release_component"] + RC -->|points to| CV["component_version"] + CV -->|tagged at| CMT["commit"] + CMT -->|closes| PR["pull_request"] + PR -->|resolves| TASK["task / bug"] + TASK -->|traces to| REQ["requirement"] + REL -->|documents| RN["release_notes\n→ document"] +``` + +### D37 — Full Component → Release → Deployment Chain + +```mermaid +flowchart TD + TEAM["team"] -->|owns| COMP["component"] + COMP -->|lives in| REPO["repository"] + REPO -->|triggers| PIPE["pipeline_run"] + PIPE -->|produces| ART["build_artifact"] + COMP -->|versioned as| CV["component_version"] + CV -->|included in| REL["release"] + REL -->|deployed via| DEP["deployment"] + DEP -->|targets| ENV["environment"] +``` + +### D43 — Tech Stack ↔ Release & Compliance + +```mermaid +flowchart TD + REL["release"] -->|pins| TS["tech_stack\n(versions locked)"] + TS -->|includes| LV["library_version[]"] + LV -->|license| LIC["license info"] + LIC -->|checked by| CC["compliance_check"] + TS -->|scanned into| SBOM["sbom\n(bill of materials)"] + SBOM -->|input to| SR["security_review\n→ document"] +``` + +### Domain 10 — Operations / Incidents + +``` +cf.studio.core.incident.v1~ +cf.studio.core.alert.v1~ +cf.studio.core.runbook.v1~ // → document +cf.studio.core.postmortem.v1~ // → document +cf.studio.core.slo.v1~ // Service Level Objective +cf.studio.core.sli.v1~ // Service Level Indicator +cf.studio.core.on_call_schedule.v1~ +cf.studio.core.escalation_policy.v1~ +cf.studio.core.health_check.v1~ +cf.studio.core.metric_definition.v1~ // metric schema/definition, not time-series data +cf.studio.core.quality_metric.v1~ // code quality, test coverage metrics +``` + +### D24 — Incident & Operations Cross-References + +```mermaid +flowchart LR + ALERT["alert"] -->|escalates to| INC["incident"] + INC -->|assigned via| ESC["escalation_policy"] + ESC -->|references| OCS["on_call_schedule"] + OCS -->|assigns| PER["person"] + INC -->|produces| PM["postmortem\n→ document"] + PM -->|creates| TASK["task\n(prevention)"] +``` + +### Domain 11 — Security + +``` +cf.studio.core.vulnerability.v1~ +cf.studio.core.cve.v1~ +cf.studio.core.security_finding.v1~ // pentest, code scan, secret scan +cf.studio.core.threat_model.v1~ // → document +cf.studio.core.security_review.v1~ // → document +cf.studio.core.dependency_vulnerability.v1~ // Dependabot, Snyk +``` + +### D17 — Security & Vulnerability Objects (type hierarchy) + +```mermaid +classDiagram + class vulnerability { + severity: critical|high|medium|low + cveId: string? + state: open|fixed|ignored + } + class cve { + cvssScore: float + description: string + } + class security_finding { + source: pentest|code_scan|secret_scan + severity: string + } + class dependency_vulnerability { + packageName: string + affectedVersions: string[] + fixedVersion: string? + } + class compliance_check { + standard: string + control: string + } + class compliance_check_result { + checkId: ref compliance_check + state: pass|fail|skip + } + + vulnerability --> cve : references + dependency_vulnerability --|> vulnerability + security_finding --|> vulnerability + compliance_check "1" --> "many" compliance_check_result +``` + +### D25 — Security Cross-References + +```mermaid +flowchart LR + SF["source_file"] -->|contains| DV["dependency_vulnerability"] + DV -->|references| CVE["cve"] + CVE -->|details in| VUL["vulnerability"] + VUL -->|found by| SR["security_finding"] + VUL -->|remediated by| TASK["task"] + SR -->|reported in| SREP["security_review\n→ document"] +``` + +### D42 — Library Version ↔ Security + +```mermaid +flowchart LR + LV["library_version\n(lodash 4.17.20)"] -->|has| DV["dependency_vulnerability"] + DV -->|references| CVE["cve\n(CVE-2021-23337)"] + CVE -->|severity| SEV["critical / high / medium"] + DV -->|fixed in| FLV["library_version\n(lodash 4.17.21)"] + FLV -->|upgrade via| TASK["task\n(remediation)"] +``` + +### Domain 12 — Compliance / Governance + +``` +cf.studio.core.audit_finding.v1~ +cf.studio.core.compliance_check.v1~ +cf.studio.core.compliance_check_result.v1~ +cf.studio.core.policy_exception.v1~ +cf.studio.core.compliance_report.v1~ // → document +cf.studio.core.data_erasure_request.v1~ // GDPR right-to-erasure tracking + // strategy: anonymize | delete + // anonymize = replace PII with [redacted] +cf.studio.core.cost_report.v1~ // AI cost aggregated report (see schema below) +``` + +``` +CostReport extends Object { + typeId: gts.cf.studio.core.object.v1~cf.studio.core.cost_report.v1~ + tenantId: ref → Tenant + period: { + from: datetime + to: datetime + grain: day | week | month + } + totalCostUSD: float + breakdown: [ + { + workerId?: ref → Worker + category?: string // Worker metadata.category + modelId?: GTS Type ID // Gears Models Registry ref + runCount: int + totalCostUSD: float + avgCostUSD: float + } + ] + costPerAcceptedChange?: float // totalCost / merged pull_requests in period + generatedAt: datetime + // materialized from Gears Usage Collector by ai_cost_efficiency_analysis Analyzer +} +``` + +### Domain 13 — People / Teams + +``` +cf.studio.core.person.v1~ +cf.studio.core.team.v1~ +cf.studio.core.org_unit.v1~ // department, division +``` + +### D34 — Component ↔ People & Teams + +```mermaid +classDiagram + class component { + ownerId: ref team + kind: service|library|module + } + class team { + name: string + } + class person { + userId: ref User + } + class on_call_schedule { + teamId: ref team + } + class role { + name: string + } + + component --> team : owned by + team "1" --> "many" person : members + team --> on_call_schedule : on-call + person --> role : has +``` + +### Domain 14 — Infrastructure + +``` +cf.studio.core.environment.v1~ // dev, staging, prod +cf.studio.core.service.v1~ // microservice, cloud service +cf.studio.core.cluster.v1~ // K8s, ECS, EKS +cf.studio.core.resource.v1~ // generic cloud resource +cf.studio.core.namespace.v1~ // K8s namespace, logical grouping +cf.studio.core.secret_reference.v1~ // reference only: name, vault_path, provider — no value stored +cf.studio.core.certificate.v1~ +cf.studio.core.infra_config.v1~ // base (abstract) + // narrowed by Kit: + // ~cf.studio.core.terraform_resource.v1~ + // ~cf.studio.core.helm_release.v1~ + // ~cf.studio.core.k8s_manifest.v1~ +``` + +### D14 — Infrastructure Config Hierarchy + +```mermaid +classDiagram + class infra_config { + environment: ref environment + version: string + } + + infra_config <|-- terraform_resource + infra_config <|-- helm_release + infra_config <|-- k8s_manifest +``` + +### Domain 15 — Documents + +``` +cf.studio.core.document.v1~ // base (abstract) + // narrowed types: + cf.studio.core.spec.v1~ // → document + cf.studio.core.guide.v1~ // → document + cf.studio.core.readme.v1~ // → document + cf.studio.core.wiki_page.v1~ // → document + cf.studio.core.api_documentation.v1~ // → document + cf.studio.core.glossary.v1~ // → document + // policy/governance docs use document with category tag +``` + +### D11 — Document Type Hierarchy + +```mermaid +classDiagram + class document { + content: string + version: semver + ownerId: ref User + } + + document <|-- spec + document <|-- guide + document <|-- readme + document <|-- wiki_page + document <|-- api_documentation + document <|-- prd + document <|-- adr +``` + +### D12 — Document Type Hierarchy (continued) + +```mermaid +classDiagram + class document + + document <|-- design + document <|-- feature_spec + document <|-- decomposition + document <|-- runbook + document <|-- postmortem + document <|-- release_notes + document <|-- meeting_note +``` + +### Domain 16 — AI / Agents + +``` +cf.studio.core.prompt.v1~ // base (abstract) + cf.studio.core.skill.v1~ // → prompt (reusable agent instruction) + cf.studio.core.system_prompt.v1~ // → prompt + cf.studio.core.prompt_template.v1~ // → prompt + cf.studio.core.prompt_variant.v1~ // → prompt (A/B variant) +cf.studio.core.ai_agent.v1~ +cf.studio.core.ai_tool.v1~ +cf.studio.core.evaluation_run.v1~ +cf.studio.core.evaluation_result.v1~ +cf.studio.core.benchmark_sample.v1~ // human-approved WorkerRun example for World Model training + // feeds fine-tuning via Gears Model Runtime Controller +// llm_model → reference to Gears Models Registry (no separate Object type) +``` + +### D13 — Prompt Type Hierarchy + +```mermaid +classDiagram + class prompt { + content: string + version: semver + } + + prompt <|-- skill + prompt <|-- system_prompt + prompt <|-- prompt_template + prompt <|-- prompt_variant +``` + +--- + +### Domain 19 — Validation & Evidence + +``` +cf.studio.core.validation_session.v1~ // aggregates retry loop for one Validator run + // on one Object: retryCount, state, runs[] +cf.studio.core.validation_result.v1~ // output of one Validator WorkerRun + // state: pass|fail|superseded|revoked +cf.studio.core.evidence.v1~ // structured proof of action/validation + // state: valid|superseded|revoked + // produced by Worker output Contract +``` + +--- + +### Domain 19a — Traceability + +``` +cf.studio.core.traceability_report.v1~ // aggregated requirement coverage analysis + // output of traceability_analysis Analyzer Worker +``` + +``` +TraceabilityReport extends Object { + typeId: gts.cf.studio.core.object.v1~cf.studio.core.traceability_report.v1~ + workspaceId: ref → Workspace + sourceRunId: ref → WorkerRun // traceability_analysis Analyzer run + generatedAt: datetime + coverage: { + requirements: { + total: int + withDesign: int // have design ref + withTasks: int // have task[] + withTests: int // have test_case[] + withPRs: int // have merged pull_request[] + fullyTraced: int // all four layers present + coveragePct: float // fullyTraced / total + } + } + staleLinks: [ + { + sourceId: ref → Object // requirement or design that changed + targetId: ref → Object // linked artifact now stale + sourceUpdatedAt: datetime + staleSince: datetime + } + ] + gaps: [ // Recommendation[] created per gap + { + objectId: ref → Object + missingLayers: string[] // e.g. ["test_case", "pull_request"] + } + ] + allCriticalRequirementsTraced: boolean // compliance gate +} +``` + +--- + +### Domain 20 — Outbound Event Subscriptions + +``` +cf.studio.core.event_subscription.v1~ // external webhook/event-bus subscription + // format: cloudevents (default) | raw + // state: active | paused | failed +``` + +``` +EventSubscription extends Object { + typeId: gts.cf.studio.core.object.v1~cf.studio.core.event_subscription.v1~ + name: string + filter: { + eventPattern: GTS Type pattern // e.g. gts.cf.core.events.type.v1~cf.studio.core.* + objectPattern?: GTS Type pattern // optional: filter by Object type that triggered event + } + delivery: { + kind: webhook | event_bus + endpoint?: string // HTTPS URL (kind: webhook) + secret?: ref requiredSettings // HMAC signing secret + sinkRef?: string // Gears sink ID (kind: event_bus) + } + format: cloudevents | gts_native // default: cloudevents + state: active | paused | failed + retryPolicy: { + maxRetries: int // default: 3 + backoff: linear | exponential + } +} +``` + +// gts_native = raw GTS event JSON without CloudEvents envelope +// (for Tenants already consuming Gears Events Broker directly) + +CloudEvents envelope (when format: cloudevents): +```json +{ + "specversion": "1.0", + "type": "gts.cf.core.events.type.v1~cf.studio.core.worker_run_completed.v1~", + "source": "https://studio.cf/tenants/{tenantId}", + "id": "{workerRunId}", + "time": "...", + "data": { } +} +``` + +--- + +### Domain 21 — Worker Interactions + +``` +cf.studio.core.worker_interaction.v1~ // interactive exchange between Worker and user + // kind: input_request | menu | free_form_intent + // state: pending | answered | timed_out | cancelled + // max 1 pending per WorkerRun at any time +``` + +``` +WorkerInteraction extends Object { + typeId: gts.cf.studio.core.object.v1~cf.studio.core.worker_interaction.v1~ + workerRunId: ref → WorkerRun + kind: input_request | menu | free_form_intent + prompt: string // what the Worker is asking + context?: string // why it is asking (LLM reasoning context) + options?: [ // kind: menu only + { value: string, label: string, description?: string } + ] + inputSchema?: Contract // kind: input_request — validates response + requiredRole?: RolePattern // who may answer; null = any authorized user + response?: any // filled by user + state: pending | answered | timed_out | cancelled + expiresAt?: datetime + timeoutAction: continue | abort | escalate // default: abort +} +``` + +--- + +### Notes + +- **Dashboard** — implemented in Constructor Fabric Insight, not Studio. +- **Business/Strategy domain** (`market_research`, `opportunity`, `business_case`) — separate Kit (Phase 4+). +- **`function`, `type_definition`, `code_dependency`** — IDE/static analysis concern, not Studio core. +- **`llm_model`** — reference to Gears Models Registry by GTS ID. +- **`metric_definition`** defines what is measured; actual time-series data lives in Insight/Datadog/Prometheus. +- **`secret_reference`** stores only the reference (name, path, provider) — never the secret value. + +--- + +### Vendor Kit Extension Examples + +``` +// Jira Kit +gts.cf.studio.core.object.v1~cf.studio.core.task.v1~jira.studio.core.jira_issue.v1~ +gts.cf.studio.core.object.v1~cf.studio.core.bug.v1~jira.studio.core.jira_bug.v1~ +gts.cf.studio.core.object.v1~cf.studio.core.epic.v1~jira.studio.core.jira_epic.v1~ + +// GitHub Kit +gts.cf.studio.core.object.v1~cf.studio.core.pull_request.v1~github.studio.core.github_pr.v1~ +gts.cf.studio.core.object.v1~cf.studio.core.pipeline_run.v1~github.studio.core.actions_run.v1~ +gts.cf.studio.core.object.v1~cf.studio.core.vulnerability.v1~github.studio.core.dependabot_alert.v1~ + +// GitLab Kit +gts.cf.studio.core.object.v1~cf.studio.core.pull_request.v1~gitlab.studio.core.merge_request.v1~ +gts.cf.studio.core.object.v1~cf.studio.core.pipeline_run.v1~gitlab.studio.core.gitlab_pipeline.v1~ + +// Jenkins Kit +gts.cf.studio.core.object.v1~cf.studio.core.build.v1~jenkins.studio.core.jenkins_build.v1~ +gts.cf.studio.core.object.v1~cf.studio.core.pipeline_job.v1~jenkins.studio.core.jenkins_job.v1~ + +// Kubernetes Kit +gts.cf.studio.core.object.v1~cf.studio.core.infra_config.v1~k8s.studio.core.k8s_manifest.v1~ +gts.cf.studio.core.object.v1~cf.studio.core.service.v1~k8s.studio.core.k8s_service.v1~ +gts.cf.studio.core.object.v1~cf.studio.core.cluster.v1~k8s.studio.core.k8s_cluster.v1~ + +// PagerDuty Kit +gts.cf.studio.core.object.v1~cf.studio.core.incident.v1~pagerduty.studio.core.pd_incident.v1~ +gts.cf.studio.core.object.v1~cf.studio.core.alert.v1~pagerduty.studio.core.pd_alert.v1~ + +// Datadog Kit +gts.cf.studio.core.object.v1~cf.studio.core.alert.v1~datadog.studio.core.dd_monitor.v1~ +gts.cf.studio.core.object.v1~cf.studio.core.incident.v1~datadog.studio.core.dd_incident.v1~ +gts.cf.studio.core.object.v1~cf.studio.core.metric_definition.v1~datadog.studio.core.dd_metric.v1~ + +// Snyk Kit +gts.cf.studio.core.object.v1~cf.studio.core.vulnerability.v1~snyk.studio.core.snyk_issue.v1~ + +// Confluence Kit +gts.cf.studio.core.object.v1~cf.studio.core.wiki_page.v1~confluence.studio.core.confluence_page.v1~ +``` + +--- + +*Generated during Studio v2 Domain Model brainstorm session.* +*Date: 2026-07-02* diff --git a/v2/docs/user-journeys.md b/v2/docs/user-journeys.md new file mode 100644 index 00000000..90dab8e4 --- /dev/null +++ b/v2/docs/user-journeys.md @@ -0,0 +1,1817 @@ +# Studio v2 — User Journeys + +## Introduction + +This document describes the twenty-two primary cross-cutting user journeys in Studio v2. +Each journey traces the full path a user takes from intent to outcome, showing which +Objects, Workers, Flows, Validators, Connectors, and WorkerInteractions are involved. + +**How to read ALGORITHM blocks** + +Each block follows a fixed schema: + +- `ACTOR` — the role that initiates the journey +- `GOAL` — the outcome they are trying to reach +- `INPUTS` — what must already exist before the journey begins; `[sync: name]` marks + Objects synced from external systems via Connectors +- `OUTPUTS` — what is produced when the journey ends; `[write-back: name]` marks + Objects written back to external systems +- `COST TIER` — approximate AI cost: `low` (script only), `medium` (hybrid Workers), + `high` (chain of 2+ LLM Workers) +- `AUTOMATION GATE` — `none` (readonly or Validator-only; any automationLevel) or + `approved_automation` (action Workers; requires `automationLevel >= approved_automation + AND category in approvedWorkerCategories`) +- `STEPS` — the ordered sequence of actions, Workers, Flows, and Validator gates invoked +- `DECISION_POINTS` — named forks where the user or Studio chooses a path +- `GUARDS` — invariants that must hold throughout; violation halts the journey +- `NEXT` — optional handoff to a downstream journey or external process + +**Studio v2 architecture note** + +Studio v2 is Object- and Worker-centric. Objects live in the shadow SDLC graph. Workers +consume and produce Objects. Flows add mandatory-step constraints over Workers. Connectors +sync Objects from external systems (via Gears OAGW). Action Workers write back to external +systems through `WriteBackPolicy`. Validators run regardless of `automationLevel`; action +Workers require `approved_automation`. WorkerInteractions pause a WorkerRun mid-run and +resume on user response. Evidence is immutable proof attached to Objects. + +--- + +## Journey Index + +| # | Journey | Actor | Goal | Workers / Flows / Validators | Cost Tier | Automation Gate | +|---|---------|-------|------|------------------------------|-----------|-----------------| +| 1 | Plan and Implement a Feature | Developer | decompose intent → code → PR with traceability | `decompose_feature_worker` → `implement_code_worker` → `create_pr_worker` + `pr_design_validator` | high | approved_automation | +| 2 | Onboard a Project to Studio v2 | Tech Lead / DevOps | Kit install + Connector setup + Workspace config | Kit install + Connector setup + WorkerInteraction (menu) | low | approved_automation | +| 3 | Explore Design Options and Author an ADR | Architect / Tech Lead | WorkerInteraction free_form_intent → `create_adr_worker` → adr Object | `object_graph_retriever` + `create_adr_worker` | medium | approved_automation | +| 4 | Review and Fix Code via PR Validator | Developer / Reviewer | `pr_design_validator` findings → WorkerInteraction (menu) per finding → fix PR | `pr_design_validator` + `implement_code_worker` + `create_pr_worker` | high | approved_automation | +| 5 | Create and Publish a Kit | Platform Engineer | Kit manifest authoring + Kit Registry publish | Kit manifest authoring + WorkerInteraction (menu) | low | approved_automation | +| 6 | Generate Project Documentation | Technical Writer / Developer | `document_retriever` → `create_design_worker` (docs variant) → ValidationSession | `document_retriever` + `create_design_worker` + `gap_analysis_validator` | high | approved_automation | +| 7 | Author a PRD | Product Manager | `create_prd_worker` → prd Object + `gap_analysis_validator` | `create_prd_worker` + `gap_analysis_validator` | high | approved_automation | +| 8 | Record an Architecture Decision | Architect / Tech Lead | `create_adr_worker` → adr Object + ValidationSession | `create_adr_worker` + `pr_design_validator` | medium | approved_automation | +| 9 | Author a System Design | Architect / Tech Lead | `create_design_worker` → design Object + `gap_analysis_validator` | `create_design_worker` + `gap_analysis_validator` | high | approved_automation | +| 10 | Decompose Design into Tasks | Tech Lead / PM | `decompose_feature_worker` → decomposition + task[] [write-back: jira] | `decompose_feature_worker` + `gap_analysis_validator` | high | approved_automation | +| 11 | Author a Feature Specification | Tech Lead / Developer | `create_feature_spec_worker` → feature_spec Object + ValidationSession | `create_feature_spec_worker` + `gap_analysis_validator` | high | approved_automation | +| 12 | Implement a Feature with Traceability | Developer | `implement_code_worker` → source_file[] + `create_pr_worker` + `pr_design_validator` | `implement_code_worker` + `create_pr_worker` + `pr_design_validator` | high | approved_automation | +| 13 | Analyze Change Impact | Tech Lead / PM / Release Manager | `traceability_analysis` + `stale_artifact_detection` → impact report | `traceability_analysis` + `stale_artifact_detection` | medium | none | +| 14 | Review a Pull Request | Tech Lead / Reviewer | `pr_design_validator` + `security_impact_analysis` + `gap_analysis` → findings | `pr_design_validator` + `security_impact_analysis` + `gap_analysis` | medium | none | +| 15 | Reconstruct SDLC Artifacts from Code | Tech Lead / Architect | `reverse_engineer_worker` reading `code_retriever` output → SDLC Objects | `code_retriever` + `reverse_engineer_worker` | high | approved_automation | +| 16 | Full SDLC Pipeline End-to-End | PM, Architect, Developer | All Workers in PRD → ADR → DESIGN → DECOMPOSITION → FEATURE → CODE order | all SDLC Workers in sequence | high | approved_automation | +| 17 | Release Readiness Estimation | Release Manager / Tech Lead | `traceability_analysis` + `release_readiness_review` Flow → Approval gate | `traceability_analysis` + `release_readiness_review` Flow | medium | none | +| 18 | PR Status Monitoring | Team Lead / PM / Release Manager | Connector sync (GitHub) + status Analyzer Worker → status report | `traceability_analysis` + Connector GitHub sync | low | none | +| 19 | Traceability Coverage Gate in CI | Tech Lead / Developer / DevOps | `traceability_analysis` Analyzer + CI Connector → coverage gate | `traceability_analysis` + CI Connector | low | none | +| 20 | Cross-Workspace Traceability Navigation | Tech Lead / Architect | Workspace Object + `object_graph_retriever` scoped to workspace | `object_graph_retriever` + `traceability_analysis` | low | none | +| 21 | Interactive Kit Update | Developer / Tech Lead | Kit version check + WorkerInteraction (menu) per changed file | Kit version check + WorkerInteraction (menu) | low | approved_automation | +| 22 | Object Graph Navigation | Developer / Architect | `object_graph_retriever` + `traceability_analysis` before making a change | `object_graph_retriever` + `traceability_analysis` | low | none | + +--- + +## Journeys + +### Journey 1: Plan and Implement a Feature + +```text +ALGORITHM PlanAndImplementFeature + ACTOR: Developer + GOAL: Deliver a working, reviewed, and write-back PR implementing a + feature, with optional upfront exploration, design decomposition, + and automatic design conformance validation + INPUTS: [ + Feature intent described (natural language or task Object), + feature_spec (optional; linked to task), + design[] — for conformance check, + repository [sync: github], + workspace configured with approved Kit + ] + OUTPUTS: [ + decomposition + task[] (if planning phase executed), + source_file[] — implementation with traceability markers, + pull_request (state: review) [write-back: github], + ValidationSession (pr_design_validator) + Evidence + ] + COST TIER: high (decompose_feature_worker llm + implement_code_worker llm + + create_pr_worker hybrid) + AUTOMATION GATE: approved_automation + STEPS: + 1. DECISION: Explore context first? + YES (target area unclear): + invoke object_graph_retriever (workspace scope): + Input: feature intent as query + Output: relevant Objects (design, feature_spec, component refs) + WorkerRun created; state: pending → running → done + Worker requests clarification: + WorkerInteraction (kind: free_form_intent) created + WorkerRun.state → awaiting_input + Developer scopes intent → WorkerRun resumes + NO (target known): skip to step 2. + 2. DECISION: Plan first? + YES (feature spans multiple components or is ambiguous): + invoke decompose_feature_worker (llm, on_demand): + Input: feature intent, design[] (from graph/chain) + Output: decomposition + task[] + WorkerRun created; state: pending → running → done + Worker requests clarification (scope/ordering): + WorkerInteraction (kind: menu) created + Developer selects ordering strategy (dependency/risk/value) + WorkerRun resumes + gap_analysis_validator fires (realtime): + ValidationSession created + On pass: Evidence attached to decomposition + On fail (within maxRetries): WorkerInteraction for gap resolution + NO (single-scope, feature_spec already exists): skip to step 3. + 3. DECISION: automationLevel dial? + WorkerInteraction (kind: menu) at Flow start: + Options: [recommended_automation, approved_automation, enterprise] + Developer selects → FlowRun.automationLevel set for this run + 4. invoke implement_code_worker (llm, on_demand): + Input: feature_spec or task, design[] (from Worker.inputBindings: + source graph/chain) + Output: source_file[] with traceability markers + WorkerRun created; state: pending → running → done + If clarification needed mid-run: + WorkerInteraction (kind: input_request) created + WorkerRun.state → awaiting_input + Developer responds → WorkerRun resumes + 5. invoke create_pr_worker (hybrid, on_demand): + Input: source_file[], branch + Output: pull_request [write-back: github] + pull_request.implementsRequirements populated from feature_spec IDs + Connector write-back via [write-back: github]: + Gate 2 check: WriteBackPolicy.requiresApproval + If true: Approval Object created; developer/lead approves + If approved: connector_outbound_sync_worker executes + 6. pr_design_validator fires automatically (realtime, onEvent: PR → review): + ValidationSession created + Input: pull_request, design[], acceptance_criteria[] + On pass: Evidence attached to pull_request; PR ready for review + On fail (within maxRetries): WorkerInteraction (kind: menu) with + options per finding; developer amends source_file[]; loop repeats + On fail (retries exhausted): Approval (kind: risk_acceptance) created + 7. DECISION: Cancel Worker at any step? + YES: cancel(workerRunId, cascade: true) → WorkerRun.state: aborted + NO: continue + DECISION_POINTS: + - ExploreFirst: skip (target known) / run object_graph_retriever (unclear) + - PlanFirst: skip (single-scope) / run decompose_feature_worker (multi-step) + - AutomationLevel: WorkerInteraction (kind: menu) at Flow start + - WriteBackApproval: Gate 2 (github write-back) per Tenant policy + - ConformanceResult: pass immediately / fail-and-fix loop / escalate + GUARDS: [ + automationLevel >= approved_automation for implement_code_worker, + create_pr_worker, and decompose_feature_worker, + decomposition must be reviewed (WorkerInteraction resolved) before + implement_code_worker is invoked on any derived task, + pr_design_validator Evidence must be attached to pull_request before + it can advance to state: approved, + source_file traceability markers must reference IDs from feature_spec, + Gate 2 (WriteBackPolicy) must be satisfied before github write-back + ] + NEXT: Journey 13 (change impact) or Journey 17 (release readiness) + after PR is merged +``` + +--- + +### Journey 2: Onboard a Project to Studio v2 + +```text +ALGORITHM OnboardProjectToStudioV2 + ACTOR: Tech Lead or DevOps engineer + GOAL: Bring an existing codebase under Studio v2 governance by installing + a Kit, configuring Connectors, setting up Workspace, and declaring + Tenant.approvedWorkerCategories + INPUTS: [ + Existing source repository accessible on disk, + User has write access to repository root and Studio Tenant admin rights, + Optional: Kit Registry URL + Kit identifier to install + ] + OUTPUTS: [ + .bootstrap/ directory (cf-studio-path) populated with Studio config, + Kit installed and validated, + Connector(s) configured (GitHub, Jira, etc.), + Workspace Object created with registered sources, + Tenant.approvedWorkerCategories declared, + automationLevel set (default: recommendations) + ] + COST TIER: low (script Workers + WorkerInteraction menu; no LLM Workers required) + AUTOMATION GATE: approved_automation (Kit install + Connector setup write to graph) + STEPS: + 1. Tech Lead initializes Studio v2 in the repository root. + Studio creates the .bootstrap/ scaffold and reads any existing + configuration fragments. WorkerRun created for init Worker. + 2. DECISION: Kit to install? + WorkerInteraction (kind: menu) created: + Options: [install from Kit Registry, install from local path, + install from GitHub ref, skip (configure manually)] + Tech Lead selects → WorkerRun resumes + 3. Kit install Worker executes: + Input: Kit Registry reference or local path + Output: Kit installed; Worker[], Flow[], Connector[] templates available + WorkerRun created; state: pending → running → done + DECISION: Per-file conflicts? + For each file that would be overwritten: + WorkerInteraction (kind: menu) per file: + Options: [accept upstream, keep existing, diff and decide] + WorkerRun resumes after all per-file decisions resolved + 4. Kit validation Worker runs (script, realtime): + Checks manifest schema, resolves all declared component references, + confirms no dangling dependencies + ValidationSession created + On fail: WorkerInteraction (kind: input_request) for gap resolution + On pass: Evidence attached to Kit install WorkerRun + 5. Connector setup per external system: + For each system (GitHub, Jira, etc.) identified: + WorkerInteraction (kind: menu) created: + Options: [configure now, skip (configure later)] + If configure now: + connector_inbound_sync_worker template instantiated; + FieldMappings declared; syncProtocol (push/pull) set; + WriteBackPolicy.requiresApproval set per Tenant policy + 6. Workspace Object created: + registered sources: [current repo + any cross-repo refs] + object_graph_retriever scoped to workspace + DECISION: Multi-repo workspace? + YES: additional sources registered; cross-repo traceability enabled + NO: single-repo workspace finalized + 7. Tenant.approvedWorkerCategories declared: + WorkerInteraction (kind: menu): + Options: [sdlc, coding, security, ops, all] + Tech Lead selects approved categories + automationLevel set (default: recommendations; raise via Journey 8 + once team is comfortable) + 8. Onboarding complete: all Workers in approved categories available; + Connectors syncing; Workspace queries resolving. + DECISION_POINTS: + - KitSource: Registry / local path / GitHub ref / skip + - PerFileConflict: accept upstream / keep existing / diff and decide + - ConnectorSetup: configure now / skip per system + - MultiRepoWorkspace: yes (add sources) / no (single repo) + - ApprovedCategories: WorkerInteraction (kind: menu) selection + GUARDS: [ + Kit validation (ValidationSession) must pass before any Kit Worker + can be invoked in the project, + Connector FieldMappings must not map external fields to Object.id + or Object.tenantId, + Tenant.approvedWorkerCategories must be non-empty before action Workers + can execute, + automationLevel defaults to recommendations; raising requires Journey 8, + Per-file conflict WorkerInteractions must all resolve before Kit install + WorkerRun reaches state: done + ] + NEXT: Project ready for day-to-day v2 journeys (1, 3, 7, 9, 12) +``` + +--- + +### Journey 3: Explore Design Options and Author an ADR + +```text +ALGORITHM ExploreDesignOptionsAndAuthorADR + ACTOR: Architect or Tech Lead + GOAL: Explore design options via free-form WorkerInteraction, produce a + structured decision summary, and author a persisted adr Object + grounded in that exploration + INPUTS: [ + ADR topic or decision question stated by the user, + design[] (optional; for cross-reference), + adr[] (optional; existing ADRs for context), + workspace configured + ] + OUTPUTS: [ + adr Object (state: draft → approved) with decision, options, consequences, + ValidationSession + Evidence (adr_structure_validator), + WorkerRun audit trail + ] + COST TIER: medium (object_graph_retriever hybrid + create_adr_worker llm) + AUTOMATION GATE: approved_automation + STEPS: + 1. Architect describes the ADR topic. + WorkerInteraction (kind: free_form_intent) created: + WorkerRun.state → awaiting_input + Architect elaborates: decision drivers, constraints, alternatives, + stakeholder concerns, any prior ADR context + WorkerRun resumes with enriched intent + 2. invoke object_graph_retriever (workspace scope, hybrid, on_demand): + Input: ADR topic query + Output: relevant Objects — existing design[], adr[], component refs + WorkerRun created; state: pending → running → done + DECISION: Explore further? + YES: WorkerInteraction (kind: free_form_intent) for additional scoping + (e.g., add competing options, constrain scope) + NO: proceed to step 3 with retrieved context + 3. invoke create_adr_worker (llm, on_demand): + Input: ADR topic, retrieved context (design[], adr[]), + free_form_intent output (from Worker.inputBindings: source user) + Output: adr Object (state: draft) containing: + Context and Problem Statement, + Decision Drivers, + Considered Options (≥ 2) with pros/cons, + Decision Outcome with rationale, + Consequences (positive, negative, neutral), + Object ID assigned + WorkerRun created; state: pending → running → done + If clarification needed mid-run: + WorkerInteraction (kind: input_request) created + WorkerRun.state → awaiting_input + Architect responds → WorkerRun resumes + 4. adr_structure_validator fires (realtime | on_demand): + ValidationSession created + On pass: Evidence attached to adr Object + On fail (within maxRetries): WorkerInteraction (kind: menu) with + options per structural gap; Architect resolves; validator retries + On fail (retries exhausted): Approval (kind: risk_acceptance) created + 5. DECISION: adr acceptable? + YES: adr.state → approved (StatePolicy transition; requires Evidence + from adr_structure_validator) + NO: Architect edits adr directly; re-runs create_adr_worker with + amended intent; validator re-fires + 6. DECISION: Cross-reference in design Object? + YES: object_graph_retriever locates parent design; + Architect adds adr Object ref to design.architectureDrivers + NO: adr remains standalone + DECISION_POINTS: + - ExploreDepth: single retrieval / additional free_form_intent rounds + - AdrAcceptance: approve as-is / re-run with amendments + - CrossReference: register in design / standalone + GUARDS: [ + free_form_intent WorkerInteraction must resolve before create_adr_worker + is invoked — intent must be explicit, + adr Object must contain at least two considered options before + ValidationSession can pass, + adr_structure_validator Evidence must be attached before adr.state + can advance to approved, + adr Object ID must be unique within the Tenant namespace + ] + NEXT: Journey 9 (Author System Design referencing this ADR) +``` + +--- + +### Journey 4: Review and Fix Code via PR Validator + +```text +ALGORITHM ReviewAndFixCodeViaPRValidator + ACTOR: Developer or Reviewer + GOAL: Systematically identify issues in a PR via pr_design_validator, + obtain per-finding approval via WorkerInteraction, apply targeted + fixes, and produce a clean PR with Evidence + INPUTS: [ + pull_request (state: review) [sync: github], + design[] — linked via pull_request.conformsToDesign refs, + feature_spec or acceptance_criteria[] — from task/feature_spec, + repository [sync: github] + ] + OUTPUTS: [ + ValidationSession (state: pass) + Evidence attached to pull_request, + source_file[] — fixed implementation, + pull_request (state: review, updated) [write-back: github], + WorkerRun audit trail per fix applied + ] + COST TIER: high (pr_design_validator hybrid + implement_code_worker llm + + create_pr_worker hybrid) + AUTOMATION GATE: approved_automation (fix Workers); none (Validator only) + STEPS: + 1. invoke object_graph_retriever scoped to PR target area (hybrid, on_demand): + Input: pull_request + workspace + Output: relevant design[], component[], feature_spec Objects + WorkerRun created; state: pending → running → done + 2. pr_design_validator fires (realtime | on_demand): + ValidationSession created + Input: pull_request diff, design[], acceptance_criteria[] + Output: ValidationResult with structured findings list + (severity: critical | major | minor | info per finding) + WorkerRun created; state: pending → running → done + 3. DECISION: Conformance result? + PASS: Evidence attached to pull_request; proceed to step 6. + FAIL: findings list surfaced; proceed to step 4. + 4. Per-finding WorkerInteraction (kind: menu) for each finding: + WorkerRun.state → awaiting_input + For each finding: Options: [fix, skip, accept risk] + fix: finding queued for implement_code_worker + skip: finding dismissed; reason recorded + accept risk: Approval (kind: risk_acceptance) created + WorkerRun resumes after all findings reviewed + 5. For each finding approved for fix: + invoke implement_code_worker (llm, on_demand): + Input: finding (location, description), source_file[], feature_spec + Output: source_file[] (amended) + WorkerRun created; state: pending → running → done + invoke create_pr_worker (hybrid, on_demand) to update PR: + Input: source_file[], existing pull_request branch + Output: pull_request (updated) [write-back: github] + Gate 2: WriteBackPolicy.requiresApproval checked + pr_design_validator re-fires on updated PR (step 2 loop) + 6. All risk_acceptance Approvals resolved (approved or rejected): + ValidationSession state → pass (all approved) | escalated (any rejected) + Evidence attached to pull_request + 7. DECISION: Cancel any Worker mid-run? + YES: cancel(workerRunId, cascade: true) → WorkerRun.state: aborted + NO: continue + DECISION_POINTS: + - ConformanceResult: pass / fail (proceed to findings) + - PerFindingDecision: fix / skip / accept risk (WorkerInteraction per finding) + - WriteBackApproval: Gate 2 (github write-back) per Tenant policy + - EscalationDecision: approve exception / reject PR + GUARDS: [ + object_graph_retriever must complete before pr_design_validator fires, + implement_code_worker may only touch locations referenced by approved + findings — no out-of-scope edits, + Each risk_acceptance Approval must be resolved before ValidationSession + can close, + pr_design_validator re-fires on every push to the PR branch; no skipping, + Evidence is immutable once attached; revocation requires explicit + revokedBy + revokedAt + ] + NEXT: Journey 17 (release readiness) after PR merged +``` + +--- + +### Journey 5: Create and Publish a Kit + +```text +ALGORITHM CreateAndPublishKit + ACTOR: Platform Engineer + GOAL: Package reusable Studio v2 behaviors (Workers, Flows, Connectors, + GTS types) into a validated Kit, publish to Kit Registry, and + install in one or more consumer Tenants + INPUTS: [ + Kit source directory with Worker definitions, Flow definitions, + Connector templates, GTS type schemas, and rule files, + Optional: existing .cf-studio-kit.toml for update scenario, + Kit Registry credentials + ] + OUTPUTS: [ + Validated Kit artifact with .cf-studio-kit.toml manifest, + Workers, Flows, Connectors, GTS types registered in Kit Registry, + Consumer Tenant Kit install confirmed + ValidationSession Evidence + ] + COST TIER: low (script Workers + WorkerInteraction menu; manifest authoring) + AUTOMATION GATE: approved_automation + STEPS: + 1. Platform Engineer invokes Kit manifest authoring Worker: + Worker scans source directory; identifies all candidate: + Worker definitions, Flow definitions, Connector templates, + GTS type schemas, WorkerImplementation configs + WorkerRun created; state: pending → running → done + 2. DECISION: Kit target path? + WorkerInteraction (kind: menu) created: + Options: [current directory, custom path] + Platform Engineer selects → WorkerRun resumes + 3. Manifest proposal generated: + Worker produces proposed .cf-studio-kit.toml listing all + discovered components with metadata (name, version, dependencies, + exposed entry points, GTS type IDs) + WorkerInteraction (kind: menu): + Options: [approve default, show preview, edit interactively, + rerun discovery, cancel] + Platform Engineer selects → WorkerRun resumes + 4. DECISION: Edit manifest? + YES (edit interactively): WorkerInteraction (kind: input_request) + for each section; Platform Engineer adjusts components, + versions, dependencies + NO (approve default or show preview confirmed): proceed to step 5 + 5. Kit validation Worker runs (script, realtime): + Checks: manifest schema, all declared component references + resolve, no dangling GTS type dependencies, Worker contracts + reference only registered GTS types + ValidationSession created + On pass: Evidence attached to Kit manifest WorkerRun + On fail: WorkerInteraction (kind: input_request) for gap resolution; + manifest edited; validation re-runs + 6. Kit publish to Registry: + connector_outbound_sync_worker executes (write-back: Kit Registry) + Gate 2: WriteBackPolicy.requiresApproval checked for registry write + If approved: Kit registered with semantic version + 7. In consumer Tenant: + Kit install Worker executes (Journey 2, step 3 pattern) + Per-file conflict WorkerInteractions resolved + Kit validation ValidationSession passes + Tenant.approvedWorkerCategories updated to include Kit categories + DECISION_POINTS: + - KitTargetPath: current directory / custom path + - ManifestApproval: approve / preview / edit / rerun discovery / cancel + - RegistryWriteBackApproval: Gate 2 per Tenant policy + - PerFileConflict: accept upstream / keep existing / diff and decide + GUARDS: [ + Kit discovery must complete before manifest proposal is generated, + Manifest must be approved (not cancelled) before Kit validation runs, + Kit ValidationSession must pass (Evidence attached) before publish, + Consumer Tenant Kit validation must pass before Workers from the Kit + can be invoked, + GTS type IDs in Kit must be unique within the Registry namespace + ] + NEXT: Consumer Tenant teams invoke Kit Workers in their journeys +``` + +--- + +### Journey 6: Generate Project Documentation + +```text +ALGORITHM GenerateProjectDocumentation + ACTOR: Technical Writer or Developer + GOAL: Produce audience-tuned, reviewed, and validated project documentation + grounded in an exploration of Objects in the Studio graph and source + INPUTS: [ + Documentation scope defined (module, API, architecture, onboarding, etc.), + design[] — for accuracy grounding, + feature_spec[] — for API/behavior grounding, + source_file[] [sync: github] (optional; for code-level accuracy), + workspace configured + ] + OUTPUTS: [ + document Object (state: draft → approved) — documentation artifact, + ValidationSession + Evidence (gap_analysis_validator), + WorkerRun audit trail + ] + COST TIER: high (document_retriever hybrid + create_design_worker llm) + AUTOMATION GATE: approved_automation + STEPS: + 1. invoke document_retriever (document_index, workspace scope, on_demand): + Input: documentation scope as query + Output: relevant Objects — design[], feature_spec[], existing docs, + architectural context for the target area + WorkerRun created; state: pending → running → done + DECISION: Scope clarification needed? + YES: WorkerInteraction (kind: free_form_intent) created + Writer elaborates: audience, narrator style, diagram preference + WorkerRun resumes + NO: proceed with retrieved context + 2. invoke code_retriever (code_index, workspace scope, on_demand): + Input: scope query → source_file[] content for factual accuracy + WorkerRun created; state: pending → running → done + 3. invoke create_design_worker (llm, on_demand) in documentation mode: + Input: document_retriever output, code_retriever output, + design[], feature_spec[] + (from Worker.inputBindings: source graph/chain) + Output: document Object (state: draft) with: + Audience-tuned content (developer / PM / newcomer / mixed), + Narrator style (first-person / third-person / neutral), + Diagrams (Mermaid embedded / suggested / skipped), + TOC, section structure + WorkerRun created; state: pending → running → done + If clarification needed mid-run: + WorkerInteraction (kind: input_request) created + WorkerRun.state → awaiting_input; Writer responds; resumes + 4. gap_analysis_validator fires (realtime): + Checks: TOC consistency, required sections present, no broken + cross-references, language complexity within audience target + ValidationSession created + On pass: Evidence attached to document Object + On fail (within maxRetries): WorkerInteraction (kind: menu) with + options per gap; Writer resolves; validator retries + On fail (retries exhausted): Approval (kind: risk_acceptance) created + 5. DECISION: Document acceptable? + YES: document.state → approved (StatePolicy; requires Evidence) + NO: Writer edits document directly or re-runs create_design_worker + with amended scope; gap_analysis_validator re-fires + DECISION_POINTS: + - ScopeClarity: proceed / WorkerInteraction free_form_intent + - AudienceDimension: developer / PM / newcomer / mixed + - NarratorDimension: first-person / third-person / neutral + - DiagramDimension: auto-embed / suggest / skip + - DocumentAcceptance: approve / re-run with amendments + GUARDS: [ + document_retriever must complete before create_design_worker begins, + gap_analysis_validator Evidence must be attached before document.state + can advance to approved, + Fix-loop must not alter factual content without re-running + document_retriever if significant structural changes are made, + Audience dimension must be resolved (WorkerInteraction) before authoring + ] + NEXT: Documentation Object available in graph; share or embed in design +``` + +--- + +### Journey 7: Author a PRD + +```text +ALGORITHM AuthorPRD + ACTOR: Product Manager + GOAL: Produce a validated prd Object with requirements, actors, use + cases, success criteria, and Object IDs that gate downstream + SDLC artifact authoring + INPUTS: [ + Product concept or problem description, + Stakeholder context, + design[] or feature_spec[] (optional; for grounding), + Optional: prd [sync: jira/confluence] if imported via Connector + ] + OUTPUTS: [ + prd Object (state: draft → approved) with fr[], nfr[], use_case[], + success_criteria[] sub-Objects each with unique IDs, + ValidationSession + Evidence (gap_analysis_validator), + WorkerRun audit trail + ] + COST TIER: high (create_prd_worker llm + gap_analysis_validator hybrid) + AUTOMATION GATE: approved_automation + STEPS: + 1. PM describes the product or feature area. + WorkerInteraction (kind: free_form_intent) created: + WorkerRun.state → awaiting_input + PM elaborates: actors, goals, key requirements, success conditions + WorkerRun resumes + 2. DECISION: Import PRD from external system? + YES (prd exists in Confluence/Jira): + connector_inbound_sync_worker imports prd [sync: confluence/jira] + prd Object created with externalRef populated + Proceed to step 4 for gap validation + NO: proceed to step 3 + 3. invoke create_prd_worker (llm, on_demand): + Input: free_form_intent output, optional design[], feature_spec[] + (from Worker.inputBindings: source user/graph) + Output: prd Object (state: draft) with sections: + Overview, Actors, Goals, + fr[] (Functional Requirements, each with unique Object ID, + RFC 2119 MUST/SHALL language), + nfr[] (Non-Functional Requirements, each with unique Object ID), + use_case[] (actor-goal-scenario triples referencing fr IDs), + success_criteria[] (measurable acceptance conditions per fr) + WorkerRun created; state: pending → running → done + If clarification needed mid-run: + WorkerInteraction (kind: input_request) created + WorkerRun.state → awaiting_input; PM responds; resumes + 4. gap_analysis_validator fires (realtime): + Checks: fr[] non-empty, all fr have success_criteria, nfr[] present, + use_case[] reference valid fr IDs, no orphaned sub-Objects + ValidationSession created + On pass: Evidence attached to prd Object + On fail (within maxRetries): WorkerInteraction (kind: menu) with + options per gap; PM resolves; validator retries + On fail (retries exhausted): Approval (kind: risk_acceptance) created + 5. DECISION: PRD acceptable? + YES: prd.state → approved (StatePolicy; requires Evidence) + NO: PM edits prd directly or re-runs create_prd_worker with amended + intent; gap_analysis_validator re-fires + DECISION_POINTS: + - ImportVsAuthor: import via Connector / author with create_prd_worker + - PRDAcceptance: approve / re-run with amendments + - GapResolution: WorkerInteraction (kind: menu) per gap + GUARDS: [ + create_prd_worker cannot be invoked without resolved free_form_intent, + fr[] Object IDs must be unique within the Tenant namespace, + All fr must use RFC 2119 MUST/SHALL/SHOULD language, + gap_analysis_validator Evidence must be attached before prd.state → approved, + Imported prd via Connector must still pass gap_analysis_validator + ] + NEXT: Journey 8 (Record ADR) or Journey 9 (Author System Design) +``` + +--- + +### Journey 8: Record an Architecture Decision + +```text +ALGORITHM RecordArchitectureDecision + ACTOR: Architect or Tech Lead + GOAL: Capture a technology or design decision as an adr Object with + context, options, consequences, and a unique ID that can be + cross-referenced in the system design + INPUTS: [ + Decision description, + Considered alternatives, + design Object (optional; for cross-reference), + prd Object (optional; for requirement grounding) + ] + OUTPUTS: [ + adr Object (state: draft → approved) with unique ID, options, + decision outcome, consequences, + ValidationSession + Evidence (adr_structure_validator), + adr ID registered in design.architectureDrivers (if design linked) + ] + COST TIER: medium (object_graph_retriever hybrid + create_adr_worker llm) + AUTOMATION GATE: approved_automation + STEPS: + 1. invoke object_graph_retriever (workspace scope, hybrid, on_demand): + Input: decision topic query + Output: relevant Objects — related adr[], design[], component refs + WorkerRun created; state: pending → running → done + 2. invoke create_adr_worker (llm, on_demand): + Input: decision description, retrieved context + (from Worker.inputBindings: source graph/chain/user) + Output: adr Object (state: draft) with: + Context and Problem Statement, + Decision Drivers, + Considered Options (≥ 2) with pros/cons per option, + Decision Outcome with rationale, + Consequences (positive, negative, neutral), + unique Object ID assigned + WorkerRun created; state: pending → running → done + If clarification needed mid-run: + WorkerInteraction (kind: input_request) created + WorkerRun.state → awaiting_input; Architect responds; resumes + 3. adr_structure_validator fires (realtime | on_demand): + ValidationSession created + Checks: ≥ 2 options present, decision outcome non-empty, + consequences section non-empty, Object ID assigned + On pass: Evidence attached to adr Object + On fail (within maxRetries): WorkerInteraction (kind: menu) per gap + On fail (retries exhausted): Approval (kind: risk_acceptance) created + 4. DECISION: ADR acceptable? + YES: adr.state → approved (StatePolicy; requires Evidence) + NO: Architect edits adr; create_adr_worker re-runs; validator re-fires + 5. DECISION: Cross-reference in design? + YES: object_graph_retriever locates parent design; + adr Object ref added to design.architectureDrivers + NO: adr remains standalone + DECISION_POINTS: + - ADRAcceptance: approve / re-run with amendments + - CrossReference: register in design / standalone + GUARDS: [ + adr Object must contain at least two considered options, + Consequences section must be non-empty before ValidationSession passes, + adr Object ID must be unique within the Tenant namespace, + adr_structure_validator Evidence must be attached before adr.state → approved + ] + NEXT: Journey 9 (Author System Design referencing this ADR) +``` + +--- + +### Journey 9: Author a System Design + +```text +ALGORITHM AuthorSystemDesign + ACTOR: Architect or Tech Lead + GOAL: Document system architecture covering components, interfaces, + boundaries, principles, and constraints as a design Object, + with IDs that downstream decomposition and implementation reference + INPUTS: [ + prd Object (for fr[] and nfr[] to satisfy), + adr[] (for architecture drivers), + High-level architecture knowledge + ] + OUTPUTS: [ + design Object (state: draft → approved) with component[], principle[], + constraint[], interface[] sub-Objects each with unique IDs, + ValidationSession + Evidence (gap_analysis_validator) + ] + COST TIER: high (create_design_worker llm + gap_analysis_validator hybrid) + AUTOMATION GATE: approved_automation + STEPS: + 1. invoke object_graph_retriever (workspace scope, hybrid, on_demand): + Input: design scope query + Output: relevant Objects — prd, adr[], existing design refs + WorkerRun created; state: pending → running → done + 2. invoke create_design_worker (llm, on_demand): + Input: prd, adr[] (from Worker.inputBindings: source graph/chain) + Output: design Object (state: draft) with sections: + Architecture Vision — purpose, scope, quality attributes, + Architecture Drivers — links to adr Object IDs and prd nfr IDs, + principle[] (each with unique Object ID), + constraint[] (each with unique Object ID), + component[] (each with unique Object ID; responsibilities, boundaries), + interface[] — contracts between components (input/output schemas, + protocols, error semantics) + WorkerRun created; state: pending → running → done + If clarification needed mid-run: + WorkerInteraction (kind: input_request) created + WorkerRun.state → awaiting_input; Architect responds; resumes + 3. DECISION: Include sequence diagrams? + YES: create_design_worker generates Mermaid diagrams for key + interaction flows and embeds inline in design Object + NO: diagram placeholders inserted; Architect authors separately + 4. gap_analysis_validator fires (realtime): + Checks: all prd fr[] referenced in component[] or interface[], + all major technology choices linked to adr Object IDs, + component[] IDs unique, principle[] and constraint[] non-empty + ValidationSession created + On pass: Evidence attached to design Object + On fail (within maxRetries): WorkerInteraction (kind: menu) per gap + On fail (retries exhausted): Approval (kind: risk_acceptance) created + 5. DECISION: Design acceptable? + YES: design.state → approved (StatePolicy; requires Evidence) + NO: Architect edits design; create_design_worker re-runs with + amended context; gap_analysis_validator re-fires + DECISION_POINTS: + - SequenceDiagrams: auto-embed Mermaid / placeholders + - DesignAcceptance: approve / re-run with amendments + GUARDS: [ + prd Object must be in state: approved before create_design_worker runs, + All component[] Object IDs must be unique within the Tenant namespace, + design must reference existing adr Object IDs for every major + technology choice, + gap_analysis_validator Evidence must be attached before design.state → approved + ] + NEXT: Journey 10 (Decompose Design into Tasks) +``` + +--- + +### Journey 10: Decompose Design into Tasks + +```text +ALGORITHM DecomposeDesignIntoTasks + ACTOR: Tech Lead or PM + GOAL: Break a design Object into an ordered, dependency-linked + decomposition + task[] with full prd and design coverage, and + write task[] back to Jira + INPUTS: [ + design Object (state: approved), + prd Object (for fr[] coverage links), + workspace [sync: jira] configured + ] + OUTPUTS: [ + decomposition Object — ordered feature list with dependency graph, + task[] (state: planned) [write-back: jira] — each with unique Object ID, + dependency links, coverage links to prd fr[] and design component[], + Definition of Done, + ValidationSession + Evidence (gap_analysis_validator) + ] + COST TIER: high (decompose_feature_worker llm + gap_analysis_validator hybrid) + AUTOMATION GATE: approved_automation + STEPS: + 1. invoke decompose_feature_worker (llm, on_demand): + Input: design, prd (from Worker.inputBindings: source graph/chain) + Output: decomposition Object + task[] (state: planned) + Each task entry: + unique Object ID, + one-paragraph description of scope and boundaries, + dependency links to other task Object IDs, + coverage links to prd fr[] IDs and design component[] IDs, + initial status: planned, + measurable Definition of Done + WorkerRun created; state: pending → running → done + Worker requests ordering clarification: + WorkerInteraction (kind: menu) created + Options: [dependency order, risk-first, value-first] + WorkerRun resumes after selection + 2. gap_analysis_validator fires (realtime): + Checks: every task references ≥ 1 prd fr[], dependency graph + acyclic, all tasks have non-empty Definition of Done, + design component[] coverage ≥ threshold + ValidationSession created + On pass: Evidence attached to decomposition Object + On fail (within maxRetries): WorkerInteraction (kind: menu) per gap + On fail (retries exhausted): Approval (kind: risk_acceptance) created + 3. DECISION: Review tasks before write-back? + YES: Tech Lead reviews task[] in Studio; edits names, priorities, + owners via WorkerInteraction (kind: input_request) + NO: proceed directly to step 4 + 4. Connector write-back via [write-back: jira]: + connector_outbound_sync_worker writes task[] to Jira + Gate 2 check: WriteBackPolicy.requiresApproval + If true: Approval Object created; PM/Lead approves + If approved: write-back executes; task[].externalRef populated + DECISION_POINTS: + - OrderingStrategy: dependency order / risk-first / value-first + - TaskReviewBeforeWriteBack: review first / write-back immediately + - WriteBackApproval: Gate 2 (jira write-back) per Tenant policy + GUARDS: [ + design Object must be in state: approved before decompose_feature_worker runs, + Every task must reference at least one prd fr[] Object ID, + Dependency graph must have no cycles, + All tasks must have a non-empty Definition of Done, + gap_analysis_validator Evidence must be attached before decomposition + is considered complete, + Gate 2 (WriteBackPolicy) must be satisfied before jira write-back + ] + NEXT: Journey 11 (Author Feature Specification) per task entry +``` + +--- + +### Journey 11: Author a Feature Specification + +```text +ALGORITHM AuthorFeatureSpecification + ACTOR: Tech Lead or Developer + GOAL: Write a precise, implementable feature_spec Object with CDSL flows, + algorithms, state diagrams, and test scenarios that developers can + implement with full traceability + INPUTS: [ + task Object (from decomposition; with unique ID and description), + design Object (for interface contracts), + prd Object (for acceptance criteria) + ] + OUTPUTS: [ + feature_spec Object (state: draft → approved) with flow[], algo[], + state_diagram[] sub-Objects (each with unique ID) and test_scenario[], + ValidationSession + Evidence (gap_analysis_validator) + ] + COST TIER: high (create_feature_spec_worker llm + gap_analysis_validator hybrid) + AUTOMATION GATE: approved_automation + STEPS: + 1. invoke object_graph_retriever (workspace scope, hybrid, on_demand): + Input: task Object ID + scope query + Output: relevant Objects — design interface contracts, prd fr[], + related feature_spec[] for consistency + WorkerRun created; state: pending → running → done + 2. invoke create_feature_spec_worker (llm, on_demand): + Input: task, design, prd + (from Worker.inputBindings: source graph/chain) + Output: feature_spec Object (state: draft) with sections: + Overview — feature purpose, scope, link to task, + flow[] — each with unique Object ID; GIVEN/WHEN/THEN scenarios + covering nominal path and primary alternates, + algo[] — each with unique Object ID; pseudocode or ALGORITHM block, + test_scenario[] — ≥ 1 happy-path + ≥ 1 error/edge-case per flow, + Definition of Done — measurable, checkable criteria from prd + WorkerRun created; state: pending → running → done + If clarification needed mid-run: + WorkerInteraction (kind: input_request) created + WorkerRun.state → awaiting_input; Developer responds; resumes + 3. DECISION: Include state diagrams? + YES: create_feature_spec_worker generates Mermaid state diagrams + for stateful entities; each state assigned unique Object ID + NO: state_diagram section omitted + 4. gap_analysis_validator fires (realtime): + Checks: flow[] Object IDs unique, test_scenario[] cover ≥ 1 happy + + ≥ 1 error case per flow, Definition of Done measurable, + prd acceptance criteria addressed + ValidationSession created + On pass: Evidence attached to feature_spec Object + On fail (within maxRetries): WorkerInteraction (kind: menu) per gap + On fail (retries exhausted): Approval (kind: risk_acceptance) created + 5. DECISION: Feature spec acceptable? + YES: feature_spec.state → approved (StatePolicy; requires Evidence) + NO: Developer edits feature_spec; create_feature_spec_worker re-runs; + gap_analysis_validator re-fires + DECISION_POINTS: + - StateDiagrams: include Mermaid state diagrams / omit + - SpecAcceptance: approve / re-run with amendments + GUARDS: [ + task Object must exist and be linked to decomposition before + create_feature_spec_worker runs, + All flow[] Object IDs must be unique within the Tenant namespace, + test_scenario[] must cover ≥ 1 happy-path and ≥ 1 error case per flow, + Definition of Done must be measurable and checkable, + gap_analysis_validator Evidence must be attached before feature_spec.state + → approved + ] + NEXT: Journey 12 (Implement a Feature with Traceability) +``` + +--- + +### Journey 12: Implement a Feature with Traceability + +```text +ALGORITHM ImplementFeatureWithTraceability + ACTOR: Developer + GOAL: Write production code implementing a feature_spec Object, with + traceability markers linking every code unit back to feature_spec + flow[] and algo[] IDs, produce a PR, and pass design conformance + INPUTS: [ + feature_spec Object (state: approved; with flow[] and algo[] IDs), + design[] — for conformance check, + repository [sync: github] + ] + OUTPUTS: [ + source_file[] — implementation with traceability markers, + pull_request (state: review) [write-back: github] with + conformsToDesign[] and implementsRequirements[], + ValidationSession (pr_design_validator) + Evidence, + WorkerRun audit trail + ] + COST TIER: high (implement_code_worker llm + create_pr_worker hybrid) + AUTOMATION GATE: approved_automation + STEPS: + 1. invoke object_graph_retriever (workspace scope, hybrid, on_demand): + Input: feature_spec Object ID + codebase scope + Output: relevant source_file[], component[], interface[] Objects + WorkerRun created; state: pending → running → done + 2. DECISION: Write tests first? + YES (test-first): WorkerInteraction (kind: menu): + Developer (or Worker) writes failing tests per flow[] test_scenario[] + before implementation code; WorkerRun resumes + NO: implementation code written first; tests added in same WorkerRun + 3. invoke implement_code_worker (llm, on_demand): + Input: feature_spec, task, code_retriever context + (from Worker.inputBindings: source graph/chain) + Output: source_file[] with traceability markers: + Every function/class/block satisfying a flow[] or algo[] Object ID + carries a marker referencing that Object ID + WorkerRun created; state: pending → running → done + If clarification needed mid-run: + WorkerInteraction (kind: input_request) created + WorkerRun.state → awaiting_input; Developer responds; resumes + 4. stale_artifact_detection Analyzer fires (realtime): + Checks traceability markers reference IDs in current feature_spec + (not stale/renamed IDs) + On fail: WorkerInteraction to resolve stale references + 5. invoke create_pr_worker (hybrid, on_demand): + Input: source_file[], branch + Output: pull_request [write-back: github] + pull_request.implementsRequirements = [feature_spec flow[] IDs] + pull_request.closesIssues = [task Object] + Gate 2: WriteBackPolicy.requiresApproval checked for github write-back + 6. pr_design_validator fires automatically (realtime, onEvent: PR → review): + ValidationSession created + On pass: Evidence attached to pull_request; PR ready for review + On fail (within maxRetries): WorkerInteraction (kind: menu) per + finding; Developer amends source_file[]; create_pr_worker re-runs; + pr_design_validator re-fires + On fail (retries exhausted): Approval (kind: risk_acceptance) created + DECISION_POINTS: + - TestFirstPath: yes (test-first) / no (implementation-first) + - StaleMarkerResolution: WorkerInteraction per stale reference + - WriteBackApproval: Gate 2 (github write-back) per Tenant policy + - ConformanceResult: pass / fail-and-fix loop / escalate + GUARDS: [ + feature_spec must be in state: approved before implement_code_worker runs, + Traceability markers in source_file[] must reference IDs from the + source feature_spec — no orphaned or invented IDs, + stale_artifact_detection must pass (or be acknowledged) before PR creation, + pr_design_validator Evidence must be attached before pull_request can + advance to state: approved, + Gate 2 (WriteBackPolicy) must be satisfied before github write-back + ] + NEXT: Journey 13 (Change Impact) or Journey 17 (Release Readiness) +``` + +--- + +### Journey 13: Analyze Change Impact + +```text +ALGORITHM AnalyzeChangeImpact + ACTOR: Tech Lead, PM, or Release Manager + GOAL: Understand which downstream Objects and traceability markers are + affected by a change to an upstream artifact, and surface stale + or uncovered dependencies before they reach production + INPUTS: [ + Changed Object ID (e.g., prd fr[] ID), + Baseline Object state (prior version or snapshot), + Current Object state (HEAD) + ] + OUTPUTS: [ + Impact report WorkerRun output: cascade tree of affected Objects, + Recommendation[] (state: pending) — one per stale or uncovered Object, + stale_artifact_detection findings — Objects not updated within threshold + ] + COST TIER: medium (traceability_analysis hybrid + stale_artifact_detection script) + AUTOMATION GATE: none (Analyzer Workers; read-only) + STEPS: + 1. traceability_analysis Analyzer Worker runs (hybrid, on_demand): + Input: changed Object ID + workspace scope + Maps: prd → design → decomposition → feature_spec → source_file[] + pull_request chains + Identifies: all downstream Objects referencing the changed ID + Creates Recommendation per broken or unresolved downstream link + WorkerRun created; state: pending → running → done + 2. stale_artifact_detection Analyzer Worker runs (script, realtime): + Input: downstream Object set identified in step 1 + Checks: Objects not updated within Tenant staleness threshold + since the upstream Object changed + Creates Recommendation (severity: warning | critical) per stale Object + WorkerRun created; state: pending → running → done + 3. DECISION: Analysis mode? + CASCADE-TRACKING: report cascade tree and Recommendations only + RELEASE-READINESS: additionally produce version bump recommendation + (patch/minor/major) based on breadth and depth of impact + (connects to Journey 17) + 4. User reviews Recommendation[] in Studio UI: + severity: info | warning | critical + DECISION: Per Recommendation action? + ACCEPT: user triggers downstream artifact update Workers + DISMISS: Recommendation dismissed with reason + SNOOZE: re-check scheduled + 5. Impact report WorkerRun output aggregated: + cascade tree, stale Object list, coverage gaps, optional + version bump recommendation + DECISION_POINTS: + - AnalysisMode: cascade-tracking / release-readiness-estimation + - PerRecommendationAction: accept / dismiss / snooze + GUARDS: [ + Read-only operation — traceability_analysis and stale_artifact_detection + never modify Objects, + Recommendations created only if gap/staleness persists after re-check; + stale Recommendations invalidated when gap closes, + confidence: partial allowed when Connector is unavailable (Analyzers + continue with available graph data) + ] + NEXT: Update affected downstream Objects, or Journey 14 (Review PR) +``` + +--- + +### Journey 14: Review a Pull Request + +```text +ALGORITHM ReviewPullRequest + ACTOR: Tech Lead, Reviewer, or Team Lead + GOAL: Obtain a structured review of a GitHub PR against code quality, + design, adr, and prd standards, with severity-rated findings + persisted as ValidationSession + Evidence + INPUTS: [ + pull_request (state: review) [sync: github], + design[] — linked via pull_request.conformsToDesign refs, + adr[] — for architecture decision consistency, + prd fr[] — for requirements traceability, + feature_spec[] — for acceptance criteria + ] + OUTPUTS: [ + ValidationSession (pr_design_validator) — findings grouped by domain, + Evidence attached to pull_request (on pass), + Recommendation[] (state: pending) — per non-critical finding, + security_impact_analysis report (WorkerRun output) + ] + COST TIER: medium (pr_design_validator hybrid + security_impact_analysis hybrid) + AUTOMATION GATE: none (Validators and Analyzers run at any automationLevel) + STEPS: + 1. pr_design_validator fires automatically (realtime, onEvent: PR → review) + or is invoked on_demand: + ValidationSession created + Input: pull_request diff, design[], acceptance_criteria[] + Checks (per domain): + Code — correctness, style, patterns per codebase rules, + Design — consistency with design component[] and interface[], + ADR — implementation consistent with adr decision outcomes; + no silent overrides, + PRD — changed behavior traceable to prd fr[]; no scope creep + Output: ValidationResult with findings rated: + critical (blocks merge) / major (should fix before merge) / + minor (can fix post-merge) / info (observation only) + WorkerRun created; state: pending → running → done + 2. security_impact_analysis Analyzer runs (hybrid, on_demand | scheduled): + Input: pull_request[], vulnerability[], security_finding[] + Output: Recommendation[] per security finding in PR scope + WorkerRun created; state: pending → running → done + 3. gap_analysis Analyzer runs (hybrid, on_demand): + Input: pull_request, prd fr[], feature_spec[] + Checks: changed behavior traceable to requirements + Creates Recommendation per coverage gap + WorkerRun created; state: pending → running → done + 4. Tech Lead reviews ValidationResult + Recommendation[] in Studio UI + (or via GitHub comment from Connector write-back if configured). + 5. DECISION: Conformance outcome? + PASS: Evidence attached to pull_request; pull_request can advance + FAIL (within maxRetries): Developer notified; pushes fix; + pr_design_validator re-fires + FAIL (retries exhausted): Approval (kind: risk_acceptance) created; + Tech Lead approves exception or rejects PR + 6. DECISION: Single PR or all open PRs? + SINGLE: process as above + ALL: traceability_analysis Analyzer scans all open pull_request[] + [sync: github]; produces per-PR ValidationSession summary + DECISION_POINTS: + - ReviewScope: single PR / all open PRs + - ConformanceOutcome: pass / fail-and-retry / escalate + - EscalationDecision: approve exception / reject PR + GUARDS: [ + Read-only validation — Validators never modify source_file[] or design[], + PR diff always re-fetched from GitHub Connector; no cached data reused, + Evidence is immutable once attached to pull_request, + security_impact_analysis Recommendation[] must be reviewed before + ValidationSession can close + ] + NEXT: Journey 13 (change impact) or address findings in a fix branch +``` + +--- + +### Journey 15: Reconstruct SDLC Artifacts from Code + +```text +ALGORITHM ReconstructSDLCArtifactsFromCode + ACTOR: Tech Lead or Architect (working with legacy or undocumented code) + GOAL: Reconstruct missing prd, design, decomposition, and feature_spec + Objects from existing code using code_retriever output as primary + evidence, flagging gaps where evidence is insufficient + INPUTS: [ + Code scope (directory or file list) [sync: github], + Existing traceability markers in code (optional), + workspace configured + ] + OUTPUTS: [ + Reconstructed SDLC Objects (prd | design | decomposition | feature_spec) + grounded in actual code behavior, + gap_marker annotations in Objects where code evidence is missing or + ambiguous, + ValidationSession + Evidence per reconstructed Object + ] + COST TIER: high (code_retriever hybrid + reverse_engineer_worker llm chain) + AUTOMATION GATE: approved_automation + STEPS: + 1. invoke code_retriever (code_index, workspace scope, on_demand): + Input: code scope query + Output: source_file[] content, function signatures, test cases, + module boundaries, existing traceability markers + WorkerRun created; state: pending → running → done + 2. DECISION: Marker strategy? + WorkerInteraction (kind: menu) created: + Options: [marker-first (extract existing traceability markers as + artifact skeleton), pattern-inference (infer from code + structure — module names, function names, test names)] + Architect selects → WorkerRun resumes + 3. DECISION: Target artifact kinds? + WorkerInteraction (kind: menu) created: + Options: [feature_spec only (default), full pipeline (prd + design + + decomposition + feature_spec in order)] + Architect selects → WorkerRun resumes + 4. Flow X activates (entryConstraints: code_retriever output, marker + strategy, target kinds): + FlowRun created + mandatorySteps executed in sequence per target kind: + 5. invoke reverse_engineer_worker (llm, on_demand) per target Object kind: + Input: code_retriever output (source_file[], markers, test cases) + (from Worker.inputBindings: source chain) + Output: reconstructed Object (state: draft) with: + Content grounded in code evidence (marker locations, function + signatures, test cases, module interfaces), + gap_marker annotations where code evidence is absent or ambiguous + (description of what is missing and why it could not be inferred) + WorkerRun created; state: pending → running → done + If clarification needed mid-run: + WorkerInteraction (kind: input_request) created + WorkerRun.state → awaiting_input; Architect responds; resumes + 6. gap_analysis_validator fires per reconstructed Object (realtime): + ValidationSession created + On pass: Evidence attached to Object + On fail (within maxRetries): WorkerInteraction (kind: menu) per gap + On fail (retries exhausted): Approval (kind: risk_acceptance) created + 7. DECISION: Object acceptable? + YES: Object.state → approved (StatePolicy; requires Evidence) + NO: Architect edits Object; reverse_engineer_worker re-runs for + that kind; gap_analysis_validator re-fires + 8. Repeat steps 5–7 for each target artifact kind in pipeline order. + DECISION_POINTS: + - MarkerStrategy: marker-first / pattern-inference + - TargetArtifactKinds: feature_spec only / full pipeline + - PerObjectAcceptance: approve / re-run with amendments + GUARDS: [ + Every reconstructed requirement or flow must be grounded in actual + code behavior observable in the code scope, + Discrepancies between inferred spec and actual code must be flagged + as gap_marker annotations — never silently omitted, + gap_analysis_validator Evidence must be attached before Object.state + → approved, + reverse_engineer_worker must never delete or overwrite existing approved + SDLC Objects without explicit WorkerInteraction confirmation + ] + NEXT: Journey 13 (change impact) or Journey 12 (implement missing features) +``` + +--- + +### Journey 16: Full SDLC Pipeline End-to-End + +```text +ALGORITHM FullSDLCPipelineEndToEnd + ACTOR: Product Manager, Architect, Developer (team) + GOAL: Deliver a fully traced feature from product requirement to + production code, with every Object linked by IDs and validated + at each stage via ValidationSession + Evidence + INPUTS: [ + Product idea or problem statement, + Studio v2 initialized with SDLC Kit and Connectors (Journey 2), + repository [sync: github], workspace [sync: jira] + ] + OUTPUTS: [ + prd + adr[] + design + decomposition + feature_spec[] + source_file[] + — all Objects with unique IDs and traceability links, + pull_request[] [write-back: github] — all passing pr_design_validator, + ValidationSession[] + Evidence — one per Object at each stage, + task[] [write-back: jira] — with traceability to prd fr[] + ] + COST TIER: high (full chain of LLM + hybrid Workers) + AUTOMATION GATE: approved_automation + STEPS: + 1. PM invokes create_prd_worker (Journey 7): + prd Object (state: approved) — fr[], nfr[], use_case[], + success_criteria[] each with unique IDs; + gap_analysis_validator Evidence attached. + 2. Architect invokes create_adr_worker for each major technology decision + (Journey 8): + adr[] Objects (state: approved) — options, decision outcome, + consequences; adr_structure_validator Evidence attached; + adr IDs registered in design.architectureDrivers. + 3. Architect invokes create_design_worker (Journey 9): + design Object (state: approved) — component[], principle[], + constraint[], interface[] each with unique IDs; + gap_analysis_validator Evidence attached; prd fr[] and adr[] + coverage confirmed. + 4. Tech Lead invokes decompose_feature_worker (Journey 10): + decomposition Object + task[] (state: planned) — each task with + unique ID, dependency links, prd fr[] coverage links; + gap_analysis_validator Evidence attached; + task[] [write-back: jira] via Gate 2. + 5. For each task: Developer invokes create_feature_spec_worker + (Journey 11): + feature_spec Object (state: approved) — flow[], algo[], state_diagram[], + test_scenario[] each with unique IDs; + gap_analysis_validator Evidence attached. + 6. Developer invokes implement_code_worker + create_pr_worker + + pr_design_validator (Journey 12): + source_file[] with traceability markers referencing feature_spec IDs; + pull_request [write-back: github]; + pr_design_validator ValidationSession + Evidence attached to PR; + Gate 2 satisfied for github write-back. + 7. traceability_analysis Analyzer runs (Journey 13): + Confirms all prd → design → decomposition → feature_spec → + source_file chains intact; Recommendation[] created for any gaps. + 8. pr_design_validator has already run on each PR (step 6); + Tech Lead reviews ValidationResult summary per PR. + DECISION_POINTS: + - ADRCount: one create_adr_worker invocation per major decision + - FeatureGranularity: adjust decompose_feature_worker task granularity + via WorkerInteraction (kind: menu) ordering selection + - TestFirst: write feature_spec test_scenario[] before implementation? + (Journey 12 step 2) + GUARDS: [ + Every feature_spec references its parent task Object ID, + Every traceability marker in source_file[] traces to a flow[] Object ID + in a feature_spec, + gap_analysis_validator Evidence attached at every artifact stage before + Object.state → approved, + pr_design_validator Evidence attached to each pull_request before + state: approved, + Gate 2 (WriteBackPolicy) satisfied for jira and github write-backs + ] + NEXT: Journey 13 (change impact for future changes), + Journey 18 (PR status monitoring) +``` + +--- + +### Journey 17: Release Readiness Estimation + +```text +ALGORITHM ReleaseReadinessEstimation + ACTOR: Release Manager, Tech Lead + GOAL: Before a release, assess downstream impact of all artifact changes, + gate on automated validators, produce a version bump recommendation, + and obtain Tech Lead Approval + INPUTS: [ + release Object (state: candidate), + release_component[] — component versions in this release, + pull_request[] [sync: github] — merged PRs for this release, + Changed upstream Object ID(s), + Baseline Object state (prior release tag) + ] + OUTPUTS: [ + release Object (state: approved | blocked), + ValidationSession[] + Evidence — per mandatory Validator, + Approval (kind: release_approval) — Tech Lead sign-off, + Impact report (traceability_analysis WorkerRun output): + cascade tree, stale Object list, coverage gaps, + version bump recommendation (patch | minor | major) + ] + COST TIER: medium (traceability_analysis hybrid + release_readiness_review Flow) + AUTOMATION GATE: none (Validators run at any automationLevel; + Approval is StatePolicy gate) + STEPS: + 1. Release Manager creates release Object (state: candidate). + Flow: release_readiness_review activates (entryConstraints: release, + state: candidate). + FlowRun created; mandatorySteps executed in sequence. + 2. traceability_analysis Analyzer Worker runs (hybrid, on_demand): + Input: changed Object IDs + workspace scope + Maps full cascade: prd → design → decomposition → feature_spec + → source_file[] → pull_request[] chains + Identifies stale Objects (stale_artifact_detection co-runs) + Creates Recommendation per gap or stale Object + WorkerRun created; state: pending → running → done + FlowRun.completedSteps updated + 3. gap_analysis_validator (hybrid, realtime) — mandatoryStep: + Checks all prd fr[] in release scope are implemented + tested + ValidationSession created + On pass: Evidence attached to release Object + On fail: release blocked with gap list; PM/Dev must close gaps; + gap_analysis_validator re-runs + 4. DECISION: Version bump recommendation: + traceability_analysis output determines: + breaking changes → major + new behavior (new fr[] or component[]) → minor + fix only (no new IDs) → patch + WorkerInteraction (kind: menu) for Release Manager to confirm + or override the recommendation + 5. All mandatory Validators pass → Approval (kind: release_approval) created: + requiredRole: tech_lead + payload: { release Object, Evidence[] from all validators, + version bump recommendation, cascade tree summary } + 6. DECISION: Tech Lead Approval? + APPROVE: release.state → approved + REQUEST CHANGES: gaps identified; release.state remains: candidate + REJECT: release.state → blocked + DECISION_POINTS: + - ValidatorFailureResolution: fix gaps / add tests / create security exception + - VersionBumpConfirmation: WorkerInteraction (kind: menu) to confirm/override + - TechLeadApprovalDecision: approve / request changes / reject + GUARDS: [ + All mandatory Validators must reach ValidationSession.state: pass + before Approval is created, + Read-only analysis — traceability_analysis never modifies Objects, + Approval is mandatory for release.state → approved; no bypass, + Evidence from each Validator is immutable and attached to release + audit trail + ] + NEXT: Journey 12 if gaps found (implement missing features), + external deploy pipeline after release.state: approved +``` + +--- + +### Journey 18: PR Status Monitoring + +```text +ALGORITHM PRStatusMonitoring + ACTOR: Team Lead, PM, Release Manager + GOAL: Get a current status snapshot of one or all open GitHub PRs — + CI state, open findings from Validators, severity of unresolved + feedback, resolved-finding audit + INPUTS: [ + pull_request[] (state: review) [sync: github], + ValidationSession[] — associated with each pull_request, + workspace [sync: github] configured + ] + OUTPUTS: [ + Status report (traceability_analysis WorkerRun output) per PR: + CI sync state, open Recommendation count, ValidationSession.state, + severity assessment (critical / major / minor / info), + resolved-finding audit + ] + COST TIER: low (connector_inbound_sync_worker script + traceability_analysis) + AUTOMATION GATE: none (read-only Analyzer Workers) + STEPS: + 1. connector_inbound_sync_worker syncs pull_request[] from GitHub + [sync: github] (push webhook or scheduled pull): + pull_request Objects updated with current CI state, comment counts, + review decisions; externalRef.lastSyncedAt updated + WorkerRun created; state: pending → running → done + 2. traceability_analysis Analyzer Worker runs (hybrid, on_demand): + Input: pull_request[] + associated ValidationSession[] + design[] + Checks: which PRs have passing Evidence, which have open findings, + which have unresolved Recommendations, CI check states + Creates Recommendation per PR with stale or failing ValidationSession + WorkerRun created; state: pending → running → done + 3. Resolved-finding audit: + Analyzer checks: any ValidationSession finding marked resolved + without a corresponding source_file[] update in the PR + Creates Recommendation (severity: warning) per suspicious resolution + 4. DECISION: Single PR or all open PRs? + SINGLE: Analyzer scoped to one pull_request Object + ALL: Analyzer scans all pull_request[] with state: review + 5. Team Lead reviews status report: + per-PR: CI state, ValidationSession.state, open Recommendation count, + severity of unresolved findings, suspicious resolutions flagged + DECISION: Action per PR? + MERGE: PR passes all gates; merge decision made externally + REQUEST CHANGES: findings need resolution; developer notified + ESCALATE: critical findings unresolved; Approval escalation created + DECISION_POINTS: + - ReviewScope: single PR / all open PRs + - ResolvedFindingAudit: surface all / only suspicious resolutions + - PerPRAction: merge / request changes / escalate + GUARDS: [ + Always re-synced from GitHub Connector fresh — no cached data reused, + Read-only — no Object modifications during this journey, + Recommendations created only for persistent gaps; auto-invalidated when + gap closes + ] + NEXT: Journey 14 (deeper PR review) or Journey 4 (review-and-fix) +``` + +--- + +### Journey 19: Traceability Coverage Gate in CI + +```text +ALGORITHM TraceabilityCoverageGateInCI + ACTOR: Tech Lead, Developer, DevOps + GOAL: Enforce a minimum traceability coverage threshold as a CI quality + gate — fail the pipeline if Object ID coverage or marker depth + drops below the configured floor + INPUTS: [ + source_file[] [sync: github] — codebase with traceability markers, + feature_spec[] — for required Object IDs, + Configured min-coverage and min-granularity thresholds in Kit config, + CI Connector configured (github_actions or jenkins) + ] + OUTPUTS: [ + ValidationSession (traceability_coverage_validator): + exit: PASS (0) or FAIL (non-zero), + Coverage report WorkerRun output: + per-file coverage %, aggregate coverage %, granularity score, + Recommendation[] per uncovered feature_spec Object ID + ] + COST TIER: low (script Worker + CI Connector; no LLM) + AUTOMATION GATE: none (script Validator; read-only) + STEPS: + 1. Developer implements feature with traceability markers (Journey 12). + 2. CI pipeline triggers traceability_coverage_validator via CI Connector + (github_actions webhook event → connector_inbound_sync_worker → + traceability_analysis Analyzer + coverage script): + WorkerRun created; state: pending → running → done + 3. traceability_analysis Analyzer scans source_file[]: + Computes per-file and aggregate coverage: + (markers present / total feature_spec flow[] IDs required) + Computes granularity score: + (ratio of function-level markers to block-level markers) + WorkerRun created; state: pending → running → done + 4. ValidationSession (traceability_coverage_validator) evaluates: + If coverage >= min-coverage AND granularity >= min-granularity: + ValidationSession.state → pass; Evidence created + CI Connector write-back: [write-back: github_actions] → CI green + If below threshold: + ValidationSession.state → fail + Recommendation per uncovered feature_spec Object ID + CI Connector write-back: CI fail status + 5. DECISION: CI fail? + YES: Developer identifies uncovered feature_spec IDs from + Recommendation[]; adds missing markers; pushes fix; + CI re-triggers step 2 + NO: CI green; PR can proceed + 6. DECISION: Scan scope? + FULL CODEBASE: all source_file[] in workspace + SCOPED: filter to specific feature_spec[] scope (faster CI) + DECISION_POINTS: + - ScanScope: full codebase / scoped to feature area + - FailMode: hard fail (CI blocks merge) / warn only (advisory) + GUARDS: [ + Thresholds must be configured in Kit config before enforcement, + Coverage report always emitted even on failure for developer diagnosis, + CI Connector write-back (Gate 2) must be configured before CI status + can be updated, + Analyzer is read-only — never modifies source_file[] or feature_spec[] + ] + NEXT: Add missing markers → push fix → CI re-runs → merge when PASS +``` + +--- + +### Journey 20: Cross-Workspace Traceability Navigation + +```text +ALGORITHM CrossWorkspaceTraceabilityNavigation + ACTOR: Tech Lead, Architect + GOAL: In a multi-repo Workspace, trace an Object ID from its definition + in one repo to all its usages across all registered Workspace sources, + and assess blast radius before making a change + INPUTS: [ + Workspace Object — initialized with registered sources (multi-repo), + Object ID to investigate, + All Workspace sources reachable via Connectors + ] + OUTPUTS: [ + Definition location (Object + source repo), + All usage Objects across Workspace sources, + Object content (full specification block), + Recommendation[] per cross-workspace dependency gap + ] + COST TIER: low (object_graph_retriever hybrid; read-only) + AUTOMATION GATE: none (read-only Retriever and Analyzer Workers) + STEPS: + 1. Confirm Workspace Object is configured with registered sources synced + (connector_inbound_sync_worker has run for all sources). + 2. invoke object_graph_retriever (object_graph scope: workspace, hybrid, + on_demand): + Input: Object ID query + Workspace scope + Output: Object definition location (source repo, file, Object type), + all Objects referencing this ID across Workspace sources + WorkerRun created; state: pending → running → done + 3. invoke document_retriever (document_index, workspace scope, on_demand): + Input: Object ID + Output: full specification content of the Object + WorkerRun created; state: pending → running → done + 4. traceability_analysis Analyzer runs (hybrid, on_demand): + Input: Object ID + Workspace scope + Maps full dependency chain across all registered sources: + prd → design → decomposition → feature_spec → source_file[] + → pull_request[] chains (per repo) + Identifies cross-repo dependencies and broken chains + Creates Recommendation per unresolved cross-workspace link + WorkerRun created; state: pending → running → done + 5. Assess blast radius: + How many Objects and source repos reference this ID? + Which repos have stale Objects (stale_artifact_detection output)? + WorkerInteraction (kind: free_form_intent) — optional: + Architect annotates findings for the team + 6. DECISION: Planning a change? + YES: proceed to Journey 13 (change impact analysis) on the upstream + Object containing this ID + NO: navigation complete; use findings for review or documentation + 7. DECISION: Navigation scope? + SINGLE ID DEEP-DIVE: full chain for one Object ID + BREADTH SCAN: object_graph_retriever queries all IDs of a kind + (e.g., all prd fr[] IDs) across Workspace + DECISION_POINTS: + - PlanningChange: yes (→ Journey 13) / no (navigation complete) + - NavigationScope: single ID deep-dive / breadth scan of a kind + - IncludeCodeScan: include source_file[] scan in workspace query + GUARDS: [ + All Workspace sources must be synced (connector_inbound_sync_worker ran) + before cross-workspace queries run, + All operations are read-only — no Object modifications, + object_graph_retriever scoped to Workspace boundary; cannot query + outside registered sources + ] + NEXT: Journey 13 (if change is planned), or update Object referencing this ID +``` + +--- + +### Journey 21: Interactive Kit Update + +```text +ALGORITHM InteractiveKitUpdate + ACTOR: Developer, Tech Lead + GOAL: Update an installed Kit to the latest version, reviewing each + changed Worker/Flow/GTS-type/Connector definition via + WorkerInteraction (kind: menu) before accepting changes + INPUTS: [ + Installed Kit (.cf-studio-kit.toml on disk), + Upstream Kit source (Kit Registry, local path, or GitHub ref), + Workspace with Kit installed + ] + OUTPUTS: [ + Updated Kit files on disk (only accepted changes), + .cf-studio-kit.toml reflecting new Kit version, + ValidationSession + Evidence (Kit validation after update), + WorkerRun audit trail of per-file decisions + ] + COST TIER: low (Kit version check script + WorkerInteraction menus) + AUTOMATION GATE: approved_automation (Kit install Worker writes to graph) + STEPS: + 1. Kit version check Worker runs (script, on_demand): + Compares installed Kit version against upstream Registry + Output: update summary (new version, changed files, breaking changes) + WorkerRun created; state: pending → running → done + 2. DECISION: Proceed with update? + WorkerInteraction (kind: menu) created: + Options: [proceed, skip (defer update), show changelog] + Tech Lead selects → WorkerRun resumes + 3. For each changed file in the Kit update: + WorkerInteraction (kind: menu) created per file: + Shows diff of upstream vs local file + Options: [accept upstream, keep existing, diff and edit merged result] + WorkerRun.state → awaiting_input; Developer responds + WorkerRun resumes; decision recorded in WorkerRun audit trail + 4. Kit install Worker writes only accepted / merged files: + WorkerRun created; state: pending → running → done + Only files with accept/merge decision are written; + declined files preserved exactly as-is + 5. Kit validation Worker runs (script, realtime): + ValidationSession created + Checks: manifest schema valid, all component references resolve, + no dangling GTS type dependencies, Worker contracts consistent + On pass: Evidence attached to Kit install WorkerRun + On fail: WorkerInteraction (kind: input_request) for resolution; + validation re-runs + 6. DECISION: Regenerate dependent Workers? + YES (if Kit update changes WorkerImplementation configs): + Affected Worker definitions updated in Tenant registry; + active WorkerRuns not affected (in-flight runs use prior version) + NO: Kit update complete without Worker regeneration + 7. Tech Lead tests updated Kit behavior in a representative journey run. + DECISION_POINTS: + - ProceedWithUpdate: proceed / skip / show changelog + - PerFileDecision: accept upstream / keep existing / diff and edit + (WorkerInteraction per file) + - RegenerateWorkers: yes / no + GUARDS: [ + Declined files are never overwritten — WorkerInteraction decision is binding, + Merged/edited files written only after Developer confirms edit in + WorkerInteraction, + Kit ValidationSession must pass (Evidence attached) after update before + Kit Workers can be invoked, + Active in-flight WorkerRuns use the prior Kit version; no mid-run + Kit hot-swap + ] + NEXT: Test updated Kit Workers in a representative journey +``` + +--- + +### Journey 22: Object Graph Navigation + +```text +ALGORITHM ObjectGraphNavigation + ACTOR: Developer, Architect + GOAL: Understand the full traceability picture for a given feature area + — enumerate Object IDs, find definitions, find usages, read content + — before making a change or designing an extension + INPUTS: [ + Feature area or subsystem of interest, + Workspace with registered artifacts and sources, + Object types of interest (prd fr[], design component[], feature_spec + flow[], source_file[] markers) + ] + OUTPUTS: [ + List of all Object IDs in the area (by type), + Definition Objects (source repo, type, content), + Usage Objects across artifacts and source_file[], + Content of relevant Object specification blocks, + Recommendation[] per traceability gap found + ] + COST TIER: low (object_graph_retriever hybrid + traceability_analysis; + read-only, no LLM authoring) + AUTOMATION GATE: none (read-only Retriever and Analyzer Workers) + STEPS: + 1. invoke object_graph_retriever (object_graph scope: workspace, hybrid, + on_demand): + Input: feature area query + Object type filter + Output: all Objects in scope by type + (prd fr[], design component[], feature_spec flow[], task[]) + WorkerRun created; state: pending → running → done + 2. For each Object ID of interest: + invoke object_graph_retriever scoped to single Object ID: + Output: definition Object (location, type, content preview) + All Objects referencing this ID (usages across artifacts) + WorkerRun created; state: pending → running → done + 3. invoke document_retriever (document_index, workspace scope, on_demand): + Input: Object ID + Output: full specification content of the Object block + WorkerRun created; state: pending → running → done + 4. DECISION: Include source_file[] code-level scan? + YES: invoke code_retriever (code_index, workspace scope, on_demand): + Input: Object ID + Output: source_file[] locations where this ID is referenced + (traceability markers, test cases) + WorkerRun created; state: pending → running → done + NO: artifact-level navigation complete + 5. traceability_analysis Analyzer runs (hybrid, on_demand): + Input: Object IDs enumerated in step 1 + workspace scope + Maps full artifact → code traceability chains + Creates Recommendation per broken or missing link in the chain + WorkerRun created; state: pending → running → done + 6. DECISION: Planning a change? + YES: proceed to Journey 13 (change impact analysis) on the upstream + Object; use graph navigation findings as baseline + NO: navigation complete; findings used for review or documentation + 7. DECISION: Navigation depth? + SINGLE ID DEEP-DIVE: full chain trace for one Object ID + BREADTH SCAN: all Object IDs of a kind in the feature area + DECISION_POINTS: + - IncludeCodeScan: include code_retriever scan / artifact-level only + - NavigationDepth: single ID deep-dive / breadth scan of a kind + - PlanningChange: yes (→ Journey 13) / no (navigation complete) + GUARDS: [ + All operations are read-only — no Object modifications, + object_graph_retriever scoped to Workspace boundary, + traceability_analysis Recommendations created only for persistent gaps; + auto-invalidated when gap closes + ] + NEXT: Journey 13 (change impact), Journey 12 (implement missing markers), + or Journey 15 (reconstruct missing SDLC artifacts) +``` + +--- + +## Cross-Journey Patterns + +The twenty-two journeys above share a set of recurring structural patterns. Understanding +these patterns helps teams reason about how Studio v2 Workers compose and how quality +gates propagate across the system. + +### Worker-Chain Pattern + +Journeys 1, 9, 10, 11, 12, and 16 all chain multiple Workers sequentially where the +output Object of one Worker becomes the input to the next (via `Worker.inputBindings: +source chain`). The chain is explicit: `create_prd_worker` → `create_design_worker` → +`decompose_feature_worker` → `create_feature_spec_worker` → `implement_code_worker` +→ `create_pr_worker`. Each step creates a WorkerRun with a clear audit trail. If any +step fails or is cancelled, downstream Workers are not invoked until the upstream +WorkerRun reaches state: done. + +### Validator-First Quality Gate + +Every journey that advances an Object to a new state passes through a Validator gate +before the StatePolicy transition can occur. Validators (gap_analysis_validator, +pr_design_validator, adr_structure_validator, traceability_coverage_validator) produce +ValidationSessions and immutable Evidence attached to the Object. Evidence is the +precondition for state advancement. Retries are bounded by `Validator.maxRetries`; when +exhausted, an Approval (kind: risk_acceptance) is required. Validators run at any +automationLevel — they are never gated on approved_automation. + +### automationLevel Dial + +Journeys 1, 5, 7, 9, 10, 11, and 12 require `automationLevel >= approved_automation` +for action Workers (Workers that write Objects or write back to external systems). +Read-only Analyzers and Validators (Journeys 13, 14, 18, 19, 20, 22) run at any +automationLevel. Journey 21 (Kit Update) uses approved_automation for the Kit install +write. The automationLevel dial can be shown at Flow start via WorkerInteraction +(kind: menu) allowing the user to explicitly confirm the level for the current run +before any action Worker executes. + +### Connector-Mediated Objects + +Most journeys include Objects synced from external systems (`[sync: jira]`, +`[sync: github]`, `[sync: pagerduty]`, `[sync: confluence]`). These Objects carry +`externalRef` with `connectorId`, `externalId`, `externalUrl`, and `lastSyncedAt`. +Workers operate on Studio Objects regardless of origin — the Connector handles the +sync boundary. Connector inbound sync is performed by `connector_inbound_sync_worker` +(script, platform Worker). Outbound write-back uses `connector_outbound_sync_worker` +subject to Gate 2 (WriteBackPolicy). + +### WorkerInteraction Mid-Run + +All LLM and hybrid Workers can pause mid-run by emitting a WorkerInteraction +(kind: input_request | menu | free_form_intent). The WorkerRun transitions to +`awaiting_input`. The user responds. The WorkerRun resumes with the response injected +into context. This pattern replaces the v1 concept of "findings browsers" and +per-step modal dialogs — it is a uniform mid-run pause mechanism that works the +same way across all Worker types and all journeys. + +### Evidence Audit Trail + +Every Validator-gated transition produces Evidence attached to the Object. Every +WorkerRun records `externalEvents[]` write-ahead before execution. Every Approval +records `decidedBy` and `decidedAt`. Every WorkerInteraction records the user response +and timestamp. The combination forms a complete, immutable audit trail from initial +intent (WorkerInteraction free_form_intent) through every intermediate Object state +transition to the final write-back to external systems. This audit trail is always +persisted in the Object graph — there is no "session-only" mode for WorkerRun outputs. diff --git a/v2/poc/ui-1/index.html b/v2/poc/ui-1/index.html new file mode 100644 index 00000000..c54c10e8 --- /dev/null +++ b/v2/poc/ui-1/index.html @@ -0,0 +1,32 @@ + + + + + + + Constructor Studio v2 + + + + + + + + +
+ + + diff --git a/v2/poc/ui-1/package.json b/v2/poc/ui-1/package.json new file mode 100644 index 00000000..df5659f9 --- /dev/null +++ b/v2/poc/ui-1/package.json @@ -0,0 +1,30 @@ +{ + "name": "constructor-studio-v2-poc", + "version": "0.1.0", + "private": true, + "scripts": { + "dev": "vite", + "build": "tsc && vite build", + "preview": "vite preview" + }, + "dependencies": { + "@monaco-editor/react": "^4.6.0", + "@xyflow/react": "^12.3.6", + "framer-motion": "^11.3.0", + "lucide-react": "^0.400.0", + "react": "^18.3.1", + "react-dom": "^18.3.1", + "zustand": "^4.5.4" + }, + "devDependencies": { + "@types/react": "^18.3.3", + "@types/react-dom": "^18.3.0", + "@vitejs/plugin-react": "^4.3.1", + "typescript": "^5.4.5", + "vite": "^5.3.1" + }, + "allowScripts": { + "esbuild@0.21.5": true, + "fsevents@2.3.3": true + } +} diff --git a/v2/poc/ui-1/src/App.tsx b/v2/poc/ui-1/src/App.tsx new file mode 100644 index 00000000..31c4dbb0 --- /dev/null +++ b/v2/poc/ui-1/src/App.tsx @@ -0,0 +1,118 @@ +import { ReactFlowProvider } from '@xyflow/react' +import { useAppStore } from './store/app-store' +import { TopBar } from './components/layout/TopBar' +import { Sidebar } from './components/layout/Sidebar' +import { RightPanel } from './components/layout/RightPanel' +import { ObjectGraph } from './components/graph/ObjectGraph' +import { ActivityFeed } from './components/workers/ActivityFeed' +import { FlowsView } from './components/flows/FlowsView' +import { RecommendationsPanel } from './components/recommendations/RecommendationsPanel' +import { WorkerRunSimulator } from './components/workers/WorkerRunSimulator' +import { WorkersMonitor } from './components/workers/WorkersMonitor' +import { WorkersCatalog } from './components/workers/WorkersCatalog' +import { AgenticLoopView } from './components/workers/AgenticLoopView' +import { WorkerInteractionModal } from './components/workers/WorkerInteractionModal' +import { FileTree } from './components/files/FileTree' +import { FileViewer } from './components/files/FileViewer' +import { LineActionBar } from './components/files/LineActionBar' +import { KitsView } from './components/kits/KitsView' +import { WorkspacesView } from './components/workspaces/WorkspacesView' +import { ChatView } from './components/chat/ChatView' +import { BottomPanel } from './components/chat/BottomPanel' + +export default function App() { + const activeView = useAppStore(s => s.activeView) + + return ( +
+ {/* Top bar */} + + + {/* Main layout */} +
+ {/* Left sidebar */} + + + {/* Main content */} +
+ {activeView === 'graph' && ( + + + + )} + + {activeView === 'flows' && ( +
+ +
+ )} + + {activeView === 'activity' && ( +
+
+

Activity Feed

+

All worker runs across this workspace

+
+ +
+ )} + + {activeView === 'recommendations' && ( +
+ +
+ )} + + {activeView === 'files' && ( +
+ + +
+ )} + + {activeView === 'kits' && ( +
+ +
+ )} + + {activeView === 'workspaces' && ( +
+ +
+ )} + + {activeView === 'workers' && ( +
+ +
+ )} + + {activeView === 'catalog' && ( +
+ +
+ )} + + {activeView === 'loop' && ( +
+ +
+ )} + +
+ + {/* Right panel (slides in) */} + +
+ + {/* Bottom AI Chat panel */} + + + {/* Floating overlays */} + + + +
+ ) +} diff --git a/v2/poc/ui-1/src/components/chat/BottomPanel.tsx b/v2/poc/ui-1/src/components/chat/BottomPanel.tsx new file mode 100644 index 00000000..4c43f4e7 --- /dev/null +++ b/v2/poc/ui-1/src/components/chat/BottomPanel.tsx @@ -0,0 +1,274 @@ +import { useRef, useCallback, useEffect, useState } from 'react' +import { motion, AnimatePresence } from 'framer-motion' +import { Cpu, X, Maximize2, Plus, ChevronDown, Pencil, Check } from 'lucide-react' +import { useAppStore } from '../../store/app-store' +import { ChatView } from './ChatView' + +const MIN_H = 240 +const MAX_H = 680 + +interface ChatTab { + id: string + title: string +} + +let tabCounter = 1 +function newTab(): ChatTab { + tabCounter++ + return { id: `tab-${Date.now()}`, title: `Chat ${tabCounter}` } +} + +export function BottomPanel() { + const chatOpen = useAppStore(s => s.chatOpen) + const chatHeight = useAppStore(s => s.chatHeight) + const toggleChat = useAppStore(s => s.toggleChat) + const setChatHeight = useAppStore(s => s.setChatHeight) + + const [tabs, setTabs] = useState([{ id: 'tab-1', title: 'Chat 1' }]) + const [activeTabId, setActiveTabId] = useState('tab-1') + const [editingTabId, setEditingTabId] = useState(null) + const [editTitle, setEditTitle] = useState('') + + const dragging = useRef(false) + const startY = useRef(0) + const startH = useRef(chatHeight) + + const onDragStart = useCallback((e: React.MouseEvent) => { + e.preventDefault() + dragging.current = true + startY.current = e.clientY + startH.current = chatHeight + document.body.style.cursor = 'ns-resize' + document.body.style.userSelect = 'none' + }, [chatHeight]) + + useEffect(() => { + const onMove = (e: MouseEvent) => { + if (!dragging.current) return + const delta = startY.current - e.clientY + setChatHeight(Math.max(MIN_H, Math.min(MAX_H, startH.current + delta))) + } + const onUp = () => { + if (!dragging.current) return + dragging.current = false + document.body.style.cursor = '' + document.body.style.userSelect = '' + } + window.addEventListener('mousemove', onMove) + window.addEventListener('mouseup', onUp) + return () => { window.removeEventListener('mousemove', onMove); window.removeEventListener('mouseup', onUp) } + }, [setChatHeight]) + + useEffect(() => { + const onKey = (e: KeyboardEvent) => { + if ((e.metaKey || e.ctrlKey) && e.key === 'j') { e.preventDefault(); toggleChat() } + // Cmd/Ctrl+T → new tab (when chat open) + if ((e.metaKey || e.ctrlKey) && e.key === 't' && chatOpen) { e.preventDefault(); addTab() } + } + window.addEventListener('keydown', onKey) + return () => window.removeEventListener('keydown', onKey) + }, [toggleChat, chatOpen]) + + const addTab = () => { + if (!chatOpen) toggleChat() + const t = newTab() + setTabs(prev => [...prev, t]) + setActiveTabId(t.id) + } + + const closeTab = (id: string, e: React.MouseEvent) => { + e.stopPropagation() + setTabs(prev => { + if (prev.length === 1) return prev // keep at least one + const next = prev.filter(t => t.id !== id) + if (activeTabId === id) { + const idx = prev.findIndex(t => t.id === id) + setActiveTabId(next[Math.max(0, idx - 1)].id) + } + return next + }) + } + + const startRename = (tab: ChatTab, e: React.MouseEvent) => { + e.stopPropagation() + setEditingTabId(tab.id) + setEditTitle(tab.title) + } + + const commitRename = () => { + if (editingTabId && editTitle.trim()) { + setTabs(prev => prev.map(t => t.id === editingTabId ? { ...t, title: editTitle.trim() } : t)) + } + setEditingTabId(null) + } + + return ( +
+ {/* Tab bar */} +
+ {/* Drag handle */} + {chatOpen && ( +
+
+
+ )} + + {/* AI icon */} +
+ +
+ + {/* Tabs */} + {tabs.map(tab => { + const isActive = tab.id === activeTabId + const isEditing = editingTabId === tab.id + return ( +
{ if (!chatOpen) toggleChat(); setActiveTabId(tab.id) }} + style={{ + display: 'flex', alignItems: 'center', gap: 5, + padding: '0 10px', height: '100%', cursor: 'pointer', flexShrink: 0, + background: isActive && chatOpen ? 'rgba(99,102,241,0.1)' : 'transparent', + borderRight: '1px solid rgba(63,63,70,0.35)', + borderBottom: isActive && chatOpen ? '2px solid #6366f1' : '2px solid transparent', + color: isActive && chatOpen ? '#a5b4fc' : '#52525b', + fontSize: 12, fontWeight: isActive ? 500 : 400, + transition: 'all 0.12s', minWidth: 80, maxWidth: 160, + position: 'relative', + }} + > + {isEditing ? ( + setEditTitle(e.target.value)} + onBlur={commitRename} + onKeyDown={e => { if (e.key === 'Enter') commitRename(); if (e.key === 'Escape') setEditingTabId(null) }} + onClick={e => e.stopPropagation()} + style={{ + width: 90, fontSize: 11, background: 'rgba(99,102,241,0.15)', + border: '1px solid rgba(99,102,241,0.4)', borderRadius: 4, + color: '#e4e4e7', padding: '1px 4px', outline: 'none', + }} + /> + ) : ( + startRename(tab, e)} + title="Double-click to rename" + > + {tab.title} + + )} + {/* Close button — only show on hover or when multiple tabs */} + {tabs.length > 1 && ( + + )} +
+ ) + })} + + {/* New tab button */} + + + {/* Spacer */} +
+ + {/* Controls */} +
+ ⌘J + {chatOpen && ( + + )} + +
+
+ + {/* Panel body — render all tabs, show only active */} + + {chatOpen && ( + +
+ {tabs.map(tab => ( +
+ {/* ChatView keyed by tabId so each tab has independent state */} + +
+ ))} +
+ + )} + +
+ ) +} diff --git a/v2/poc/ui-1/src/components/chat/ChatView.tsx b/v2/poc/ui-1/src/components/chat/ChatView.tsx new file mode 100644 index 00000000..409e240b --- /dev/null +++ b/v2/poc/ui-1/src/components/chat/ChatView.tsx @@ -0,0 +1,773 @@ +import { useState, useRef, useEffect, useCallback } from 'react' +import { motion, AnimatePresence } from 'framer-motion' +import { Send, Cpu, Loader2, CheckCircle2, XCircle, ChevronDown, Zap, AlertTriangle, GitBranch, FileText, Search, Wrench, TestTube2, Link2, X, Settings2, MessageSquare, ChevronRight } from 'lucide-react' +import { useAppStore } from '../../store/app-store' +import { WORKER_DEFS, MOCK_RECOMMENDATIONS, MOCK_OBJECTS } from '../../data/mock-data' + +// ─── Chat config types ──────────────────────────────────────────────────────── + +type ModelId = 'claude-sonnet-4-6' | 'claude-opus-4-8' | 'claude-haiku-4-5' +type ChatMode = 'normal' | 'extended_thinking' | 'code_focus' | 'autonomous' +type ReasoningEffort = 'low' | 'medium' | 'high' | 'max' +type ContextWindow = '8k' | '32k' | '200k' | '1m' + +interface ChatConfig { + model: ModelId + mode: ChatMode + effort: ReasoningEffort + context: ContextWindow +} + +const MODELS: { id: ModelId; label: string; description: string; tier: 'fast' | 'balanced' | 'powerful' }[] = [ + { id: 'claude-haiku-4-5', label: 'Haiku 4.5', description: 'Fastest, lowest cost', tier: 'fast' }, + { id: 'claude-sonnet-4-6', label: 'Sonnet 4.6', description: 'Balanced speed & quality', tier: 'balanced' }, + { id: 'claude-opus-4-8', label: 'Opus 4.8', description: 'Most capable, slowest', tier: 'powerful' }, +] + +const MODES: { id: ChatMode; label: string; description: string }[] = [ + { id: 'normal', label: 'Normal', description: 'Standard responses' }, + { id: 'extended_thinking', label: 'Extended Thinking', description: 'Visible reasoning chain' }, + { id: 'code_focus', label: 'Code Focus', description: 'Optimised for code tasks' }, + { id: 'autonomous', label: 'Autonomous', description: 'Agent acts without confirmation' }, +] + +const EFFORTS: { id: ReasoningEffort; label: string; tokens: string }[] = [ + { id: 'low', label: 'Low', tokens: '~1k' }, + { id: 'medium', label: 'Medium', tokens: '~8k' }, + { id: 'high', label: 'High', tokens: '~32k' }, + { id: 'max', label: 'Max', tokens: '~64k' }, +] + +const CONTEXTS: { id: ContextWindow; label: string; description: string }[] = [ + { id: '8k', label: '8k', description: 'Light — quick tasks' }, + { id: '32k', label: '32k', description: 'Standard' }, + { id: '200k', label: '200k', description: 'Large — full codebase' }, + { id: '1m', label: '1M', description: 'Maximum — entire repo' }, +] + +const DEFAULT_CONFIG: ChatConfig = { model: 'claude-sonnet-4-6', mode: 'normal', effort: 'medium', context: '32k' } + +// ─── Config Tab ─────────────────────────────────────────────────────────────── + +function ConfigTab({ config, onChange }: { config: ChatConfig; onChange: (c: ChatConfig) => void }) { + function Section({ title, children }: { title: string; children: React.ReactNode }) { + return ( +
+

{title}

+ {children} +
+ ) + } + + function OptionGrid({ items, value, onChange: onChg, renderLabel }: { + items: { id: T; label: string; description?: string }[] + value: T + onChange: (v: T) => void + renderLabel?: (item: { id: T; label: string; description?: string }) => React.ReactNode + }) { + return ( +
+ {items.map(item => ( + + ))} +
+ ) + } + + const tierColor = { fast: '#10b981', balanced: '#6366f1', powerful: '#f59e0b' } + + return ( +
+
+ onChange({ ...config, model: m })} + renderLabel={item => ( + <> +
+ +

{item.label}

+
+

{item.description}

+ + )} + /> +
+ +
+ onChange({ ...config, mode: m })} /> +
+ +
+
+ {EFFORTS.map(e => ( + + ))} +
+ {(config.effort === 'high' || config.effort === 'max') && ( +

+ ⚠ Higher effort increases latency and cost +

+ )} +
+ +
+
+ {CONTEXTS.map(c => ( + + ))} +
+
+ + {/* Summary */} +
+

Current Config

+
+ {[ + { label: MODELS.find(m => m.id === config.model)?.label ?? config.model, color: '#818cf8' }, + { label: MODES.find(m => m.id === config.mode)?.label ?? config.mode, color: '#a78bfa' }, + { label: `Effort: ${config.effort}`, color: '#6ee7b7' }, + { label: `${config.context} ctx`, color: '#fbbf24' }, + ].map(b => ( + + {b.label} + + ))} +
+
+
+ ) +} + +// ─── Types ──────────────────────────────────────────────────────────────────── + +type Role = 'user' | 'assistant' +type MsgKind = 'text' | 'tool_use' | 'tool_result' | 'suggestion_row' + +interface ToolCall { + workerId: string + workerLabel: string + status: 'running' | 'done' | 'failed' + objectTitle?: string + output?: string + costUsd?: number + durationMs?: number +} + +interface Message { + id: string + role: Role + kind: MsgKind + text?: string + streaming?: boolean + toolCall?: ToolCall + suggestions?: SlashCommand[] +} + +interface SlashCommand { + cmd: string + label: string + description: string + icon: React.ReactNode + workerId?: string +} + +// ─── Slash commands ─────────────────────────────────────────────────────────── + +const SLASH_COMMANDS: SlashCommand[] = [ + { cmd: '/analyze', label: '/analyze', description: 'Run gap analysis on selected object', icon: , workerId: 'gap_analysis_validator' }, + { cmd: '/trace', label: '/trace', description: 'Run traceability analysis', icon: , workerId: 'traceability_analysis' }, + { cmd: '/implement', label: '/implement', description: 'Implement code for selected feature/task', icon: , workerId: 'implement_code_worker' }, + { cmd: '/design', label: '/design', description: 'Create design from PRD', icon: , workerId: 'create_design_worker' }, + { cmd: '/test', label: '/test', description: 'Generate tests for selected object', icon: , workerId: 'implement_code_worker' }, + { cmd: '/decompose', label: '/decompose', description: 'Decompose design into tasks', icon: , workerId: 'decompose_feature_worker' }, + { cmd: '/validate', label: '/validate', description: 'Validate PR against design', icon: , workerId: 'pr_design_validator' }, + { cmd: '/security', label: '/security', description: 'Run security impact analysis', icon: , workerId: 'security_impact_analysis' }, + { cmd: '/recs', label: '/recs', description: 'List active recommendations', icon: }, + { cmd: '/score', label: '/score', description: 'Show quality score for selected object', icon: }, + { cmd: '/explain', label: '/explain', description: 'Explain the selected object in plain language', icon: }, +] + +// ─── AI response generator ──────────────────────────────────────────────────── + +function generateResponse(input: string, selectedObjectId: string | null): { text: string; workerId?: string } { + const lower = input.toLowerCase().trim() + const selectedObj = selectedObjectId ? MOCK_OBJECTS.find(o => o.id === selectedObjectId) : null + const objName = selectedObj?.title ?? 'the workspace' + + if (lower.startsWith('/recs') || lower.includes('recommendation')) { + const recs = MOCK_RECOMMENDATIONS.filter(r => r.state === 'pending') + return { text: `Found **${recs.length} active recommendations** in the workspace:\n\n${recs.map(r => `- **${r.severity.toUpperCase()}** — ${r.title}`).join('\n')}\n\nWould you like me to accept and run any of these?` } + } + if (lower.startsWith('/score') || lower.includes('quality score') || lower.includes('health')) { + if (selectedObj) { + const scores: Record = { 'prd-001': 82, 'design-001': 78, 'adr-001': 91, 'task-001': 70, 'fspec-001': 88, 'fspec-002': 45, 'pr-001': 72, 'incident-001': 40 } + const score = scores[selectedObj.id] ?? 65 + const label = score >= 80 ? 'Good' : score >= 60 ? 'Needs attention' : 'Critical' + return { text: `**Quality Score for ${selectedObj.title}: ${score}/100** (${label})\n\nKey signals:\n- **State:** ${selectedObj.state}\n- **Validation:** ${selectedObj.validationStatus}\n- **Staleness:** ${selectedObj.stalenessScore}%\n- **Links:** ${selectedObj.links.length} connected objects\n\nOpen the **Score tab** in the right panel for full charts and trends.` } + } + return { text: 'Please select an object in the graph first to see its quality score.' } + } + if (lower.startsWith('/explain') || lower.includes('explain') || lower.includes('what is')) { + if (selectedObj) { + const typeDescriptions: Record = { + prd: 'a **Product Requirements Document** — defines actors, functional/non-functional requirements, use cases, and success criteria that downstream SDLC artifacts must satisfy.', + design: 'a **System Design** artifact — specifies components, interfaces, architecture drivers, and constraints. Implementation tasks and PRs must conform to it.', + adr: 'an **Architecture Decision Record** — documents a significant architectural choice with context, options, decision outcome, and consequences.', + task: 'a **Development Task** — a concrete unit of implementation work linked to a feature spec and covered by at least one requirement ID.', + feature_spec: 'a **Feature Specification** — GIVEN/WHEN/THEN flows, algorithms, test scenarios, and Definition of Done for one task scope.', + pull_request: 'a **Pull Request** — implementation artifact validated against the design. Evidence from pr_design_validator must be attached before merge.', + incident: 'an **Incident** — a production event requiring root cause analysis, postmortem, and prevention tasks.', + build: 'a **Build artifact** — CI/CD execution result linked to commits and deployments.', + } + return { text: `**${selectedObj.title}** is ${typeDescriptions[selectedObj.typeId] ?? 'a Studio object'}\n\nCurrent state: **${selectedObj.state}** · Validation: **${selectedObj.validationStatus}**\n\n${selectedObj.description ?? ''}` } + } + return { text: 'Select an object in the graph to explain it.' } + } + if (lower.includes('traceability') || lower.includes('coverage') || lower.includes('trace')) { + return { text: `**Traceability Coverage Analysis** for ${objName}:\n\nThe current SDLC chain looks like:\n\`\`\`\nPRD (87% covered) → Design (92%) → Tasks (78%) → PRs (80%)\n\`\`\`\n\nGaps detected:\n- R-005 in PRD has no linked test case\n- Invoice Generation feature spec not approved\n- Event-driven pattern (ADR-001) has no code implementation\n\nShall I run \`/trace\` to get a full analysis?`, workerId: undefined } + } + if (lower.includes('cost') || lower.includes('spend') || lower.includes('expensive')) { + return { text: `**AI Cost Summary** for workspace:\n\nTotal spent this month: **$4.82**\n\nBy artifact:\n- task-001 (Stripe Webhook): $1.35 — 5 runs\n- design-001 (Architecture): $0.82 — 5 runs\n- prd-001 (Billing PRD): $0.66 — 4 runs\n- fspec-001 (Stripe Flow): $0.50 — 2 runs\n\nMost expensive worker: **implement_code_worker** ($0.71 avg)\nCheapest: **gap_analysis_validator** ($0.07 avg)` } + } + if (lower.includes('help') || lower === '?') { + return { text: `I'm the **Constructor Studio AI Agent**. I can help you:\n\n**Run workers** — type \`/analyze\`, \`/trace\`, \`/implement\`, \`/design\`, \`/validate\`\n\n**Query the graph** — ask about objects, links, recommendations, costs\n\n**Navigate** — "show me critical issues", "what tasks are in progress?"\n\n**Explain** — "explain this design", "what is a feature spec?"\n\nSelect an object in the graph for context, or just ask!` } + } + if (lower.includes('critical') || lower.includes('problem') || lower.includes('issue') || lower.includes('broken')) { + return { text: `**Critical issues in workspace:**\n\n🔴 **fspec-002** (Invoice Generation Flow) — no test scenarios, missing algo blocks, feature spec not approved\n🔴 **incident-001** (INC-441) — no postmortem, root cause not identified\n🔴 **decomp-001** — tasks missing prd fr[] coverage\n\n⚠️ **task-001** — no traceability markers in source code\n⚠️ **design-001** — event bus pattern not implemented\n\nWould you like me to create a remediation plan?` } + } + if (lower.includes('task') && (lower.includes('progress') || lower.includes('status'))) { + return { text: `**Task status overview:**\n\n- ✅ task-003 (Schema Migration) — **done**\n- 🟡 task-001 (Stripe Webhook) — **in_progress** · PR in review\n- 📋 task-002 (Invoice Generation) — **planned** · no feature spec yet\n\nBlocker: task-002 is waiting on an approved feature spec. Run \`/design\` or \`/decompose\` to unblock it.` } + } + if (selectedObj) { + return { text: `I can see you have **${selectedObj.title}** selected (${selectedObj.typeId}, state: ${selectedObj.state}).\n\nWhat would you like to do? I can:\n- Run \`/analyze\` to check for gaps\n- Run \`/trace\` for traceability coverage\n- Run \`/explain\` for a plain-language summary\n- Show the Score tab for quality metrics` } + } + return { text: `I'm your Studio AI agent. Select an object in the graph for context, or ask me about the workspace. Type \`/\` to see available commands.` } +} + +// ─── Message components ─────────────────────────────────────────────────────── + +function StreamingText({ text, onDone }: { text: string; onDone: () => void }) { + const [displayed, setDisplayed] = useState('') + const [done, setDone] = useState(false) + const idx = useRef(0) + + useEffect(() => { + idx.current = 0 + setDisplayed('') + setDone(false) + const interval = setInterval(() => { + idx.current += Math.floor(Math.random() * 4) + 2 + if (idx.current >= text.length) { + setDisplayed(text) + setDone(true) + clearInterval(interval) + onDone() + } else { + setDisplayed(text.slice(0, idx.current)) + } + }, 18) + return () => clearInterval(interval) + }, [text]) + + return +} + +function FormattedText({ text }: { text: string }) { + const parts = text.split(/(\*\*[^*]+\*\*|`[^`]+`|\n)/g) + return ( + + {parts.map((p, i) => { + if (p === '\n') return
+ if (p.startsWith('**') && p.endsWith('**')) return {p.slice(2, -2)} + if (p.startsWith('`') && p.endsWith('`')) return {p.slice(1, -1)} + return {p} + })} + + ) +} + +function ToolCard({ toolCall }: { toolCall: ToolCall }) { + return ( +
+
+ {toolCall.status === 'running' && } + {toolCall.status === 'done' && } + {toolCall.status === 'failed' && } + {toolCall.workerLabel} + {toolCall.objectTitle && on {toolCall.objectTitle}} +
+ {toolCall.costUsd && ${toolCall.costUsd.toFixed(2)}} + {toolCall.durationMs && {(toolCall.durationMs / 1000).toFixed(1)}s} +
+
+ {toolCall.output && ( +

+ {toolCall.output} +

+ )} +
+ ) +} + +function AssistantBubble({ msg, onStreamDone }: { msg: Message; onStreamDone: (id: string) => void }) { + return ( +
+
+ +
+
+ {msg.toolCall && } + {msg.text && ( +
+ {msg.streaming + ? onStreamDone(msg.id)} /> + : + } +
+ )} +
+
+ ) +} + +function UserBubble({ msg }: { msg: Message }) { + return ( +
+
+ {msg.text} +
+
+ ) +} + +// ─── Slash command palette ──────────────────────────────────────────────────── + +function CommandPalette({ query, onSelect, onClose }: { + query: string + onSelect: (cmd: SlashCommand) => void + onClose: () => void +}) { + const filtered = SLASH_COMMANDS.filter(c => + c.cmd.includes(query.toLowerCase()) || c.description.toLowerCase().includes(query.toLowerCase()) + ) + if (filtered.length === 0) return null + return ( + +
+ Commands + +
+
+ {filtered.map(cmd => ( + + ))} +
+ + ) +} + +// ─── Main ChatView ──────────────────────────────────────────────────────────── + +let msgCounter = 1000 + +function uid() { return `msg-${Date.now()}-${msgCounter++}` } + +const WELCOME: Message = { + id: uid(), + role: 'assistant', + kind: 'text', + text: `Hello! I'm your **Constructor Studio AI Agent**.\n\nI can help you analyze objects, run workers, track recommendations, and navigate the SDLC graph.\n\nSelect an object in the graph for context, or type \`/\` to see available commands.`, +} + +type ChatTab = 'chat' | 'config' + +export function ChatView() { + const selectedObjectId = useAppStore(s => s.selectedObjectId) + const runWorker = useAppStore(s => s.runWorker) + const objects = useAppStore(s => s.objects) + + const [tab, setTab] = useState('chat') + const [config, setConfig] = useState(DEFAULT_CONFIG) + const [messages, setMessages] = useState([WELCOME]) + const [input, setInput] = useState('') + const [showPalette, setShowPalette] = useState(false) + const [loading, setLoading] = useState(false) + const bottomRef = useRef(null) + const inputRef = useRef(null) + + const selectedObj = selectedObjectId ? objects.find(o => o.id === selectedObjectId) : null + + useEffect(() => { + bottomRef.current?.scrollIntoView({ behavior: 'smooth' }) + }, [messages]) + + const addMsg = (msg: Omit) => { + const m = { ...msg, id: uid() } + setMessages(prev => [...prev, m]) + return m.id + } + + const updateMsg = (id: string, patch: Partial) => { + setMessages(prev => prev.map(m => m.id === id ? { ...m, ...patch } : m)) + } + + const streamDone = useCallback((id: string) => { + updateMsg(id, { streaming: false }) + }, []) + + const executeCommand = async (cmd: SlashCommand, fullInput: string) => { + setLoading(true) + + if (cmd.workerId && selectedObjectId) { + // Tool use card — show running + const toolId = addMsg({ + role: 'assistant', kind: 'tool_use', + toolCall: { workerId: cmd.workerId, workerLabel: cmd.label, status: 'running', objectTitle: selectedObj?.title }, + }) + + // Simulate worker execution + runWorker(cmd.workerId, selectedObjectId) + + await new Promise(r => setTimeout(r, 2200)) + + const cost = (Math.random() * 0.3 + 0.05) + const duration = Math.floor(Math.random() * 4000 + 1500) + const outputs: Record = { + gap_analysis_validator: `Analysis complete. ${selectedObj?.validationStatus === 'pass' ? 'No critical gaps found.' : 'Found 2 gaps: missing test coverage for R-005, 1 use-case without acceptance criteria.'}`, + traceability_analysis: 'Traceability chain mapped. Coverage: PRD 87% → Design 92% → Code 80%. 3 broken links found.', + implement_code_worker: 'Implementation generated. 342 lines, @cpt- markers for all flow IDs. Review suggested.', + create_design_worker: 'System design created: 6 components, 12 API contracts, 3 Mermaid sequence diagrams.', + pr_design_validator: 'PR validated against design. ' + (Math.random() > 0.3 ? 'PASS — Evidence attached.' : 'FAIL — 1 finding: missing error handling.'), + security_impact_analysis: 'Security review complete. No critical vulnerabilities. Recommendation: add rate limiting on webhook endpoint.', + decompose_feature_worker: 'Decomposed into 4 tasks with dependency order. All tasks have Definition of Done.', + } + updateMsg(toolId, { + toolCall: { workerId: cmd.workerId, workerLabel: cmd.label, status: 'done', objectTitle: selectedObj?.title, output: outputs[cmd.workerId] ?? 'Worker completed successfully.', costUsd: cost, durationMs: duration }, + }) + + // Follow-up AI message + await new Promise(r => setTimeout(r, 300)) + addMsg({ + role: 'assistant', kind: 'text', + text: `Done! ${outputs[cmd.workerId] ?? 'Worker completed.'}\n\nYou can see full details in the **History tab** of the right panel.`, + streaming: true, + }) + } else if (cmd.cmd === '/recs' || cmd.cmd === '/score' || cmd.cmd === '/explain') { + const { text } = generateResponse(cmd.cmd, selectedObjectId) + await new Promise(r => setTimeout(r, 600)) + addMsg({ role: 'assistant', kind: 'text', text, streaming: true }) + } else if (cmd.workerId && !selectedObjectId) { + addMsg({ + role: 'assistant', kind: 'text', + text: `To run **${cmd.label}**, please select an object in the graph first. Click any node to select it.`, + streaming: true, + }) + } + + setLoading(false) + } + + const handleSubmit = async () => { + const trimmed = input.trim() + if (!trimmed || loading) return + + addMsg({ role: 'user', kind: 'text', text: trimmed }) + setInput('') + setShowPalette(false) + setLoading(true) + + // Check for slash command + const cmd = SLASH_COMMANDS.find(c => trimmed.toLowerCase().startsWith(c.cmd)) + if (cmd) { + await executeCommand(cmd, trimmed) + return + } + + // Regular AI response + await new Promise(r => setTimeout(r, 700 + Math.random() * 500)) + const { text } = generateResponse(trimmed, selectedObjectId) + addMsg({ role: 'assistant', kind: 'text', text, streaming: true }) + setLoading(false) + } + + const handleKeyDown = (e: React.KeyboardEvent) => { + if (e.key === 'Enter' && !e.shiftKey) { e.preventDefault(); handleSubmit() } + if (e.key === 'Escape') setShowPalette(false) + } + + const handleInputChange = (e: React.ChangeEvent) => { + const v = e.target.value + setInput(v) + setShowPalette(v === '/' || (v.startsWith('/') && !v.includes(' '))) + } + + const handleCommandSelect = (cmd: SlashCommand) => { + setInput(cmd.cmd + ' ') + setShowPalette(false) + inputRef.current?.focus() + } + + const clearChat = () => setMessages([WELCOME]) + + const currentModel = MODELS.find(m => m.id === config.model) + const tierColor = { fast: '#10b981', balanced: '#6366f1', powerful: '#f59e0b' } + + return ( +
+ {/* Header */} +
+ {/* Top row */} +
+
+ +
+
+

Studio AI

+
+ + {currentModel?.label} + · + {config.mode.replace('_', ' ')} + · + effort:{config.effort} + · + {config.context} ctx +
+
+ {selectedObj && ( + + {selectedObj.title.length > 14 ? selectedObj.title.slice(0, 14) + '…' : selectedObj.title} + + )} + {tab === 'chat' && ( + + )} +
+ {/* Tabs */} +
+ {([['chat', 'Chat', MessageSquare], ['config', 'Config', Settings2]] as const).map(([id, label, Icon]) => ( + + ))} +
+
+ + {/* Config tab */} + {tab === 'config' && } + + {/* Messages */} + {tab === 'chat' &&
+ {messages.map(msg => ( + + {msg.role === 'assistant' + ? + : + } + + ))} + {loading && !messages.find(m => m.streaming) && ( +
+
+ +
+
+ {[0, 1, 2].map(i => ( + + ))} +
+
+ )} +
+
} + + {/* Chat tab — quick chips + input */} + {tab === 'chat' && ( + <> +
+ {['/analyze', '/trace', '/explain', '/recs', '/score'].map(cmd => { + const c = SLASH_COMMANDS.find(s => s.cmd === cmd)! + return ( + + ) + })} +
+ +
+ + {showPalette && ( + setShowPalette(false)} + /> + )} + + +
+