From 05ea3f6d3cb95c56a025afdf5205b2f962d5781e Mon Sep 17 00:00:00 2001 From: ainetx Date: Thu, 2 Jul 2026 17:46:47 +0300 Subject: [PATCH 001/106] docs(v2): add Studio v2 vision deck and domain model Add initial v2 documentation artifacts: - v2/docs/STUDIO_VISION.md: investor-facing vision deck for Studio v2, covering the shadow SDLC graph, validated action engine, connector layer, killer workflows, competitive positioning, and expansion roadmap - v2/docs/domain-model.md: comprehensive domain model draft produced through structured brainstorm session, covering Object/Worker/Flow base model, GTS identifier conventions (vendor=cf), Contract schema, WorkerRun execution model, Tenant hierarchy, Kit extensibility, StatePolicy, Role/Policy/Authorization, AuditLog, Recommendation, Events/Notifications, and a full SDLC object type catalog (~95 core types across 16 domains) with 17 Mermaid diagrams Signed-off-by: ainetx --- v2/docs/STUDIO_VISION.md | 763 ++++++++++++++++++++ v2/docs/domain-model.md | 1469 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 2232 insertions(+) create mode 100644 v2/docs/STUDIO_VISION.md create mode 100644 v2/docs/domain-model.md 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..5c6a069f --- /dev/null +++ b/v2/docs/domain-model.md @@ -0,0 +1,1469 @@ +# Studio v2 — Domain Model + +> Status: **draft** — result of a brainstorm session, requires final validation. + +--- + +## Diagrams + +### D1 — System Overview: Registry vs Object Graph + +```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 +``` + +--- + +### 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 Tenant + class Workspace + class WorkerRun + class FlowRun + class Role + class Recommendation + + Object <|-- Tenant + Object <|-- Workspace + Object <|-- WorkerRun + Object <|-- FlowRun + Object <|-- Role + Object <|-- Recommendation +``` + +--- + +### D3 — Tenant Hierarchy & Isolation + +```mermaid +classDiagram + class Tenant { + 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 +``` + +--- + +### 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 +``` + +--- + +### 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"] +``` + +--- + +### 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"] +``` + +--- + +### 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 +``` + +--- + +### 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 +``` + +--- + +### D9 — Recommendation Lifecycle + +```mermaid +flowchart TD + AW["Analyzer Worker\n(schedule/onEvent/onDemand)"] -->|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)"] +``` + +--- + +### 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 +``` + +--- + +### 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 +``` + +--- + +### D13 — Prompt Type Hierarchy + +```mermaid +classDiagram + class prompt { + content: string + version: semver + } + + prompt <|-- skill + prompt <|-- system_prompt + prompt <|-- prompt_template + prompt <|-- prompt_variant +``` + +--- + +### 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 +``` + +--- + +### 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 +``` + +--- + +### 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 +``` + +--- + +### D17 — Security & Vulnerability Objects + +```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 +``` + +--- + +*Generated during Studio v2 Domain Model brainstorm session.* +*Date: 2026-07-02* + +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.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 +} +``` + +All object types are derived from the base `Object` via GTS chained IDs. + +### 1.2 Registry Entities + +Outside the graph. Describe rules and configurations, not data. + +| Entity | Purpose | +|---|---| +| `Worker` | Executor — consumes and produces Objects | +| `WorkerImplementation` | Runtime configuration of a Worker (model, prompt, script) | +| `Flow` | Configuration of constraints and mandatory steps | +| `Kit` | Extension packaging unit (types, Workers, Flows) | +| `obj_ext` | Attribute extension for existing types | + +--- + +## 2. GTS Identifiers + +**Convention:** `gts.....v` + +Studio vendor = `cf` (same as Constructor Fabric Gears). + +### 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 +gts.cf.studio.core.flow.v1~ ← base Flow +gts.cf.studio.core.obj_ext.v1~ ← attribute extension +gts.cf.studio.core.event.v1~ ← base Event type +``` + +### 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~ +``` + +### 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-*`). + +Describes what a Worker expects as input and what it produces as output. +Object type references use `$ref` → GTS Type Identifier. Scalar properties +are standard JSON Schema fields. + +```json +{ + "$id": "gts.cf.studio.core.worker.v1~cf.studio.core.create_design_input.v1~", + "type": "object", + "properties": { + "requirement": { + "$ref": "gts://cf.studio.core.object.v1~cf.studio.core.requirement.v1~", + "x-gts-required": true + }, + "workspace": { + "$ref": "gts://cf.studio.core.object.v1~cf.studio.core.workspace.v1~", + "x-gts-required": true + }, + "style": { "type": "string", "enum": ["detailed", "sketch"] }, + "language": { "type": "string" } + } +} +``` + +--- + +## 4. Worker + +Executor — consumes Objects, produces Objects. Registry entity. + +``` +Worker { + id: GTS Type Identifier (gts.cf.studio.core.worker.v1~...) + input: Contract (GTS Type Schema) + output: Contract (GTS Type Schema) + dependencies: Worker[] (static list — security boundary) + scope: local | project | workspace | published + implementationId: ref → WorkerImplementation + trigger?: { + schedule?: cron string + onEvent?: { + pattern: GTS Type Identifier + debounce: duration // default: 0 + } + onDemand: boolean // default: true + } +} +``` + +### 4.1 WorkerImplementation + +Runtime configuration, versioned independently from the contract. + +``` +WorkerImplementation { + id: string + version: semver + runtime: llm | script | hybrid + config: { + // llm: { model, prompt, temperature, ... } + // script: { entrypoint, language, ... } + // hybrid: { steps[] } + } + dependencies_mode: { + // workerId → { mode: sync | async } + } + checkpoint: { + enabled: boolean + ttl: duration + } + auditMode: sync | async // default: async + retentionPolicy: { + inputTTL: duration + outputTTL: duration + metadataTTL: duration + retentionAction: archive | delete // default: archive + } +} +``` + +### 4.2 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 | 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, type: string, externalId: string, url: string } + ] + checkpointExpiresAt: datetime? + 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 +``` + +### 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 +``` + +--- + +## 6. Flow + +Constraint configuration layered on top of Workers + Contracts. Registry entity. + +``` +Flow { + id: GTS Type Identifier (gts.cf.studio.core.flow.v1~...) + entryConstraints: Contract[] + mandatorySteps: Worker[] + allowedNextSteps: map + scope: local | project | workspace | published +} +``` + +### 6.1 FlowRun + +``` +FlowRun extends Object { + typeId: gts.cf.studio.core.object.v1~cf.studio.core.flow_run.v1~ + flowId: ref → Flow + completedSteps: Worker[] + skippedSteps: Worker[] + state: running | done | failed | aborted +} +``` + +--- + +## 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 +} +``` + +Every Object belongs to exactly one Tenant (`tenantId`). +Isolation enforced via ABAC policies using GTS wildcard patterns. + +--- + +## 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.** + +``` +Workspace extends Object { + typeId: gts.cf.studio.core.object.v1~cf.studio.core.workspace.v1~ + sources: [ + { path: string, role: string, adapter?: string, url?: string, branch?: string } + ] +} +``` + +--- + +## 10. Extensibility (Kit) + +### 10.1 Kit — the only extension unit + +A Kit packages: new Object types, Workers, WorkerImplementations, 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 +} +``` + +### 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.4 Permissions + +``` +Kit manifest: + requiredPermissions: + - read: [ GTS Type Identifier, ... ] + - write: [ GTS Type Identifier, ... ] + - call: [ GTS Type Identifier, ... ] + requiredSettings: + - { key: string, secret: boolean } // credentials stored in Gears Settings +``` + +- Tenant explicitly approves at installation +- Expanding permissions in new version → blocks auto-update, requires re-approval +- Reducing permissions → auto-update + +--- + +## 11. System Overview + +``` +┌─────────────────────────────────────────────────────────────┐ +│ 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 + ▼ +┌─────────────────────────────────────────────────────────────┐ +│ OBJECT GRAPH │ +│ gts.cf.studio.core.object.v1~ (base) │ +│ │ +│ Tenant* Workspace WorkerRun FlowRun │ +│ User* Role Recommendation │ +│ Requirement Task PullRequest Build │ +│ Design Incident IdentityMapping │ +│ PolicyOverride PolicyDelegation SavedAuditQuery │ +│ NotificationRuleOverride NotificationSubscription │ +│ │ +│ * extends Gears base types (AM/RG) │ +└─────────────────────────────────────────────────────────────┘ +``` + +--- + +## 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" + } + } + ] + } +} +``` + +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 + +### 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 } + conditionCache: { ttl: duration } // default: 60s + } + ] +} + +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 +} +``` + +### 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. + +### 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 +} +``` + +### 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 +} +``` + +### 15.2 Analyzer Workers + +Detect gaps and create Recommendations. Use standard Worker `trigger` with +`schedule`, `onEvent` (+ `debounce`), and `onDemand`. + +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 +``` + +--- + +## 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. + +### 16.1 Studio Event Types + +``` +// Object lifecycle +gts.cf.studio.core.event.v1~cf.studio.core.object_created.v1~ +gts.cf.studio.core.event.v1~cf.studio.core.object_updated.v1~ +gts.cf.studio.core.event.v1~cf.studio.core.object_deleted.v1~ + +// State transitions +gts.cf.studio.core.event.v1~cf.studio.core.state_changed.v1~ + +// WorkerRun +gts.cf.studio.core.event.v1~cf.studio.core.worker_run_started.v1~ +gts.cf.studio.core.event.v1~cf.studio.core.worker_run_completed.v1~ + +// Recommendations +gts.cf.studio.core.event.v1~cf.studio.core.recommendation_created.v1~ +gts.cf.studio.core.event.v1~cf.studio.core.recommendation_invalidated.v1~ + +// Kit lifecycle +gts.cf.studio.core.event.v1~cf.studio.core.kit_installed.v1~ +gts.cf.studio.core.event.v1~cf.studio.core.kit_updated.v1~ +``` + +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 +} +``` + +### 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 Settings Service. No secrets in Kit. + +--- + +## 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~ +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~ +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~ +``` + +### 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 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 + +``` +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~ +``` + +### 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~ +``` + +### 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 +``` + +### 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~ +cf.studio.core.sbom.v1~ // Software Bill of Materials +``` + +### 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~ +``` + +### 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 +``` + +### 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 +``` + +### 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.cost_report.v1~ // AI cost, infrastructure cost +``` + +### Domain 13 — People / Teams + +``` +cf.studio.core.person.v1~ +cf.studio.core.team.v1~ +cf.studio.core.org_unit.v1~ // department, division +``` + +### 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~ +``` + +### 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 +``` + +### 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~ +// llm_model → reference to Gears Models Registry (no separate Object type) +``` + +--- + +### 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* From c8a4672a58a6f035baa7f8c547c1f963cbfb3cb0 Mon Sep 17 00:00:00 2001 From: ainetx Date: Thu, 2 Jul 2026 18:47:34 +0300 Subject: [PATCH 002/106] docs(v2): enhance domain model with security and vulnerability object hierarchy and cross-references Signed-off-by: ainetx --- v2/docs/domain-model.md | 397 ++++++++++++++++++++++++++++++++++++++-- 1 file changed, 385 insertions(+), 12 deletions(-) diff --git a/v2/docs/domain-model.md b/v2/docs/domain-model.md index 5c6a069f..80e0b548 100644 --- a/v2/docs/domain-model.md +++ b/v2/docs/domain-model.md @@ -380,7 +380,11 @@ classDiagram --- -### D17 — Security & Vulnerability Objects +### D17 — Security & Vulnerability Objects (type hierarchy) + +> See D24 for cross-references between security objects and the rest of the graph. + + ```mermaid classDiagram @@ -473,7 +477,12 @@ gts.cf.studio.core.object.v1~ ← base Object (all Studio domain objects) gts.cf.studio.core.worker.v1~ ← base Worker gts.cf.studio.core.flow.v1~ ← base Flow gts.cf.studio.core.obj_ext.v1~ ← attribute extension -gts.cf.studio.core.event.v1~ ← base Event type +``` + +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 @@ -1102,26 +1111,36 @@ Studio defines event types via GTS. ### 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.studio.core.event.v1~cf.studio.core.object_created.v1~ -gts.cf.studio.core.event.v1~cf.studio.core.object_updated.v1~ -gts.cf.studio.core.event.v1~cf.studio.core.object_deleted.v1~ +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.studio.core.event.v1~cf.studio.core.state_changed.v1~ +gts.cf.core.events.type.v1~cf.studio.core.state_changed.v1~ // WorkerRun -gts.cf.studio.core.event.v1~cf.studio.core.worker_run_started.v1~ -gts.cf.studio.core.event.v1~cf.studio.core.worker_run_completed.v1~ +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~ // Recommendations -gts.cf.studio.core.event.v1~cf.studio.core.recommendation_created.v1~ -gts.cf.studio.core.event.v1~cf.studio.core.recommendation_invalidated.v1~ +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.studio.core.event.v1~cf.studio.core.kit_installed.v1~ -gts.cf.studio.core.event.v1~cf.studio.core.kit_updated.v1~ +gts.cf.core.events.type.v1~cf.studio.core.kit_installed.v1~ +gts.cf.core.events.type.v1~cf.studio.core.kit_updated.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 @@ -1465,5 +1484,359 @@ gts.cf.studio.core.object.v1~cf.studio.core.wiki_page.v1~confluence.studio.core. --- +## Object Reference Diagrams + +> These diagrams show **cross-references** between Studio Objects — who points to whom in the live graph. + +--- + +### 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 +``` + +--- + +### 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"] +``` + +--- + +### 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 +``` + +--- + +### 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 +``` + +--- + +### 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)"] +``` + +--- + +### 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"] +``` + +--- + +### 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) +``` + +--- + +### D27 — Workspace & Kit Cross-References + +```mermaid +classDiagram + class Workspace { + tenantId: ref Tenant + sources: SourceEntry[] + } + class SourceEntry { + path: string + url: string? + role: string + } + class repository { + url: string + } + class Kit { + scope: local|project|workspace|published + requiredPermissions: Permission[] + } + class Tenant { + parentId: ref Tenant? + } + + Workspace "1" --> "many" SourceEntry : sources + SourceEntry --> repository : resolves to + Tenant "1" --> "many" Kit : installed Kits + Workspace --> Tenant : tenantId +``` + +--- + +### 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 +``` + +--- + +### 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 +``` + +--- + +### 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 +``` + +--- + +### 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 +``` + +--- + *Generated during Studio v2 Domain Model brainstorm session.* *Date: 2026-07-02* From 9dfa91ba1545fd122844130e0eabda3daedafb59 Mon Sep 17 00:00:00 2001 From: ainetx Date: Thu, 2 Jul 2026 18:57:39 +0300 Subject: [PATCH 003/106] docs(v2): add component/release reference diagrams and GTS type fixes MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add component_version, component_dependency, release_component types to complete the component and release domain models - Add 7 new cross-reference diagrams (D32-D38): component ownership, component↔docs, component↔people/teams, release cross-refs, release↔work-items traceability, full component→release→deployment chain, and component dependency graph - Fix Studio event GTS type: extend Gears platform event base type gts.cf.core.events.type.v1~ instead of defining a conflicting gts.cf.studio.core.event.v1~ base type - Verify all Studio GTS types against Gears base types; confirm Worker, Flow, Kit, Role remain first-class Studio types Signed-off-by: ainetx --- v2/docs/domain-model.md | 161 +++++++++++++++++++++++++++++++++++++++- 1 file changed, 160 insertions(+), 1 deletion(-) diff --git a/v2/docs/domain-model.md b/v2/docs/domain-model.md index 80e0b548..15d8b1ea 100644 --- a/v2/docs/domain-model.md +++ b/v2/docs/domain-model.md @@ -1248,7 +1248,9 @@ cf.studio.core.decomposition.v1~ // → document (Studio SDLC DECOMPOSIT ``` cf.studio.core.design.v1~ // → document (Studio SDLC DESIGN) cf.studio.core.adr.v1~ // → document (Architecture Decision Record) -cf.studio.core.component.v1~ +cf.studio.core.component.v1~ // architectural component (service, module, library, subsystem) +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~ @@ -1333,6 +1335,7 @@ 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 ``` ### Domain 10 — Operations / Incidents @@ -1838,5 +1841,161 @@ flowchart TD --- +### D32 — Component Cross-References + +```mermaid +classDiagram + class component { + name: string + kind: service|library|module|subsystem + 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"] +``` + +--- + +### 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 +``` + +--- + +### 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"] +``` + +--- + +### 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 +``` + +--- + *Generated during Studio v2 Domain Model brainstorm session.* *Date: 2026-07-02* From 9fa740a033def2b4d0092af4636a5f4879ac17bd Mon Sep 17 00:00:00 2001 From: ainetx Date: Thu, 2 Jul 2026 18:59:31 +0300 Subject: [PATCH 004/106] docs(v2): add technology stack domain with library, database, service types and diagrams MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add Domain 3a (Technology Stack) with 10 new object types: tech_stack, library, library_version, framework, runtime, database, database_instance, third_party_service, cloud_service, tech_dependency Add 5 cross-reference diagrams (D39-D43): D39 - tech stack type hierarchy (library, framework, runtime) D40 - data and external service dependencies D41 - component ↔ full technology stack D42 - library_version ↔ security/vulnerability chain D43 - tech stack ↔ release pinning and compliance (SBOM, license) Signed-off-by: ainetx --- v2/docs/domain-model.md | 126 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 126 insertions(+) diff --git a/v2/docs/domain-model.md b/v2/docs/domain-model.md index 15d8b1ea..d7aeeed3 100644 --- a/v2/docs/domain-model.md +++ b/v2/docs/domain-model.md @@ -1266,6 +1266,21 @@ 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 +``` + ### Domain 4 — Work Items ``` @@ -1997,5 +2012,116 @@ flowchart LR --- +### 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)"] +``` + +--- + +### 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)"] +``` + +--- + +### 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"] +``` + +--- + *Generated during Studio v2 Domain Model brainstorm session.* *Date: 2026-07-02* From 45023adf5e5e0f8ecd38b5ea1a7d59b746d69696 Mon Sep 17 00:00:00 2001 From: ainetx Date: Thu, 2 Jul 2026 19:01:04 +0300 Subject: [PATCH 005/106] docs(v2): add SBOM domain entities and cross-reference diagrams MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add Domain 8a (SBOM) with 5 new object types: sbom - SBOM document (SPDX / CycloneDX / SWID) sbom_component - package/library entry within an SBOM sbom_relationship - directed relationship between sbom_components (CONTAINS, DEPENDS_ON, DESCRIBES, GENERATED_FROM, VARIANT_OF, PATCH_OF) sbom_license - SPDX license expression per component sbom_checksum - cryptographic hash (SHA256, SHA1, MD5, BLAKE2) Add 4 cross-reference diagrams (D44-D47): D44 - SBOM document structure and relationships D45 - sbom_component details (license, checksum, library_version mapping) D46 - SBOM cross-references (artifact → sbom → component → vulnerability) D47 - SBOM ↔ security scanning and license compliance chain Signed-off-by: ainetx --- v2/docs/domain-model.md | 113 +++++++++++++++++++++++++++++++++++++++- 1 file changed, 112 insertions(+), 1 deletion(-) diff --git a/v2/docs/domain-model.md b/v2/docs/domain-model.md index d7aeeed3..bb4dc5ca 100644 --- a/v2/docs/domain-model.md +++ b/v2/docs/domain-model.md @@ -1339,7 +1339,20 @@ cf.studio.core.package.v1~ cf.studio.core.package_version.v1~ cf.studio.core.container_image.v1~ cf.studio.core.container_image_tag.v1~ -cf.studio.core.sbom.v1~ // Software Bill of Materials +``` + +### 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) ``` ### Domain 9 — Release @@ -2123,5 +2136,103 @@ flowchart TD --- +### 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)"] +``` + +--- + *Generated during Studio v2 Domain Model brainstorm session.* *Date: 2026-07-02* From 73e057bd8b11ece48540b1e6353068ddc0432ff6 Mon Sep 17 00:00:00 2001 From: ainetx Date: Fri, 3 Jul 2026 11:29:55 +0300 Subject: [PATCH 006/106] =?UTF-8?q?docs(v2):=20close=20critical=20vision?= =?UTF-8?q?=20gaps=20=E2=80=94=20Validator,=20Evidence,=20Connector,=20sta?= =?UTF-8?q?leness,=20approvals?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Address critical gaps identified in gap analysis vs STUDIO_VISION.md: Object base type: - Add ownerId, validationStatus, stalenessScore, externalRef to base Object - stalenessScore = max(timeStaleness, dependencyStaleness, syncStaleness) New registry entities: - Validator (extends Worker): maxRetries, escalateTo, abortOnLimit - Connector: OAGW-backed integration with field mapping, write-back policy, sync protocol (push/pull), rate limiting, scope filter per Tenant New Object types: - ValidationSession: aggregates retry loop for one Validator run - ValidationResult: per-attempt result with superseded/revoked lifecycle - Evidence: structured proof of action/validation with valid/superseded/revoked WorkerRun state machine: add escalated + aborted states Staleness model (Section 20): - stalenessPolicy in x-gts-traits per type (timeTTL, dependencyTypes, threshold) - stale_artifact_detection Analyzer updates score async (15min + onEvent debounce) Approval & Human Control (Section 21): - Generic Approval with kind discriminator + typed payload per kind - security_exception payload: expiresAt, mitigations, secondaryApprover, autoReviewAfter - customerImpact optional field for customer-facing decisions Flow Library Catalog (Section 22): - 12 Analyzer Workers with runtime, profile, input Contract per Analyzer - 2 Flows: bug_to_fix_pr_flow (Killer Workflow 1), release_readiness_review - Worker metadata: displayName, description, category, profile Traceability (Section 23): - pull_request: closesIssues, implementsRequirements, conformsToDesign, verifiedBy - test_case: verifiesRequirements, verifiesFeature - pr_design_validator: hybrid Validator triggered on PR → review Signed-off-by: ainetx --- v2/docs/domain-model.md | 392 +++++++++++++++++++++++++++++++++++++++- 1 file changed, 383 insertions(+), 9 deletions(-) diff --git a/v2/docs/domain-model.md b/v2/docs/domain-model.md index bb4dc5ca..3f92e8d8 100644 --- a/v2/docs/domain-model.md +++ b/v2/docs/domain-model.md @@ -437,12 +437,23 @@ 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 + 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 + } } ``` @@ -455,10 +466,13 @@ Outside the graph. Describe rules and configurations, not data. | Entity | Purpose | |---|---| | `Worker` | Executor — consumes and produces Objects | +| `Validator` | Extends Worker; adds retry loop, escalation, maxRetries semantics | | `WorkerImplementation` | Runtime configuration of a Worker (model, prompt, script) | | `Flow` | Configuration of constraints and mandatory steps | -| `Kit` | Extension packaging unit (types, Workers, Flows) | +| `Connector` | Integration with external system via Gears OAGW (field mapping, write-back, sync) | +| `Kit` | Extension packaging unit (types, Workers, Validators, Flows, Connectors) | | `obj_ext` | Attribute extension for existing types | +| `StatePolicy` | Per-property transition rules (separate from type schema) | --- @@ -475,7 +489,10 @@ Studio-owned base types: ``` gts.cf.studio.core.object.v1~ ← base Object (all Studio domain objects) gts.cf.studio.core.worker.v1~ ← base Worker +gts.cf.studio.core.validator.v1~ ← extends Worker; adds retry/escalation semantics gts.cf.studio.core.flow.v1~ ← base Flow +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 ``` @@ -1213,6 +1230,347 @@ for credentials; Tenant fills via Gears Settings Service. No secrets in Kit. --- +## 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 → done + → failed (error, can retry) + → escalated (awaiting Approval from human) + → aborted (limit reached or human rejected) +``` + +### 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 +``` + +--- + +## 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 // reference to OAGW upstream (created at Kit install) + 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`; trigger: `schedule: "*/15 * * * *"` + `onEvent` with `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? + } +} +``` + +### 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 + +| Name | Runtime | Profile | Input Objects | +|---|---|---|---| +| `gap_analysis` | hybrid | scheduled | requirement, task, test_case, pull_request | +| `traceability_analysis` | hybrid | scheduled | requirement, design, task, pull_request, test_case | +| `contradiction_detection` | llm | on_demand | document[] (any two or more) | +| `bloat_detection` | hybrid | on_demand | requirement[], task[] | +| `stale_artifact_detection` | script | realtime | Object (wildcard — any type) | +| `ownership_gap_analysis` | script | realtime | Object (wildcard — ownerId == null) | +| `duplicate_work_detection` | llm | on_demand | task[], requirement[] | +| `architecture_drift_detection` | hybrid | scheduled | component, component_dependency, design | +| `security_impact_analysis` | hybrid | scheduled | pull_request, vulnerability, security_finding | +| `test_gap_detection` | hybrid | scheduled | requirement, test_case | +| `operations_metrics_analysis` | hybrid | scheduled | slo, sli, metric_definition, alert | +| `ai_cost_efficiency_analysis` | script | scheduled | WorkerRun[], cost_report | + +### 22.2 Flows (2) — mandatory step sequences + +**`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 +``` + +### 22.3 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) + +### 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 } +} +``` + +--- + ## Appendix A — Studio v2 Object Type Catalog All types follow the pattern: @@ -1291,14 +1649,16 @@ cf.studio.core.tech_debt_item.v1~ cf.studio.core.change_request.v1~ ``` -### Domain 5 — Collaboration +### 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~ +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 @@ -1460,6 +1820,20 @@ cf.studio.core.evaluation_result.v1~ --- +### 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 +``` + +--- + ### Notes - **Dashboard** — implemented in Constructor Fabric Insight, not Studio. From 8cf8b9efddda6704f5c39be789fb8dbf14a20aa7 Mon Sep 17 00:00:00 2001 From: ainetx Date: Fri, 3 Jul 2026 13:28:24 +0300 Subject: [PATCH 007/106] docs(v2): add initial brainstorm session documentation for Studio v2 domain model Signed-off-by: ainetx --- .../state.md | 225 ++++++++++++++++++ 1 file changed, 225 insertions(+) create mode 100644 .bootstrap/.cache/brainstorm/studio-v2-domain-model-2026-07-03/state.md 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..d671a8de --- /dev/null +++ b/.bootstrap/.cache/brainstorm/studio-v2-domain-model-2026-07-03/state.md @@ -0,0 +1,225 @@ +# Brainstorm Session — Studio v2 Domain Model + +**Session ID:** studio-v2-domain-model-2026-07-03 +**Date:** 2026-07-03 +**Rounds:** 20 +**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) | + +--- + +## 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` + +### 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; `WorkerRun.cost` field; `performance_benchmark` for AI Workers; custom enterprise models via Gears Models Registry +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 + +--- + +## Output Artifact + +Domain model written to: `v2/docs/domain-model.md` +Last commit: `73e057b` From a67bb5904dc5328a67cd8875d6f2c3aed27637b6 Mon Sep 17 00:00:00 2001 From: ainetx Date: Sun, 5 Jul 2026 13:06:37 +0300 Subject: [PATCH 008/106] docs(v2): distribute all 47 diagrams inline with their defining sections Signed-off-by: ainetx Co-authored-by: Constructor Studio <291158726+constructor-studio[bot]@users.noreply.github.com> Studio-Generated-By: Constructor Studio Studio-Source-Repo: https://github.com/constructorfabric/studio Constructor-Fabric: https://github.com/constructorfabric Studio-Version: skill=1.5.9, cli=1.5.10.dev73 Studio-Workflows: cf-brainstorm --- v2/docs/domain-model.md | 2801 +++++++++++++++++++-------------------- 1 file changed, 1348 insertions(+), 1453 deletions(-) diff --git a/v2/docs/domain-model.md b/v2/docs/domain-model.md index 3f92e8d8..7db8d68b 100644 --- a/v2/docs/domain-model.md +++ b/v2/docs/domain-model.md @@ -4,35 +4,38 @@ --- -## Diagrams +The system consists of two categories of entities: -### D1 — System Overview: Registry vs Object Graph +- **Object** — data and artifacts that flow through the system (the graph) +- **Registry entities** — Worker, Flow, Kit, etc. (outside the graph; templates/configurations) -```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 +## 1. Entities - subgraph Graph["Object Graph"] - Object["Object\n(base type)"] - WorkerRun["WorkerRun\nextends Object"] - FlowRun["FlowRun\nextends Object"] - end +### 1.1 Object - 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 -``` +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 + } +} +``` ### D2 — Object Base Hierarchy @@ -61,43 +64,147 @@ classDiagram Object <|-- Recommendation ``` +All object types are derived from the base `Object` via GTS chained IDs. + +### 1.2 Registry Entities + +Outside the graph. Describe rules and configurations, not data. + +| Entity | Purpose | +|---|---| +| `Worker` | Executor — consumes and produces Objects | +| `Validator` | Extends Worker; adds retry loop, escalation, maxRetries semantics | +| `WorkerImplementation` | Runtime configuration of a Worker (model, prompt, script) | +| `Flow` | Configuration of constraints and mandatory steps | +| `Connector` | Integration with external system via Gears OAGW (field mapping, write-back, sync) | +| `Kit` | Extension packaging unit (types, Workers, Validators, Flows, Connectors) | +| `obj_ext` | Attribute extension for existing types | +| `StatePolicy` | Per-property transition rules (separate from type schema) | + --- -### D3 — Tenant Hierarchy & Isolation +## 2. GTS Identifiers -```mermaid -classDiagram - class Tenant { - 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 - } +**Convention:** `gts.....v` - 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 +Studio vendor = `cf` (same as Constructor Fabric Gears). + +### 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 +gts.cf.studio.core.validator.v1~ ← extends Worker; adds retry/escalation semantics +gts.cf.studio.core.flow.v1~ ← base Flow +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 +``` + +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~ +``` + +### 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-*`). + +Describes what a Worker expects as input and what it produces as output. +Object type references use `$ref` → GTS Type Identifier. Scalar properties +are standard JSON Schema fields. + +```json +{ + "$id": "gts.cf.studio.core.worker.v1~cf.studio.core.create_design_input.v1~", + "type": "object", + "properties": { + "requirement": { + "$ref": "gts://cf.studio.core.object.v1~cf.studio.core.requirement.v1~", + "x-gts-required": true + }, + "workspace": { + "$ref": "gts://cf.studio.core.object.v1~cf.studio.core.workspace.v1~", + "x-gts-required": true + }, + "style": { "type": "string", "enum": ["detailed", "sketch"] }, + "language": { "type": "string" } + } +} ``` --- +## 4. Worker + +Executor — consumes Objects, produces Objects. Registry entity. + +``` +Worker { + id: GTS Type Identifier (gts.cf.studio.core.worker.v1~...) + input: Contract (GTS Type Schema) + output: Contract (GTS Type Schema) + dependencies: Worker[] (static list — security boundary) + scope: local | project | workspace | published + implementationId: ref → WorkerImplementation + trigger?: { + schedule?: cron string + onEvent?: { + pattern: GTS Type Identifier + debounce: duration // default: 0 + } + onDemand: boolean // default: true + } +} +``` + ### D4 — Worker & Contract ```mermaid @@ -129,708 +236,414 @@ classDiagram Worker ..> WorkerRun : execution produces ``` ---- - -### 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]) +### 4.1 WorkerImplementation - FAILED --> CHK{checkpoint\nenabled?} - CHK -->|yes + TTL valid| RETRY[Checkpoint-based\nRetry] - CHK -->|no / TTL expired| FULL[Full Restart] - RETRY --> EXEC - FULL --> WA +Runtime configuration, versioned independently from the contract. - EXEC --> LIMITS["effectiveLimits applied\nkit → tenant → call"] +``` +WorkerImplementation { + id: string + version: semver + runtime: llm | script | hybrid + config: { + // llm: { model, prompt, temperature, ... } + // script: { entrypoint, language, ... } + // hybrid: { steps[] } + } + dependencies_mode: { + // workerId → { mode: sync | async } + } + checkpoint: { + enabled: boolean + ttl: duration + } + auditMode: sync | async // default: async + retentionPolicy: { + inputTTL: duration + outputTTL: duration + metadataTTL: duration + retentionAction: archive | delete // default: archive + } +} ``` ---- +### 4.2 Composability -### 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"] +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. - REQ -->|gates| WD["Worker Discovery\n= type match\n+ state match"] -``` +The system automatically builds a **DAG** from dependencies and executes +independent branches in parallel. --- -### D7 — Authorization Model +## 5. WorkerRun -```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[] - } +A record of a specific Worker execution. **Extends Object.** - User --> Role : has - Role --> Policy : governs via - Policy <|-- PolicyOverride : overrides - Kit --> Policy : Worker authz via requiredPermissions +``` +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 | 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, type: string, externalId: string, url: string } + ] + checkpointExpiresAt: datetime? + staticChildren: WorkerRun[] +} ``` ---- - -### 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)"] +### 5.1 WorkerRun Lifecycle (Write-Ahead) - KV["Kit View\n(named query)"] -->|named query over| API - SAQ["SavedAuditQuery\nextends Object"] -->|user query over| API +``` +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 ``` ---- - -### D9 — Recommendation Lifecycle +### D5 — WorkerRun Execution Lifecycle ```mermaid flowchart TD - AW["Analyzer Worker\n(schedule/onEvent/onDemand)"] -->|creates| REC["Recommendation\nextends Object"] + START([START]) --> WA[Write-Ahead\nexternalEvents recorded] + WA --> EXEC[Execute\nDAG parallel branches] + EXEC --> DONE([done]) + EXEC --> FAILED([failed]) - 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] + FAILED --> CHK{checkpoint\nenabled?} + CHK -->|yes + TTL valid| RETRY[Checkpoint-based\nRetry] + CHK -->|no / TTL expired| FULL[Full Restart] + RETRY --> EXEC + FULL --> WA - REC -->|validationWorker| VW["Validation Worker\n(re-check + refresh input)"] - REC -->|suggestedWorker| SW["Suggested Worker\n(actionable fix)"] + EXEC --> LIMITS["effectiveLimits applied\nkit → tenant → call"] ``` ---- +### 5.2 Retry -### D10 — Events & Notifications +- **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`. -```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..."] +### 5.3 Limits (three levels, each can only narrow) - NSU["NotificationSubscription\nextends Object"] -->|personal filter| EB - NRO["NotificationRuleOverride\nextends Object"] -->|on/off + expiresAt| NR +``` +Kit defaults: timeout, depth, token_budget +Tenant max limits: ← ceiling +Call (at invocation): ← can narrow, not exceed Tenant ``` ---- - -### D11 — Document Type Hierarchy +### D18 — WorkerRun Cross-References ```mermaid classDiagram - class document { - content: string - version: semver - ownerId: ref User + 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 } - document <|-- spec - document <|-- guide - document <|-- readme - document <|-- wiki_page - document <|-- api_documentation - document <|-- prd - document <|-- adr + WorkerRun --> Worker : workerId + WorkerRun --> WorkerRun : parentRunId (sub-call tree) + WorkerRun --> Object : inputData references + WorkerRun --> Object : outputData produces + FlowRun --> WorkerRun : completedSteps ``` --- -### D12 — Document Type Hierarchy (continued) +## 6. Flow -```mermaid -classDiagram - class document +Constraint configuration layered on top of Workers + Contracts. Registry entity. - document <|-- design - document <|-- feature_spec - document <|-- decomposition - document <|-- runbook - document <|-- postmortem - document <|-- release_notes - document <|-- meeting_note +``` +Flow { + id: GTS Type Identifier (gts.cf.studio.core.flow.v1~...) + entryConstraints: Contract[] + mandatorySteps: Worker[] + allowedNextSteps: map + scope: local | project | workspace | published +} +``` + +### 6.1 FlowRun + +``` +FlowRun extends Object { + typeId: gts.cf.studio.core.object.v1~cf.studio.core.flow_run.v1~ + flowId: ref → Flow + completedSteps: Worker[] + skippedSteps: Worker[] + state: running | done | failed | aborted +} ``` --- -### D13 — Prompt Type Hierarchy +## 7. Tenant -```mermaid -classDiagram - class prompt { - content: string - version: semver - } +Recursive hierarchy. Extends Gears Resource Group tenant type. - prompt <|-- skill - prompt <|-- system_prompt - prompt <|-- prompt_template - prompt <|-- prompt_variant +``` +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 +} ``` ---- +Every Object belongs to exactly one Tenant (`tenantId`). +Isolation enforced via ABAC policies using GTS wildcard patterns. -### D14 — Infrastructure Config Hierarchy +### D3 — Tenant Hierarchy & Isolation ```mermaid classDiagram - class infra_config { - environment: ref environment - version: string + class Tenant { + 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 } - infra_config <|-- terraform_resource - infra_config <|-- helm_release - infra_config <|-- k8s_manifest + 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 ``` --- -### D15 — Kit Extensibility (GTS Chaining) +## 8. User -```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 +Extends Gears Account Management user type. - OE["obj_ext\n(attribute extension)\nno new type ID needed"] -.->|extends attrs of| B2 ``` - ---- - -### 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 +User { + typeId: gts.cf.core.am.user.v1~cf.studio.core.user.v1~ + // inherits: id, email, display_name from Gears AM + tenantId: ref → Tenant +} ``` --- -### D17 — Security & Vulnerability Objects (type hierarchy) +## 9. Workspace -> See D24 for cross-references between security objects and the rest of the graph. +Multi-repo configuration. **Extends Object.** +``` +Workspace extends Object { + typeId: gts.cf.studio.core.object.v1~cf.studio.core.workspace.v1~ + sources: [ + { path: string, role: string, adapter?: string, url?: string, branch?: string } + ] +} +``` +### D27 — Workspace & Kit Cross-References ```mermaid classDiagram - class vulnerability { - severity: critical|high|medium|low - cveId: string? - state: open|fixed|ignored - } - class cve { - cvssScore: float - description: string + class Workspace { + tenantId: ref Tenant + sources: SourceEntry[] } - class security_finding { - source: pentest|code_scan|secret_scan - severity: string + class SourceEntry { + path: string + url: string? + role: string } - class dependency_vulnerability { - packageName: string - affectedVersions: string[] - fixedVersion: string? + class repository { + url: string } - class compliance_check { - standard: string - control: string + class Kit { + scope: local|project|workspace|published + requiredPermissions: Permission[] } - class compliance_check_result { - checkId: ref compliance_check - state: pass|fail|skip + class Tenant { + parentId: ref Tenant? } - vulnerability --> cve : references - dependency_vulnerability --|> vulnerability - security_finding --|> vulnerability - compliance_check "1" --> "many" compliance_check_result + Workspace "1" --> "many" SourceEntry : sources + SourceEntry --> repository : resolves to + Tenant "1" --> "many" Kit : installed Kits + Workspace --> Tenant : tenantId ``` --- -*Generated during Studio v2 Domain Model brainstorm session.* -*Date: 2026-07-02* +## 10. Extensibility (Kit) -The system consists of two categories of entities: +### 10.1 Kit — the only extension unit -- **Object** — data and artifacts that flow through the system (the graph) -- **Registry entities** — Worker, Flow, Kit, etc. (outside the graph; templates/configurations) +A Kit packages: new Object types, Workers, WorkerImplementations, Flows, +obj_ext definitions. -### 1.1 Object +``` +Kit scopes: + local ← developer's machine + project ← project repository + workspace ← workspace configuration + published ← marketplace / Registry +``` -The base type for all domain objects in the system. +### 10.2 Two type extension mechanisms +**Narrowing** (new semantic type) → GTS derived type via chaining: ``` -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 +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 } ``` -All object types are derived from the base `Object` via GTS chained IDs. - -### 1.2 Registry Entities - -Outside the graph. Describe rules and configurations, not data. - -| Entity | Purpose | -|---|---| -| `Worker` | Executor — consumes and produces Objects | -| `Validator` | Extends Worker; adds retry loop, escalation, maxRetries semantics | -| `WorkerImplementation` | Runtime configuration of a Worker (model, prompt, script) | -| `Flow` | Configuration of constraints and mandatory steps | -| `Connector` | Integration with external system via Gears OAGW (field mapping, write-back, sync) | -| `Kit` | Extension packaging unit (types, Workers, Validators, Flows, Connectors) | -| `obj_ext` | Attribute extension for existing types | -| `StatePolicy` | Per-property transition rules (separate from 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)"] -## 2. GTS Identifiers + B1 -->|narrows to| B2 + B2 -->|narrows to| B3 + B1 -->|narrows to| B4 + B4 -->|narrows to| B5 -**Convention:** `gts.....v` + OE["obj_ext\n(attribute extension)\nno new type ID needed"] -.->|extends attrs of| B2 +``` -Studio vendor = `cf` (same as Constructor Fabric Gears). +### 10.3 Compatibility -### 2.1 Studio Base Types +- Vendor declares `compatibleWith` in Kit manifest +- Registry verifies via GTS compatibility rules at installation +- Smoke tests not run (too costly for LLM Workers) -Studio-owned base types: +### 10.4 Permissions ``` -gts.cf.studio.core.object.v1~ ← base Object (all Studio domain objects) -gts.cf.studio.core.worker.v1~ ← base Worker -gts.cf.studio.core.validator.v1~ ← extends Worker; adds retry/escalation semantics -gts.cf.studio.core.flow.v1~ ← base Flow -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 +Kit manifest: + requiredPermissions: + - read: [ GTS Type Identifier, ... ] + - write: [ GTS Type Identifier, ... ] + - call: [ GTS Type Identifier, ... ] + requiredSettings: + - { key: string, secret: boolean } // credentials stored in Gears Settings ``` -Studio event types extend the **Gears platform event base type**: +- Tenant explicitly approves at installation +- Expanding permissions in new version → blocks auto-update, requires re-approval +- Reducing permissions → auto-update -``` -gts.cf.core.events.type.v1~ ← Gears platform event base type (DO NOT redefine) -``` +--- -### 2.2 Gears Base Types Extended by Studio +## 11. System Overview -Studio extends existing Gears base types where applicable: +### D1 — System Overview: Registry vs Object Graph -| 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~` | +```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 -### 2.3 Studio Core Object Types (derived from Studio base) + 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 ``` -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~ -``` - -### 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-*`). - -Describes what a Worker expects as input and what it produces as output. -Object type references use `$ref` → GTS Type Identifier. Scalar properties -are standard JSON Schema fields. - -```json -{ - "$id": "gts.cf.studio.core.worker.v1~cf.studio.core.create_design_input.v1~", - "type": "object", - "properties": { - "requirement": { - "$ref": "gts://cf.studio.core.object.v1~cf.studio.core.requirement.v1~", - "x-gts-required": true - }, - "workspace": { - "$ref": "gts://cf.studio.core.object.v1~cf.studio.core.workspace.v1~", - "x-gts-required": true - }, - "style": { "type": "string", "enum": ["detailed", "sketch"] }, - "language": { "type": "string" } - } -} -``` - ---- - -## 4. Worker - -Executor — consumes Objects, produces Objects. Registry entity. - -``` -Worker { - id: GTS Type Identifier (gts.cf.studio.core.worker.v1~...) - input: Contract (GTS Type Schema) - output: Contract (GTS Type Schema) - dependencies: Worker[] (static list — security boundary) - scope: local | project | workspace | published - implementationId: ref → WorkerImplementation - trigger?: { - schedule?: cron string - onEvent?: { - pattern: GTS Type Identifier - debounce: duration // default: 0 - } - onDemand: boolean // default: true - } -} -``` - -### 4.1 WorkerImplementation - -Runtime configuration, versioned independently from the contract. - -``` -WorkerImplementation { - id: string - version: semver - runtime: llm | script | hybrid - config: { - // llm: { model, prompt, temperature, ... } - // script: { entrypoint, language, ... } - // hybrid: { steps[] } - } - dependencies_mode: { - // workerId → { mode: sync | async } - } - checkpoint: { - enabled: boolean - ttl: duration - } - auditMode: sync | async // default: async - retentionPolicy: { - inputTTL: duration - outputTTL: duration - metadataTTL: duration - retentionAction: archive | delete // default: archive - } -} -``` - -### 4.2 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 | 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, type: string, externalId: string, url: string } - ] - checkpointExpiresAt: datetime? - 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 -``` - -### 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 -``` - ---- - -## 6. Flow - -Constraint configuration layered on top of Workers + Contracts. Registry entity. - -``` -Flow { - id: GTS Type Identifier (gts.cf.studio.core.flow.v1~...) - entryConstraints: Contract[] - mandatorySteps: Worker[] - allowedNextSteps: map - scope: local | project | workspace | published -} -``` - -### 6.1 FlowRun - -``` -FlowRun extends Object { - typeId: gts.cf.studio.core.object.v1~cf.studio.core.flow_run.v1~ - flowId: ref → Flow - completedSteps: Worker[] - skippedSteps: Worker[] - state: running | done | failed | aborted -} -``` - ---- - -## 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 -} -``` - -Every Object belongs to exactly one Tenant (`tenantId`). -Isolation enforced via ABAC policies using GTS wildcard patterns. - ---- - -## 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.** - -``` -Workspace extends Object { - typeId: gts.cf.studio.core.object.v1~cf.studio.core.workspace.v1~ - sources: [ - { path: string, role: string, adapter?: string, url?: string, branch?: string } - ] -} -``` - ---- - -## 10. Extensibility (Kit) - -### 10.1 Kit — the only extension unit - -A Kit packages: new Object types, Workers, WorkerImplementations, 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 -} -``` - -### 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.4 Permissions +### D31 — Full Object Reference Map (top-level) -``` -Kit manifest: - requiredPermissions: - - read: [ GTS Type Identifier, ... ] - - write: [ GTS Type Identifier, ... ] - - call: [ GTS Type Identifier, ... ] - requiredSettings: - - { key: string, secret: boolean } // credentials stored in Gears Settings +```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 ``` -- Tenant explicitly approves at installation -- Expanding permissions in new version → blocks auto-update, requires re-approval -- Reducing permissions → auto-update - ---- - -## 11. System Overview - ``` ┌─────────────────────────────────────────────────────────────┐ │ GEARS INFRASTRUCTURE │ @@ -890,6 +703,20 @@ StatePolicy { } ``` +### 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 @@ -935,6 +762,36 @@ StateTransitionEvent (projection) { ## 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 ``` @@ -1011,6 +868,38 @@ IdentityMapping extends Object { } ``` +### 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**. @@ -1039,6 +928,22 @@ 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 ``` @@ -1065,6 +970,36 @@ SavedAuditQuery extends Object { } ``` +### 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. @@ -1097,6 +1032,23 @@ Recommendation extends Object { } ``` +### D9 — Recommendation Lifecycle + +```mermaid +flowchart TD + AW["Analyzer Worker\n(schedule/onEvent/onDemand)"] -->|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 standard Worker `trigger` with @@ -1118,6 +1070,34 @@ 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 @@ -1126,6 +1106,19 @@ 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 @@ -1221,6 +1214,35 @@ NotificationSubscription extends Object { } ``` +### 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` @@ -1515,812 +1537,576 @@ allowedNextSteps: ``` entryConstraints: release (state: candidate) mandatorySteps: gap_analysis_validator - test_coverage_validator (>= 80%) - security_scan_validator - tech_lead_approval -``` - -### 22.3 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) - -### 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 } -} -``` - ---- - -## 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~ -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 (service, module, library, subsystem) -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~ -``` - -### 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 -``` - -### 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~ -``` - -### 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 -``` - -### 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) -``` - -### 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 + test_coverage_validator (>= 80%) + security_scan_validator + tech_lead_approval ``` -### Domain 10 — Operations / Incidents +### 22.3 Worker Metadata +All Workers and Flows carry UI metadata: ``` -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 +metadata: { + displayName: string + description: string + category: quality|security|ops|ai-cost|traceability + icon?: string + profile: realtime|scheduled|on_demand +} ``` -### 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 -``` +## 23. Traceability Cross-References (Killer Workflows) -### Domain 12 — Compliance / Governance +### D19 — SDLC Traceability Chain -``` -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.cost_report.v1~ // AI cost, infrastructure cost +```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"] ``` -### Domain 13 — People / Teams +### D20 — Design-to-Code Traceability -``` -cf.studio.core.person.v1~ -cf.studio.core.team.v1~ -cf.studio.core.org_unit.v1~ // department, division +```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"] ``` -### Domain 14 — Infrastructure +### 23.1 pull_request references ``` -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~ +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 +} ``` -### Domain 15 — Documents +### 23.2 test_case references ``` -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 +test_case { + verifiesRequirements: requirement[] // direct coverage link + verifiesFeature?: feature_spec // optional detailed spec +} ``` -### Domain 16 — AI / Agents +### 23.3 pr_design_validator (SDLC Kit) ``` -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~ -// llm_model → reference to Gears Models Registry (no separate Object type) +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 } +} ``` --- -### Domain 19 — Validation & Evidence +## Appendix A — Studio v2 Object Type Catalog +All types follow the pattern: ``` -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 +gts.cf.studio.core.object.v1~cf.studio.core..v1~ ``` ---- - -### 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 +### Base Types (abstract) ``` -// 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~ +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 -## Object Reference Diagrams +``` +cf.studio.core.prd.v1~ // → document +cf.studio.core.epic.v1~ +cf.studio.core.user_story.v1~ +cf.studio.core.requirement.v1~ +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) +``` -> These diagrams show **cross-references** between Studio Objects — who points to whom in the live graph. +### 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 (service, module, library, subsystem) +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~ +``` -### D18 — WorkerRun Cross-References +### D32 — Component Cross-References ```mermaid classDiagram - class WorkerRun { - workerId: ref Worker - parentRunId: ref WorkerRun? - state: pending|running|done|failed + class component { + name: string + kind: service|library|module|subsystem + ownerId: ref team + repositoryId: ref repository } - class Worker { - id: GTS Type ID + class component_version { + componentId: ref component + version: semver + commitId: ref commit } - class Object { - id: GTS Instance ID + class component_dependency { + sourceId: ref component + targetId: ref component + kind: uses|implements|extends|calls } - class FlowRun { - flowId: ref Flow + class team { + name: string + } + class repository { + url: string } - WorkerRun --> Worker : workerId - WorkerRun --> WorkerRun : parentRunId (sub-call tree) - WorkerRun --> Object : inputData references - WorkerRun --> Object : outputData produces - FlowRun --> WorkerRun : completedSteps + component "1" --> "many" component_version + component "1" --> "many" component_dependency : sourceId + component_dependency --> component : targetId + component --> team : ownerId + component --> repository : repositoryId ``` ---- - -### D19 — SDLC Traceability Chain +### D33 — Component ↔ Documentation & Architecture ```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"] + 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"] ``` ---- - -### D20 — Design-to-Code Traceability +### D38 — Dependency Graph Between Components ```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"] + 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 -### D21 — Version Control Cross-References +``` +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 repository { - url: string - defaultBranch: string + class tech_stack { + componentId: ref component + description: string } - class branch { - repositoryId: ref repository + class library { name: string + ecosystem: npm|pypi|maven|cargo|nuget|gem } - class commit { - branchId: ref branch - sha: string - authorId: ref person + class library_version { + libraryId: ref library + version: semver + licenseId: string? } - class pull_request { - repositoryId: ref repository - sourceBranch: ref branch - targetBranch: ref branch + class framework { + name: string + language: string } - class tag { - commitId: ref commit + class runtime { name: string + version: string } - repository "1" --> "many" branch - branch "1" --> "many" commit - commit "many" --> "1" pull_request : included in - commit "1" --> "many" tag -``` - ---- - -### 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"] + tech_stack --> library_version : uses + tech_stack --> framework : uses + tech_stack --> runtime : targets + library_version --> library : libraryId ``` ---- - -### D23 — Deployment & Environment Cross-References +### D40 — Data & External Service Dependencies ```mermaid classDiagram - class deployment { - artifactId: ref build_artifact - environmentId: ref environment - state: pending|running|done|failed + class tech_stack { + componentId: ref component } - class build_artifact { - jobId: ref pipeline_job - version: string + class database { + engine: postgres|mongo|redis|mysql|elastic + kind: relational|document|kv|search|timeseries } - class environment { - name: dev|staging|prod - tenantId: ref Tenant + class database_instance { + databaseId: ref database + environmentId: ref environment + host: string } - class deployment_status { - deploymentId: ref deployment - state: string - workerRunId: ref WorkerRun + 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 } - deployment --> build_artifact : artifactId - deployment --> environment : environmentId - deployment "1" --> "many" deployment_status + 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 ``` ---- - -### D24 — Incident & Operations Cross-References +### D41 — Component ↔ Technology Stack ```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)"] + 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)"] ``` ---- - -### D25 — Security Cross-References +### Domain 4 — Work Items -```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"] +``` +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 -### D26 — Recommendation Cross-References +``` +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 +``` -```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 - } +### Domain 6 — Version Control - 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) +``` +// 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~ ``` ---- - -### D27 — Workspace & Kit Cross-References +### D21 — Version Control Cross-References ```mermaid classDiagram - class Workspace { - tenantId: ref Tenant - sources: SourceEntry[] - } - class SourceEntry { - path: string - url: string? - role: string - } class repository { url: string + defaultBranch: string } - class Kit { - scope: local|project|workspace|published - requiredPermissions: Permission[] + 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 Tenant { - parentId: ref Tenant? + class tag { + commitId: ref commit + name: string } - Workspace "1" --> "many" SourceEntry : sources - SourceEntry --> repository : resolves to - Tenant "1" --> "many" Kit : installed Kits - Workspace --> Tenant : tenantId + repository "1" --> "many" branch + branch "1" --> "many" commit + commit "many" --> "1" pull_request : included in + commit "1" --> "many" tag ``` ---- +### Domain 7 — CI/CD / Build -### D28 — Role & Identity Cross-References +``` +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 User { - tenantId: ref Tenant + class pipeline { + definition: YAML ref + scope: string } - class Role { - tenantId: ref Tenant - name: string + class pipeline_run { + pipelineId: ref pipeline + state: pending|running|done|failed + triggeredBy: commit|schedule|manual } - class RoleAssignment { - userId: ref User - roleId: ref Role - assignedBy: ref User + class pipeline_job { + runId: ref pipeline_run + runner: ref runner } - class IdentityMapping { - externalPattern: object - roleId: ref Role - tenantId: ref Tenant + class pipeline_step { + jobId: ref pipeline_job + state: string } - class PolicyOverride { - policyId: ref Policy - tenantId: ref Tenant + class build_artifact { + jobId: ref pipeline_job + path: string + expiresAt: datetime? + } + class deployment { + artifactId: ref build_artifact + environment: ref environment } - User "many" --> "many" Role : via RoleAssignment - IdentityMapping --> Role : maps external identity to - Role --> PolicyOverride : governed by - Tenant --> IdentityMapping : scoped to + 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 -### D29 — AuditLog & SavedQuery 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 WorkerRun { - workerId: ref Worker - inputData: any - outputData: any - externalEvents: ExternalEvent[] + class deployment { + artifactId: ref build_artifact + environmentId: ref environment + state: pending|running|done|failed } - class ExternalEvent { - source: string - externalId: string - url: string + class build_artifact { + jobId: ref pipeline_job + version: string } - class SavedAuditQuery { - createdBy: ref User + class environment { + name: dev|staging|prod tenantId: ref Tenant - query: QuerySpec } - class AuditLog { - materialized view - over WorkerRun tree + class deployment_status { + deploymentId: ref deployment + state: string + workerRunId: ref WorkerRun } - WorkerRun "1" --> "many" ExternalEvent : write-ahead - WorkerRun ..> AuditLog : materializes into - SavedAuditQuery ..> AuditLog : queries + deployment --> build_artifact : artifactId + deployment --> environment : environmentId + deployment "1" --> "many" deployment_status ``` ---- +### Domain 8 — Artifacts / Packages -### D30 — Notification Cross-References +``` +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 NotificationRule { - trigger: EventPattern - audience: RolePattern - channel: string - } - class NotificationRuleOverride { - ruleId: ref NotificationRule - active: boolean - expiresAt: datetime? + class sbom { + format: spdx|cyclonedx|swid + version: string + createdAt: datetime + artifactId: ref build_artifact + releaseId: ref release? } - class NotificationSubscription { - userId: ref User - tenantId: ref Tenant - urgency: immediate|digest|muted + class sbom_component { + sbomId: ref sbom + name: string + version: string + supplier: string? } - class User { - tenantId: ref Tenant + class sbom_relationship { + sbomId: ref sbom + sourceId: ref sbom_component + targetId: ref sbom_component + kind: CONTAINS|DEPENDS_ON|DESCRIBES|GENERATED_FROM|VARIANT_OF } - NotificationRuleOverride --> NotificationRule : ruleId - NotificationSubscription --> User : userId - User --> NotificationSubscription : personal subscriptions - NotificationRule --> NotificationRuleOverride : overridden by -``` - ---- - -### 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 + sbom "1" --> "many" sbom_component : DESCRIBES + sbom "1" --> "many" sbom_relationship + sbom_relationship --> sbom_component : sourceId + sbom_relationship --> sbom_component : targetId ``` ---- - -### D32 — Component Cross-References +### D45 — SBOM Component Details ```mermaid classDiagram - class component { + class sbom_component { + sbomId: ref sbom name: string - kind: service|library|module|subsystem - ownerId: ref team - repositoryId: ref repository + version: string } - class component_version { - componentId: ref component - version: semver - commitId: ref commit + class sbom_license { + componentId: ref sbom_component + spdxExpression: string + concluded: string? + declared: string? } - class component_dependency { - sourceId: ref component - targetId: ref component - kind: uses|implements|extends|calls + class sbom_checksum { + componentId: ref sbom_component + algorithm: SHA256|SHA1|MD5|BLAKE2 + value: string } - class team { - name: string + class library_version { + libraryId: ref library + version: semver } - class repository { - url: string + class dependency_vulnerability { + packageName: string + affectedVersions: string[] } - component "1" --> "many" component_version - component "1" --> "many" component_dependency : sourceId - component_dependency --> component : targetId - component --> team : ownerId - component --> repository : repositoryId + sbom_component "1" --> "many" sbom_license + sbom_component "1" --> "many" sbom_checksum + sbom_component --> library_version : maps to + sbom_component --> dependency_vulnerability : may have ``` ---- - -### D33 — Component ↔ Documentation & Architecture +### D46 — SBOM Cross-References ```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"] + 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)"] ``` ---- - -### D34 — Component ↔ People & Teams +### D47 — SBOM ↔ Security & Compliance ```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 +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 @@ -2353,8 +2139,6 @@ classDiagram build_artifact --> deployment : deployed as ``` ---- - ### D36 — Release ↔ Work Items & Traceability ```mermaid @@ -2368,8 +2152,6 @@ flowchart LR REL -->|documents| RN["release_notes\n→ document"] ``` ---- - ### D37 — Full Component → Release → Deployment Chain ```mermaid @@ -2384,226 +2166,339 @@ flowchart TD DEP -->|targets| ENV["environment"] ``` ---- +### D43 — Tech Stack ↔ Release & Compliance -### D38 — Dependency Graph Between Components +```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 - 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 + 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 -### D39 — Technology Stack Types +``` +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 tech_stack { - componentId: ref component + class vulnerability { + severity: critical|high|medium|low + cveId: string? + state: open|fixed|ignored + } + class cve { + cvssScore: float description: string } - class library { - name: string - ecosystem: npm|pypi|maven|cargo|nuget|gem + class security_finding { + source: pentest|code_scan|secret_scan + severity: string } - class library_version { - libraryId: ref library - version: semver - licenseId: string? + class dependency_vulnerability { + packageName: string + affectedVersions: string[] + fixedVersion: string? } - class framework { + 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.cost_report.v1~ // AI cost, infrastructure cost +``` + +### 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 - language: string } - class runtime { + 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 } - tech_stack --> library_version : uses - tech_stack --> framework : uses - tech_stack --> runtime : targets - library_version --> library : libraryId + infra_config <|-- terraform_resource + infra_config <|-- helm_release + infra_config <|-- k8s_manifest ``` ---- +### Domain 15 — Documents -### D40 — Data & External Service Dependencies +``` +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 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 + class document { + content: string + version: semver + ownerId: ref User } - 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 + document <|-- spec + document <|-- guide + document <|-- readme + document <|-- wiki_page + document <|-- api_documentation + document <|-- prd + document <|-- adr ``` ---- - -### D41 — Component ↔ Technology Stack +### D12 — Document Type Hierarchy (continued) ```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)"] +classDiagram + class document + + document <|-- design + document <|-- feature_spec + document <|-- decomposition + document <|-- runbook + document <|-- postmortem + document <|-- release_notes + document <|-- meeting_note ``` ---- +### Domain 16 — AI / Agents -### D42 — Library Version ↔ Security +``` +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~ +// llm_model → reference to Gears Models Registry (no separate Object type) +``` + +### D13 — Prompt Type Hierarchy ```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)"] +classDiagram + class prompt { + content: string + version: semver + } + + prompt <|-- skill + prompt <|-- system_prompt + prompt <|-- prompt_template + prompt <|-- prompt_variant ``` --- -### D43 — Tech Stack ↔ Release & Compliance +### Domain 19 — Validation & Evidence -```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"] +``` +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 ``` --- -### 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 - } +### Notes - sbom "1" --> "many" sbom_component : DESCRIBES - sbom "1" --> "many" sbom_relationship - sbom_relationship --> sbom_component : sourceId - sbom_relationship --> sbom_component : targetId -``` +- **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. --- -### 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[] - } +### Vendor Kit Extension Examples - sbom_component "1" --> "many" sbom_license - sbom_component "1" --> "many" sbom_checksum - sbom_component --> library_version : maps to - sbom_component --> dependency_vulnerability : may have ``` +// 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~ -### D46 — SBOM Cross-References +// 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~ -```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)"] -``` +// 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~ -### D47 — SBOM ↔ Security & Compliance +// 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~ -```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)"] +// 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~ ``` --- From b6523f6de8c4bcec6c3b731b235c4e580dfab9ca Mon Sep 17 00:00:00 2001 From: ainetx Date: Sun, 5 Jul 2026 13:32:51 +0300 Subject: [PATCH 009/106] =?UTF-8?q?docs(v2):=20add=20Worker.kind,=20Worker?= =?UTF-8?q?Run.cost,=20=C2=A724=20SDLC=20Action=20Workers,=20=C2=A725=20Pl?= =?UTF-8?q?atform=20Workers?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: ainetx Co-authored-by: Constructor Studio <291158726+constructor-studio[bot]@users.noreply.github.com> Studio-Generated-By: Constructor Studio Studio-Source-Repo: https://github.com/constructorfabric/studio Constructor-Fabric: https://github.com/constructorfabric Studio-Version: skill=1.5.9, cli=1.5.10.dev73 Studio-Workflows: cf-brainstorm --- v2/docs/domain-model.md | 101 +++++++++++++++++++++++++++++++++++++++- 1 file changed, 100 insertions(+), 1 deletion(-) diff --git a/v2/docs/domain-model.md b/v2/docs/domain-model.md index 7db8d68b..d5528179 100644 --- a/v2/docs/domain-model.md +++ b/v2/docs/domain-model.md @@ -189,6 +189,7 @@ Executor — consumes Objects, produces Objects. Registry entity. ``` Worker { id: GTS Type Identifier (gts.cf.studio.core.worker.v1~...) + kind: action | analyzer | validator | utility input: Contract (GTS Type Schema) output: Contract (GTS Type Schema) dependencies: Worker[] (static list — security boundary) @@ -305,6 +306,12 @@ WorkerRun extends Object { { source: string, type: string, externalId: string, url: string } ] checkpointExpiresAt: datetime? + cost?: { + promptTokens: int + completionTokens: int + modelId: string // GTS Type ID from Gears Models Registry + estimatedCostUSD: float + } // only populated for runtime: llm | hybrid staticChildren: WorkerRun[] } ``` @@ -1542,7 +1549,33 @@ mandatorySteps: gap_analysis_validator tech_lead_approval ``` -### 22.3 Worker Metadata +**`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: ``` @@ -1616,6 +1649,72 @@ pr_design_validator extends Validator { --- +## 24. SDLC Action Workers + +Action Workers (`kind: action`) are the "executable edges" of the Studio graph — they drive state transitions between Objects. All require `automationLevel >= approved_automation AND category in approvedWorkerCategories` (Gate 1) before a WorkerRun is created. + +### 24.1 Action 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[] | + +### 24.2 Approval Gates + +Action Workers are governed by two independent gates: + +**Gate 1 — Studio execution gate** (checked at WorkerRun creation): +``` +automationLevel >= approved_automation +AND Worker.kind == action +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 +kind: utility +``` + +| 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. | + +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. + +--- + ## Appendix A — Studio v2 Object Type Catalog All types follow the pattern: From a3bd663223c3e3f04b28e838fa90f923183e5d55 Mon Sep 17 00:00:00 2001 From: ainetx Date: Sun, 5 Jul 2026 14:08:36 +0300 Subject: [PATCH 010/106] docs(v2): add user-journeys.md with 14 ALGORITHM-format user scenarios Signed-off-by: ainetx Co-authored-by: Constructor Studio <291158726+constructor-studio[bot]@users.noreply.github.com> Studio-Generated-By: Constructor Studio Studio-Source-Repo: https://github.com/constructorfabric/studio Constructor-Fabric: https://github.com/constructorfabric Studio-Version: skill=1.5.9, cli=1.5.10.dev73 Studio-Workflows: cf-brainstorm --- v2/docs/user-journeys.md | 912 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 912 insertions(+) create mode 100644 v2/docs/user-journeys.md diff --git a/v2/docs/user-journeys.md b/v2/docs/user-journeys.md new file mode 100644 index 00000000..5dcb1b62 --- /dev/null +++ b/v2/docs/user-journeys.md @@ -0,0 +1,912 @@ +# Studio v2 — User Journeys + +## Introduction + +This document describes the fourteen primary user journeys in Studio v2. Each journey +traces the full path a user takes from intent to outcome, showing which Objects, Workers, +Flows, and Connectors 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 +- `STEPS` — the ordered sequence of actions, Workers, and Flows invoked +- `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`) +- `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`. + +--- + +## Journey Index + +| # | Journey | Actor | Goal | Workers / Flows | Cost Tier | Automation Gate | +|---|---------|-------|------|-----------------|-----------|-----------------| +| 1 | Product intent → decomposed tasks | Product Manager | prd → design → task[] in Jira | `create_design_worker` → `decompose_feature_worker` | high | approved_automation | +| 2 | Requirement gap detection | Product Manager | Detect uncovered requirements | `gap_analysis`, `traceability_analysis` | medium | none | +| 3 | Bug report → Fix PR | Developer | bug → reproduction → failing test → PR | `bug_to_fix_pr_flow` | high | approved_automation | +| 4 | Feature task → Pull Request | Developer | task → code → PR with design conformance | `implement_code_worker`, `create_pr_worker`, `pr_design_validator` | high | approved_automation | +| 5 | Accept a Recommendation | Developer | Act on an Analyzer-created Recommendation | `validationWorker` + `suggestedWorker` | low–high | approved_automation | +| 6 | PR conformance to design | Tech Lead | Validate PR against design (automatic) | `pr_design_validator` | medium | none | +| 7 | Architecture drift detection | Architect | Detect component drift from design | `architecture_drift_detection` | medium | none | +| 8 | Raise automationLevel | Architect | Unlock action Workers for a Tenant | StatePolicy transition + Approval | low | none | +| 9 | Release readiness review | Release Manager | Gate release candidate on validators | `release_readiness_review` | medium | none | +| 10 | Incident → Postmortem | SRE / On-call | incident → postmortem + prevention tasks | `incident_to_postmortem_flow` | medium–high | approved_automation | +| 11 | Deploy to environment | DevOps | build_artifact → deployment | `deploy_worker` | low | approved_automation | +| 12 | Security exception approval | Security Lead | Approve a vulnerability exception | `security_impact_analysis` + Approval | low | none | +| 13 | SBOM security scan | Security Engineer | Scan build_artifact for vulnerable deps | `security_impact_analysis` | medium | none | +| 14 | External system inbound sync | (platform) | Connector event → Object in graph | `connector_inbound_sync_worker` | low | none | + +--- + +## Journeys + +### Journey 1: Product Intent → Decomposed Tasks + +```text +ALGORITHM ProductIntentToDecomposedTasks + ACTOR: Product Manager + GOAL: Turn a product requirement document into a validated design and + an ordered task list written back to Jira + INPUTS: [ + prd (state: draft) — authored externally or in Studio, + workspace configured with Jira Connector [sync: jira] + ] + OUTPUTS: [ + design (state: approved) — linked to prd, + decomposition — ordered feature list, + task[] [write-back: jira] — Jira issues with traceability to prd + design + ] + COST TIER: high (create_design_worker + decompose_feature_worker, both llm) + AUTOMATION GATE: approved_automation + STEPS: + 1. PM selects prd Object in Studio UI or CLI. + 2. Studio invokes create_design_worker (llm, on_demand): + - Input: prd, workspace, optional style (detailed | sketch) + - Output: design (state: draft) + 3. gap_analysis_validator (hybrid, realtime) runs automatically: + - Checks prd FR coverage in candidate design + - ValidationSession created; on fail → design sent back with gaps + 4. DECISION: Design acceptable? + - YES: design state → approved (StatePolicy transition) + - NO: PM edits design manually or re-runs create_design_worker + with amended prd + 5. Studio invokes decompose_feature_worker (llm, on_demand): + - Input: design, prd, optional team capacity hint + - Output: decomposition + task[] (state: planned) + 6. DECISION: Review tasks before write-back? + - YES: PM reviews task[] in Studio; edits names, priorities, owners + - NO: proceed directly to step 7 + 7. connector_outbound_sync_worker writes task[] to Jira via + WriteBackPolicy (requiresApproval based on Tenant automationLevel). + DECISION: Approval required? + - Gate 2 (WriteBackPolicy.requiresApproval = true): + Approval Object created; PM or Tech Lead approves; write-back executes. + - Gate 2 (requiresApproval = false): write-back executes immediately. + DECISION_POINTS: + - DesignAcceptance: approve design / re-run with amendments + - TaskReviewBeforeWriteBack: review first / write-back immediately + - WriteBackApproval: Approval required (Gate 2) / immediate + GUARDS: [ + automationLevel >= approved_automation before create_design_worker + or decompose_feature_worker can be invoked, + gap_analysis_validator must pass (or PM explicitly overrides) before + design state can advance to approved, + task[] write-back to Jira must satisfy WriteBackPolicy.allowedActions, + prd must have at least one requirement before create_design_worker runs + ] + NEXT: Journey 3 (bug fix) or Journey 4 (feature implementation) per task +``` + +--- + +### Journey 2: Requirement Gap Detection + +```text +ALGORITHM RequirementGapDetection + ACTOR: Product Manager + GOAL: Identify requirements that lack design coverage, implementation + tasks, or test cases, and receive actionable Recommendations + INPUTS: [ + requirement[] — in Studio graph (may be [sync: jira] or native), + task[] [sync: jira], + test_case[] [sync: github / test management tool], + pull_request[] [sync: github] + ] + OUTPUTS: [ + Recommendation[] (state: pending) — one per detected gap, + traceability report — coverage links visualized + ] + COST TIER: medium (gap_analysis hybrid + traceability_analysis hybrid) + AUTOMATION GATE: none + STEPS: + 1. gap_analysis Analyzer Worker runs on schedule or on_demand: + - Scans requirement[], task[], test_case[], pull_request[] + - Creates Recommendation for each uncovered requirement + - Example: "requirement R-17 has no task and no test_case" + 2. traceability_analysis Analyzer Worker runs in parallel: + - Maps requirement → design → task → pull_request → test_case chains + - Creates Recommendation for broken links in the chain + 3. PM views Recommendation[] in Studio UI: + - severity: info | warning | critical + - confidence: full | partial (when external system unavailable) + 4. DECISION: Act on Recommendations? + - YES: PM accepts Recommendations → Journey 1 (create tasks) or + assigns tasks to developers manually + - DISMISS: PM dismisses with reason; Recommendation state → dismissed + - SNOOZE: PM sets validationWorker re-check schedule + DECISION_POINTS: + - AnalysisTrigger: scheduled (default: nightly) / on_demand + - RecommendationAction: accept / dismiss / snooze re-check + GUARDS: [ + Read-only — Analyzers never modify Objects, + Recommendations created only if gap persists after re-check; + stale Recommendations invalidated automatically when gap closes, + confidence: partial allowed when external Connectors unavailable + (Analyzer continues with available data) + ] + NEXT: Journey 1 (create design + tasks), or Journey 4 (implement feature) +``` + +--- + +### Journey 3: Bug Report → Fix PR + +```text +ALGORITHM BugToFixPR + ACTOR: Developer + GOAL: Turn an open bug report into a validated pull request with a + reproduction test, a fix, and Evidence from all Validators + INPUTS: [ + bug (state: open) [sync: jira], + component[] — in Studio graph, + repository [sync: github] + ] + OUTPUTS: [ + test_case — failing test proving reproduction, + pull_request (state: review) [write-back: github], + ValidationSession[] + Evidence — one per mandatory Validator, + WorkerRun[] — full execution trail + ] + COST TIER: high (4 LLM Workers in chain) + AUTOMATION GATE: approved_automation + STEPS: + 1. Developer selects bug Object in Studio UI. + Flow: bug_to_fix_pr_flow activates (entryConstraints: bug, state: open). + 2. bug_description_validator (hybrid, realtime): + - Validates bug has sufficient reproduction info + - ValidationSession created; on fail → bug returned for enrichment + 3. find_suspected_component (hybrid, on_demand): + - Input: bug → Output: component[] (ranked by suspicion) + 4. deploy_test_environment (script, on_demand): + - Input: component → Output: environment (ephemeral test env) + 5. reproduce_bug (hybrid, on_demand): + - Input: bug, environment → Output: WorkerRun with reproduction Evidence + 6. create_failing_test (llm, on_demand): + - Input: bug, reproduce output → Output: test_case (state: failing) + 7. confirm_test_fails_validator (script, realtime): + - Runs test_case against baseline; validates it fails + - ValidationSession; on fail → loop back to create_failing_test + 8. implement_fix (llm, on_demand): + - Input: bug, test_case → Output: source_file[] (fix) + 9. confirm_test_passes_validator (script, realtime): + - Runs test_case against fix; validates it passes + - ValidationSession; on fail → loop back to implement_fix + 10. create_pr_worker (hybrid, on_demand): + - Input: source_file[], branch → Output: pull_request [write-back: github] + - pull_request.verifiedBy = [test_case] + - pull_request.closesIssues = [bug] + DECISION: Write-back approval required? + - Gate 2 applies if WriteBackPolicy.requiresApproval = true for github + DECISION_POINTS: + - BugDescriptionSufficiency: pass validator / enrich bug first + - FixLoopRetry: confirm_test_passes fails → re-run implement_fix + (up to Validator.maxRetries; then Approval escalation) + - WriteBackApproval: Gate 2 (github write-back) required / immediate + GUARDS: [ + automationLevel >= approved_automation for all action Workers, + bug_description_validator must pass before find_suspected_component runs, + test_case must demonstrate failure on baseline before implement_fix runs, + pull_request.verifiedBy must reference the test_case produced in step 6, + all three Validator WorkerRuns must reach state: done with Evidence + before pull_request is created + ] + NEXT: Journey 6 (pr_design_validator fires automatically on PR creation), + or Journey 9 (release readiness) when PR is merged +``` + +--- + +### Journey 4: Feature Task → Pull Request + +```text +ALGORITHM FeatureTaskToPullRequest + ACTOR: Developer + GOAL: Implement a feature from a task with feature_spec linked, + produce a PR, and get automatic design conformance validation + INPUTS: [ + task (state: in_progress) [sync: jira], + feature_spec — linked to task, + 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 + ] + COST TIER: high (implement_code_worker llm + create_pr_worker hybrid) + AUTOMATION GATE: approved_automation + STEPS: + 1. Developer selects task Object linked to feature_spec in Studio UI. + 2. implement_code_worker (llm, on_demand): + - Input: feature_spec, task → Output: source_file[] + - Writes implementation; traceability markers link code to feature_spec IDs + 3. create_pr_worker (hybrid, on_demand): + - Input: source_file[], branch → Output: pull_request [write-back: github] + - pull_request.implementsRequirements = [requirement refs from feature_spec] + - pull_request.closesIssues = [task] + 4. pr_design_validator fires automatically (realtime, onEvent: PR → review): + - Input: pull_request, design[], acceptance_criteria[] + - Output: ValidationSession + ValidationResult + Evidence + - On fail: pull_request annotated with findings; developer fixes + 5. DECISION: Conformance pass? + - PASS: pull_request.conformsToDesign[] populated with Evidence; + PR ready for human review + - FAIL: developer amends source_file[]; create_pr_worker re-runs; + pr_design_validator re-fires (up to maxRetries; then Approval escalation) + DECISION_POINTS: + - ConformanceResult: pass immediately / fail-and-fix loop + - WriteBackApproval: Gate 2 (github write-back) per Tenant policy + GUARDS: [ + automationLevel >= approved_automation for implement_code_worker + and create_pr_worker, + feature_spec must be linked to task before implement_code_worker runs, + 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 + ] + NEXT: Journey 6 (design conformance fires automatically), + Journey 9 (release readiness after merge) +``` + +--- + +### Journey 5: Accept a Recommendation + +```text +ALGORITHM AcceptRecommendation + ACTOR: Developer (or PM / Tech Lead depending on Recommendation severity) + GOAL: Act on an Analyzer-created Recommendation by running the + suggested fix Worker, verifying the gap is closed, and reaching + state: done + INPUTS: [ + Recommendation (state: pending) — created by an Analyzer Worker, + Objects referenced by Recommendation.suggestedInput + ] + OUTPUTS: [ + Recommendation (state: done), + Object — updated by suggestedWorker output, + WorkerRun — execution record of the fix + ] + COST TIER: low–high (depends on suggestedWorker runtime) + AUTOMATION GATE: approved_automation (for suggestedWorker if kind: action) + STEPS: + 1. User sees Recommendation in Studio UI (notification or dashboard). + Recommendation shows: reason, severity, confidence, suggestedWorker, + suggestedInput (pre-filled from last re-check). + 2. DECISION: Re-check before accepting? + - YES: validationWorker runs; checks gap still exists; refreshes + suggestedInput to current Object state; recomputes severity + if severityWorker set. + DECISION: Gap still present? + - YES: proceed to step 3 with refreshed suggestedInput + - NO: Recommendation state → invalidated (gap closed already) + - NO (accept as-is): proceed to step 3 + 3. DECISION: suggestedInput changed since Recommendation created? + - YES: Studio shows diff of suggestedInput; user confirms or cancels + - NO: proceed directly + 4. User accepts Recommendation → state: accepted. + suggestedWorker invoked (automationLevel gate checked): + - Recommendation state → executing + - WorkerRun created for suggestedWorker + 5. suggestedWorker completes: + - Recommendation state → done + - Output Object updated with fix + 6. DECISION: Write-back to external system? + - If suggestedWorker output triggers Connector write-back: + Gate 2 (WriteBackPolicy) applies + DECISION_POINTS: + - ReCheckBeforeAccepting: yes / no + - InputChangedConfirmation: confirm updated input / cancel + - WriteBackApproval: Gate 2 if output touches external system + GUARDS: [ + automationLevel >= approved_automation if suggestedWorker is kind: action, + suggestedInput must be confirmed by user if it changed since Recommendation + was created, + Recommendation state machine: pending → accepted → executing → done; + no skipping states, + validationWorker re-check must complete before suggestedInput diff is shown + ] + NEXT: Depends on suggestedWorker output (may chain into Journey 3 or 4) +``` + +--- + +### Journey 6: PR Conformance to Design (Automatic) + +```text +ALGORITHM PRConformanceToDesign + ACTOR: Tech Lead (reviewer) — Studio triggers automatically + GOAL: Validate a pull request against the linked design documents + and acceptance criteria; attach Evidence to the PR + INPUTS: [ + pull_request (state: review) [sync: github], + design[] — linked via pull_request.conformsToDesign refs, + acceptance_criteria[] — from feature_spec or task + ] + OUTPUTS: [ + ValidationSession (state: pass | fail | escalated), + ValidationResult + Evidence attached to pull_request, + Recommendation if non-critical conformance gaps found + ] + COST TIER: medium (pr_design_validator hybrid) + AUTOMATION GATE: none (Validator runs at any automationLevel) + STEPS: + 1. pr_design_validator fires automatically (realtime, onEvent): + trigger: pull_request state_changed → review + 2. Validator reads pull_request diff, design[], acceptance_criteria[]. + 3. DECISION: Conformance result? + - PASS: ValidationResult (state: pass) + Evidence created; + pull_request.conformsToDesign[] populated. + Tech Lead notified (NotificationRule). + - FAIL (within maxRetries): ValidationResult (state: fail); + pull_request annotated with findings list; + developer notified to amend. + Developer pushes fix → pr_design_validator re-fires. + - FAIL (retries exhausted): ValidationSession state → escalated; + Approval (kind: risk_acceptance) created for Tech Lead; + Tech Lead approves exception or rejects PR. + 4. Tech Lead reviews ValidationResult in Studio UI (or GitHub comment + from Connector write-back if configured). + DECISION_POINTS: + - ConformanceOutcome: pass / fail-and-retry / escalate + - EscalationDecision: approve exception / reject PR + GUARDS: [ + pr_design_validator fires on every push to the PR branch, not just once, + ValidationResult must be attached to pull_request before state can + advance to approved, + Escalation Approval must be resolved before ValidationSession closes, + Evidence is immutable once created (state: valid); revocation requires + explicit revokedBy + revokedAt + ] + NEXT: Journey 9 (release readiness) after PR merged +``` + +--- + +### Journey 7: Architecture Drift Detection + +```text +ALGORITHM ArchitectureDriftDetection + ACTOR: Chief Architect / Tech Lead + GOAL: Detect components that have drifted from their design + specification and receive prioritized Recommendations + INPUTS: [ + component[] — in Studio graph, + component_dependency[] — current dependency graph, + design[] — reference architecture documents, + repository [sync: github] — for code-level evidence + ] + OUTPUTS: [ + Recommendation[] (state: pending) — one per drifted component, + architecture_drift report (WorkerRun output) + ] + COST TIER: medium (architecture_drift_detection hybrid, scheduled) + AUTOMATION GATE: none + STEPS: + 1. architecture_drift_detection Analyzer runs on schedule (or on_demand): + - Compares current component[] + component_dependency[] against design[] + - Detects: new dependencies not in design, missing components, + interface contract violations, boundary violations + - Creates Recommendation per drift with severity + evidence + 2. Architect reviews Recommendation[] in Studio UI. + 3. DECISION: Response per Recommendation? + - ACCEPT: Architect triggers update of design[] to reflect + intentional drift (Journey not covered here — cf-write-docs) + - FIX: Architect assigns task to developer to fix the drift + (task created via create_tasks_worker or manually) + - DISMISS: drift intentional; Recommendation dismissed with reason + - ADR: drift requires an Architecture Decision Record before actioning + DECISION_POINTS: + - DriftTrigger: scheduled (default: nightly) / on_demand + - DriftResponse: accept (update design) / fix (create task) / + dismiss / create ADR first + GUARDS: [ + Read-only — architecture_drift_detection never modifies Objects, + confidence: partial if repository Connector unavailable + (Analyzer continues with graph data only), + Recommendations invalidated automatically if drift closes before action taken + ] + NEXT: ADR authoring (if architecture_decision required), + Journey 4 (implement fix), or Journey 2 (broader gap analysis) +``` + +--- + +### Journey 8: Raise automationLevel + +```text +ALGORITHM RaiseAutomationLevel + ACTOR: Architect / CTO + GOAL: Unlock action Workers for a Tenant by raising automationLevel, + gated by an Approval requiring an architecture decision + INPUTS: [ + Tenant (current automationLevel: recommendations | readonly), + proposed automationLevel: approved_automation | enterprise + ] + OUTPUTS: [ + Approval (kind: architecture_decision, state: approved), + Tenant.automationLevel updated, + Tenant.approvedWorkerCategories updated + ] + COST TIER: low (StatePolicy transition + Approval; human-driven) + AUTOMATION GATE: none (this journey IS the gate) + STEPS: + 1. Architect initiates automationLevel raise in Studio UI. + 2. Studio checks StatePolicy for Tenant.automationLevel transition: + raising automationLevel → requiresApproval (always). + 3. Approval Object created: + kind: architecture_decision + payload: { proposedLevel, approvedWorkerCategories, rationale, + customerImpact? } + requiredRole: CTO | VP Engineering (per Tenant policy) + 4. Approver receives notification (NotificationRule: Approval pending). + 5. DECISION: Approver action? + - APPROVE: Tenant.automationLevel updated; + Tenant.approvedWorkerCategories updated; + action Workers of approved categories now available. + - REJECT: Approval state → rejected; automationLevel unchanged. + - EXPIRE: Approval.expiresAt reached without decision; + new Approval required. + 6. DECISION: Lowering automationLevel later? + - No Approval required (narrowing, not expanding); immediate. + DECISION_POINTS: + - ApproverDecision: approve / reject / expire + - CategoryScope: which Worker categories to approve + (studio.category in approvedWorkerCategories) + - LowerLater: immediate (no Approval needed) + GUARDS: [ + Approval is mandatory for any automationLevel raise; no bypass, + Tenant.approvedWorkerCategories must be set alongside automationLevel + change — empty list blocks all action Workers even at approved_automation, + Lowering automationLevel requires no Approval but immediately + blocks action Workers in removed categories, + customerImpact field required when automationLevel >= enterprise + ] + NEXT: Journeys 1, 3, 4, 10, 11 now available (action Workers unlocked) +``` + +--- + +### Journey 9: Release Readiness Review + +```text +ALGORITHM ReleaseReadinessReview + ACTOR: Release Manager / Tech Lead + GOAL: Gate a release candidate on automated validators and a required + Tech Lead approval, producing Evidence for the release audit trail + INPUTS: [ + release (state: candidate), + release_component[] — component versions in this release, + test_run[] [sync: github / CI], + pull_request[] [sync: github] — merged PRs for this release, + vulnerability[] [sync: snyk / dependabot] + ] + OUTPUTS: [ + release (state: approved | blocked), + ValidationSession[] + Evidence — per mandatory Validator, + Approval (kind: release_approval) — Tech Lead sign-off + ] + COST TIER: medium (hybrid Validators; script test coverage check) + AUTOMATION GATE: none (Validators run at any automationLevel; + Approval is StatePolicy gate, not automationLevel gate) + STEPS: + 1. Release Manager creates release (state: candidate) in Studio. + Flow: release_readiness_review activates. + 2. gap_analysis_validator (hybrid, realtime): + - Checks all requirements in scope are implemented + tested + - ValidationSession; on fail → release blocked with gap list + 3. test_coverage_validator (script, realtime): + - Checks test coverage >= 80% for release_component[] scope + - ValidationSession; on fail → release blocked + 4. security_scan_validator (hybrid, realtime): + - Checks no critical/high vulnerability[] without approved Approval + (kind: security_exception) in release scope + - ValidationSession; on fail → release blocked unless security exceptions + are in place with valid expiresAt + 5. All three Validators pass → Approval (kind: release_approval) created: + requiredRole: tech_lead + payload: { release, Evidence[] from all validators, + customerImpact if scope != internal } + 6. Tech Lead approves → release state: approved. + 7. DECISION: Any Validator failed? + - gap_analysis: PM/Dev must close gaps; re-run gap_analysis_validator + - test_coverage: Dev must add tests; re-run test_coverage_validator + - security_scan: Security Lead must create security_exception Approval + for each outstanding vulnerability (Journey 12) + DECISION_POINTS: + - ValidatorFailureResolution: fix gaps / add tests / create security_exception + - TechLeadApprovalDecision: approve / request changes / reject + GUARDS: [ + All three mandatory Validators must reach ValidationSession.state: pass + before Approval is created, + security_exception Approvals must have valid expiresAt (not expired) + before security_scan_validator accepts them, + release state: approved requires Approval.state: approved; + StatePolicy enforces this transition, + Evidence from each Validator is immutable and attached to release audit trail + ] + NEXT: Journey 11 (deploy to environment) +``` + +--- + +### Journey 10: Incident → Postmortem + +```text +ALGORITHM IncidentToPostmortem + ACTOR: SRE / On-call Engineer + GOAL: Automatically draft a postmortem and prevention tasks from a + resolved incident + INPUTS: [ + incident (state: resolved) [sync: pagerduty / datadog], + WorkerRun[] — execution history during incident window, + alert[] [sync: datadog / pagerduty], + on_call_schedule — for postmortem ownership assignment + ] + OUTPUTS: [ + postmortem (→ document) — structured incident analysis, + task[] (prevention) [write-back: jira] — action items, + Evidence — from incident_summary_validator + ] + COST TIER: medium–high (incident_summary_validator hybrid + + postmortem_draft_worker llm + prevention_tasks_worker hybrid) + AUTOMATION GATE: approved_automation + STEPS: + 1. connector_inbound_sync_worker receives incident (state: resolved) + from PagerDuty/Datadog via Gears OAGW. + Flow: incident_to_postmortem_flow activates. + 2. incident_summary_validator (hybrid, realtime): + - Validates incident has timeline, severity, affected systems + - ValidationSession; on fail → on-call enriches incident data + 3. postmortem_draft_worker (llm, on_demand): + - Input: incident, WorkerRun[] (execution history), alert[] + - Output: postmortem (state: draft) with: + timeline, root cause, contributing factors, impact assessment + 4. prevention_tasks_worker (hybrid, on_demand): + - Input: postmortem → Output: task[] (prevention actions) + - Tasks linked to postmortem.closedBy and relevant component[] + 5. On-call Engineer reviews postmortem in Studio UI: + DECISION: Postmortem acceptable? + - YES: postmortem state → published + - EDIT: Engineer edits draft directly; re-runs prevention_tasks_worker + if root cause changes + 6. task[] [write-back: jira] via connector_outbound_sync_worker + (Gate 2: WriteBackPolicy for jira write-back). + DECISION_POINTS: + - IncidentDataSufficiency: validator pass / enrich first + - PostmortemAcceptance: publish as-is / edit draft + - WriteBackApproval: Gate 2 (jira write-back) + GUARDS: [ + automationLevel >= approved_automation for postmortem_draft_worker + and prevention_tasks_worker, + incident_summary_validator must pass before postmortem_draft_worker runs, + postmortem must be reviewed and published by the on-call owner before + prevention tasks are written to Jira, + WorkerRun[] execution history read-only; never modified by this flow + ] + NEXT: Journey 2 (gap analysis on prevention tasks coverage), + Journey 9 (if incident triggered a release rollback) +``` + +--- + +### Journey 11: Deploy to Environment + +```text +ALGORITHM DeployToEnvironment + ACTOR: DevOps / Release Manager + GOAL: Deploy a validated build_artifact to a target environment + with an optional Approval gate for production + INPUTS: [ + build_artifact — produced by CI pipeline [sync: github actions / jenkins], + environment (target: staging | prod), + release (state: approved) — for production deploys + ] + OUTPUTS: [ + deployment (state: done | failed), + deployment_status[] — one per deploy step, + WorkerRun — execution record + ] + COST TIER: low (deploy_worker script only) + AUTOMATION GATE: approved_automation + STEPS: + 1. Release Manager selects build_artifact + environment in Studio. + 2. DECISION: Production deployment? + - PROD: release must be in state: approved (Journey 9 completed); + Approval (kind: release_approval) must be present. + WriteBackPolicy.requiresApproval = true for prod environments + (Gate 2) — if not yet approved, Approval created. + - STAGING: proceed directly (WriteBackPolicy.requiresApproval = false) + 3. deploy_worker (script, on_demand): + - Input: build_artifact, environment + - Triggers CI/CD pipeline write-back [write-back: github actions / argocd] + - Output: deployment Object + deployment_status[] + 4. deployment state transitions: pending → running → done | failed + 5. DECISION: Deployment failed? + - YES: deployment state → failed; rollback decision required. + Studio creates Recommendation (suggestedWorker: rollback_worker) + - NO: deployment state → done; release state → deployed + DECISION_POINTS: + - EnvironmentTier: staging (no Approval) / production (Approval required) + - FailureResponse: rollback / investigate / retry + GUARDS: [ + automationLevel >= approved_automation for deploy_worker, + Production deploy requires release.state: approved before deploy_worker + can be invoked, + WriteBackPolicy.allowedActions must include deploy action for the + target environment, + deployment_status[] appended on each step; never overwritten + ] + NEXT: Operations monitoring (SLO/SLI tracking outside Studio), + Journey 10 if deployment triggers incident +``` + +--- + +### Journey 12: Security Exception Approval + +```text +ALGORITHM SecurityExceptionApproval + ACTOR: Security Lead + GOAL: Formally accept a known vulnerability that cannot be immediately + fixed, with a time-bounded exception and auto-review schedule + INPUTS: [ + vulnerability or security_finding [sync: snyk / dependabot / pentest], + risk assessment context + ] + OUTPUTS: [ + Approval (kind: security_exception, state: approved), + policy_exception Object — linked to vulnerability, + scheduled re-review Approval (via autoReviewAfter Worker) + ] + COST TIER: low (human-driven; security_impact_analysis for context only) + AUTOMATION GATE: none (Approval flow is human-driven) + STEPS: + 1. Security Lead sees vulnerability or security_finding in Studio. + DECISION: Run impact analysis first? + - YES: security_impact_analysis Analyzer (hybrid, on_demand) runs: + Input: pull_request[], vulnerability[], security_finding[] + Output: Recommendation with severity + affected component[] + - NO: proceed with known context + 2. Security Lead initiates security_exception Approval: + kind: security_exception + payload: { + expiresAt, + acceptedRisk, + mitigations: [], + secondaryApprover? (required if severity: critical), + autoReviewAfter: duration + } + 3. DECISION: Secondary approver required? + - YES (severity: critical): second Approval from CISO / VP Eng + - NO: single Security Lead approval sufficient + 4. Approval approved → policy_exception created: + linked to vulnerability; blocks security_scan_validator from + failing on this vulnerability until expiresAt + 5. autoReviewAfter schedule creates a new Approval automatically + when duration elapses — forces periodic re-evaluation. + DECISION_POINTS: + - ImpactAnalysisFirst: run security_impact_analysis / skip + - SecondaryApproverRequired: yes (critical severity) / no + - ExceptionDuration: set expiresAt (max enforced by Tenant policy) + GUARDS: [ + security_exception Approval must have expiresAt set; no open-ended exceptions, + Critical severity vulnerabilities require secondaryApprover, + autoReviewAfter must be set; exceptions without review schedule are rejected, + policy_exception scope limited to the specific vulnerability Object; + wildcards not permitted + ] + NEXT: Journey 9 (security_scan_validator will now accept this exception) +``` + +--- + +### Journey 13: SBOM Security Scan + +```text +ALGORITHM SBOMSecurityScan + ACTOR: Security Engineer / DevOps + GOAL: Scan a build artifact's SBOM for vulnerable dependencies and + generate remediation Recommendations + INPUTS: [ + build_artifact — produced by CI, + sbom — attached to build_artifact (SPDX / CycloneDX), + sbom_component[] — packages listed in SBOM, + dependency_vulnerability[] [sync: snyk / dependabot / github advisory] + ] + OUTPUTS: [ + Recommendation[] — upgrade library_version for each vulnerable component, + compliance_check_result[] — license policy check, + task[] (remediation) — if Recommendation accepted + ] + COST TIER: medium (security_impact_analysis hybrid; license check script) + AUTOMATION GATE: none + STEPS: + 1. build_artifact created → onEvent trigger fires security_impact_analysis + (Analyzer, hybrid, scheduled + onEvent). + 2. Analyzer reads sbom → sbom_component[] → library_version[]: + - Matches against dependency_vulnerability[] [sync: snyk] + - Identifies: critical/high CVEs, license policy violations + 3. For each vulnerable sbom_component: + - Recommendation created: severity per CVE cvssScore, + suggestedWorker: upgrade to fixedVersion library_version + 4. compliance_check runs (script): + - Checks sbom_license[] against Tenant license policy + - compliance_check_result: pass | fail + - On fail: Recommendation for license review or policy_exception + 5. Security Engineer reviews Recommendations: + DECISION: Per Recommendation action? + - ACCEPT → Journey 5 (accept Recommendation); upgrade triggers + create_pr_worker [write-back: github] + - EXCEPTION → Journey 12 (security_exception Approval) + - DISMISS → Recommendation dismissed with reason + DECISION_POINTS: + - PerRecommendationAction: accept (upgrade) / exception / dismiss + - LicensePolicyViolation: accept (policy_exception) / fix (update dep) + GUARDS: [ + Read-only scan — never modifies sbom or build_artifact, + confidence: partial if snyk/dependabot Connector unavailable + (scan continues with available CVE data), + Recommendations linked to specific sbom_component + library_version; + not to build_artifact as a whole + ] + NEXT: Journey 12 (security_exception) or Journey 5 (accept upgrade Recommendation) +``` + +--- + +### Journey 14: External System Inbound Sync + +```text +ALGORITHM ExternalSystemInboundSync + ACTOR: (platform — no direct user interaction) + GOAL: Keep Studio graph Objects current with external system state + by processing inbound Connector events + INPUTS: [ + Gears OAGW event — from external system (Jira, GitHub, PagerDuty, etc.), + Connector (registry entity) — defines FieldMappings + syncProtocol, + {vendor}_event_handler_worker (per-Kit) — custom mapping logic + ] + OUTPUTS: [ + Object (created | updated) — in Studio graph, + externalRef populated: { connectorId, externalId, externalUrl, lastSyncedAt }, + WorkerRun — execution record of sync Worker + ] + COST TIER: low (script Workers) + AUTOMATION GATE: none (platform Worker; not subject to automationLevel gate) + STEPS: + 1. External system emits event (push) or Studio polls (pull) via Gears OAGW. + Connector.syncProtocol determines push vs pull: + - push: webhook received via OAGW webhookPath; secret verified + - pull: scheduled interval poll; incremental if supported + 2. connector_inbound_sync_worker (script, realtime): + - Receives raw OAGW event payload + - Looks up Connector FieldMappings for this event type + - Invokes per-Kit {vendor}_event_handler_worker for custom logic + 3. {vendor}_event_handler_worker (per-Kit): + DECISION: Object exists in Studio graph? + - YES (externalRef.externalId matches): UPDATE Object + - Apply FieldMappings: direct | lookup | transform Worker + - Update Object.updatedAt, externalRef.lastSyncedAt + - Emit object_updated event → may trigger Analyzers + - NO: CREATE Object + - Assign GTS Type ID from Connector Kit type mapping + - Populate Object fields via FieldMappings + - Set externalRef + - Emit object_created event + 4. WorkerRun recorded (write-ahead: externalEvents[] populated before + any Object modification begins). + 5. DECISION: Conflict detected (Object modified in Studio since last sync)? + - Connector.WriteBackPolicy.conflictStrategy applies: + - overwrite: external wins + - skip: Studio version kept; event logged + - merge: field-level merge (if FieldMapping supports) + - escalate (default): Approval (kind: custom) created for human resolution + DECISION_POINTS: + - SyncDirection: push (event-driven) / pull (scheduled interval) + - ObjectExistence: create / update + - ConflictResolution: overwrite / skip / merge / escalate + GUARDS: [ + externalEvents[] write-ahead must complete before Object is modified, + FieldMappings must not map external fields to Object.id or Object.tenantId, + Connector scopeFilter (per Tenant) must be evaluated before Object creation + — events outside scope silently dropped, + rateLimit enforced by Gears OAGW upstream; sync Worker never called + above the Kit-declared rate + ] + NEXT: Object now available in Studio graph for Analyzer Workers, + Recommendations, and user-driven journeys +``` + +--- + +## Cross-Journey Patterns + +### Object lifecycle as the common thread + +All journeys operate on named Objects (bug, task, pull_request, incident, release, etc.) +that flow through Studio's graph. Workers move Objects from state to state. +Connectors bring external Objects in (inbound sync) and push Studio actions back +(outbound write-back). The graph is the source of truth; external systems are peers. + +### Validator-first quality gate + +Journeys 3, 4, 6, 9, and 10 all include mandatory Validator steps before an Object +can advance to its next state. Validators produce ValidationSessions and Evidence — +immutable proof that quality gates were cleared. Evidence is attached to the Object +(pull_request.conformsToDesign, release audit trail) and cannot be retracted without +explicit revocation. + +### automationLevel as the permission dial + +Journeys 1, 3, 4, 10, and 11 require `automationLevel >= approved_automation` for +action Workers (Workers that change state or write back to external systems). Read-only +Analyzers and Validators (Journeys 2, 6, 7, 9) run at any automationLevel. Journey 8 +is the explicit gate for raising the level. Lowering it requires no approval. + +### Connector-mediated Objects + +Most journeys include Objects synced from external systems (`[sync: jira]`, +`[sync: github]`, `[sync: pagerduty]`). These Objects carry `externalRef` with +`connectorId`, `externalId`, `externalUrl`, and `lastSyncedAt`. Workers operate on +Studio Objects regardless of origin — the Connector handles the sync boundary. + +### Write-back as a two-gate operation + +Any action that modifies an external system (creating a Jira issue, opening a GitHub PR, +triggering a deploy) passes through two independent gates: + +- **Gate 1 (Studio execution):** `automationLevel >= approved_automation AND + category in approvedWorkerCategories` — controls whether the action Worker runs at all. +- **Gate 2 (Connector write-back):** `WriteBackPolicy.requiresApproval` — controls + whether the output is sent to the external system; may require a separate Approval. + +Both gates must pass; Gate 1 does not imply Gate 2 clearance. + +### Evidence and 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`. The combination forms a complete audit trail +from intent to production. From 82617a7edb017972d4d6b98ce5b1707e708a908b Mon Sep 17 00:00:00 2001 From: ainetx Date: Sun, 5 Jul 2026 14:54:08 +0300 Subject: [PATCH 011/106] docs(v2): apply round 25 borrowings from LangGraph; update brainstorm state to round 25 Signed-off-by: ainetx Co-authored-by: Constructor Studio <291158726+constructor-studio[bot]@users.noreply.github.com> Studio-Generated-By: Constructor Studio Studio-Source-Repo: https://github.com/constructorfabric/studio Constructor-Fabric: https://github.com/constructorfabric Studio-Version: skill=1.5.9, cli=1.5.10.dev73 Studio-Workflows: cf-brainstorm --- .../state.md | 44 ++++++++++++++++--- v2/docs/domain-model.md | 25 ++++++++++- 2 files changed, 63 insertions(+), 6 deletions(-) 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 index d671a8de..31b6de9e 100644 --- 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 @@ -2,7 +2,7 @@ **Session ID:** studio-v2-domain-model-2026-07-03 **Date:** 2026-07-03 -**Rounds:** 20 +**Rounds:** 25 **Mode:** inline / normal **SIMPLE_MODE:** normal **BRAINSTORM_MAX_ROUNDS:** 10 (exceeded — continued by user choice) @@ -62,6 +62,11 @@ | 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 | --- @@ -194,6 +199,31 @@ - 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` + +### 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` @@ -209,17 +239,21 @@ ## Open Questions -1. **AI cost routing** — `ModelRouter` registry entity; `PromptExperiment` A/B testing; `WorkerRun.cost` field; `performance_benchmark` for AI Workers; custom enterprise models via Gears Models Registry +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 Artifact +## Output Artifacts -Domain model written to: `v2/docs/domain-model.md` -Last commit: `73e057b` +- Domain model: `v2/docs/domain-model.md` +- User journeys: `v2/docs/user-journeys.md` +- Decisions: ~110 across 25 rounds +- Last session commits: `a67bb590` (diagram reorganization), `b6523f6d` (rounds 21–22), `a3bd6632` (user-journeys.md) diff --git a/v2/docs/domain-model.md b/v2/docs/domain-model.md index d5528179..77d1b6a9 100644 --- a/v2/docs/domain-model.md +++ b/v2/docs/domain-model.md @@ -203,6 +203,8 @@ Worker { } onDemand: boolean // default: true } + fallbackWorkerId?: ref → Worker // must have compatible output Contract + fallbackCondition?: on_error | on_budget_exceeded | on_timeout } ``` @@ -265,6 +267,16 @@ WorkerImplementation { metadataTTL: duration retentionAction: archive | delete // default: archive } + parallelOutputMerge?: last | append | merge_by_key | custom + // default: last; applies when DAG branches run in parallel + 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) } ``` @@ -290,7 +302,7 @@ WorkerRun extends Object { parentRunId: ref → WorkerRun? inputData: any outputData: any - state: pending | running | done | failed + state: pending | running | paused | done | failed progress: { message: string? percent: 0..100? @@ -396,6 +408,13 @@ Flow { entryConstraints: Contract[] mandatorySteps: Worker[] allowedNextSteps: map + conditionalRoutes?: [ + { + fromWorker: ref → Worker + condition: string // JSONPath expression over outputData + nextWorker: ref → Worker + } + ] // evaluated after allowedNextSteps; wins on match scope: local | project | workspace | published } ``` @@ -1334,9 +1353,13 @@ Worker output Contract declares `produces: evidence` when it generates Evidence. ``` pending → running → done + → paused (pausePoint reached; awaiting human resume) → failed (error, can retry) → escalated (awaiting Approval from human) → aborted (limit reached or human rejected) + +paused → running (human resumes) +paused → aborted (timeoutAction: abort OR human cancels) ``` ### 18.6 Escalation Flow From d52c139c06f43b84c26200a3ffbc69c95c3b4973 Mon Sep 17 00:00:00 2001 From: ainetx Date: Sun, 5 Jul 2026 15:07:29 +0300 Subject: [PATCH 012/106] =?UTF-8?q?docs(v2):=20add=20interactive=20Worker?= =?UTF-8?q?=20model=20=E2=80=94=20WorkerInteraction,=20awaiting=5Finput,?= =?UTF-8?q?=20cancel()?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: ainetx Co-authored-by: Constructor Studio <291158726+constructor-studio[bot]@users.noreply.github.com> Studio-Generated-By: Constructor Studio Studio-Source-Repo: https://github.com/constructorfabric/studio Constructor-Fabric: https://github.com/constructorfabric Studio-Version: skill=1.5.9, cli=1.5.10.dev73 Studio-Workflows: cf-brainstorm --- .../state.md | 18 ++++- v2/docs/domain-model.md | 68 +++++++++++++++++-- 2 files changed, 76 insertions(+), 10 deletions(-) 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 index 31b6de9e..c6c43b75 100644 --- 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 @@ -2,7 +2,7 @@ **Session ID:** studio-v2-domain-model-2026-07-03 **Date:** 2026-07-03 -**Rounds:** 25 +**Rounds:** 26 **Mode:** inline / normal **SIMPLE_MODE:** normal **BRAINSTORM_MAX_ROUNDS:** 10 (exceeded — continued by user choice) @@ -67,6 +67,7 @@ | 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 | --- @@ -216,6 +217,17 @@ - **user-journeys.md** создан в v2/docs/ с 14 ALGORITHM-format сценариями - Сценарии аннотированы: `[sync: connector_name]`, `cost tier: low|medium|high`, `automation gate: none|approved_automation` +### 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` @@ -255,5 +267,5 @@ - Domain model: `v2/docs/domain-model.md` - User journeys: `v2/docs/user-journeys.md` -- Decisions: ~110 across 25 rounds -- Last session commits: `a67bb590` (diagram reorganization), `b6523f6d` (rounds 21–22), `a3bd6632` (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/v2/docs/domain-model.md b/v2/docs/domain-model.md index 77d1b6a9..5e6bc317 100644 --- a/v2/docs/domain-model.md +++ b/v2/docs/domain-model.md @@ -139,6 +139,7 @@ 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~ ``` ### 2.4 Vendor (Kit) Extensions @@ -205,6 +206,13 @@ Worker { } fallbackWorkerId?: ref → Worker // must have compatible output Contract 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 + } + // kind: free_form_intent available to any Worker at runtime } ``` @@ -302,7 +310,7 @@ WorkerRun extends Object { parentRunId: ref → WorkerRun? inputData: any outputData: any - state: pending | running | paused | done | failed + state: pending | running | awaiting_input | paused | done | failed progress: { message: string? percent: 0..100? @@ -318,6 +326,9 @@ WorkerRun extends Object { { source: string, type: string, externalId: string, url: string } ] checkpointExpiresAt: datetime? + interactions: WorkerInteraction[] // history of all interactions (immutable once answered) + cancelledBy?: ref → User + cancelCascade?: boolean // were child WorkerRuns also cancelled cost?: { promptTokens: int completionTokens: int @@ -1163,6 +1174,9 @@ 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~ @@ -1352,14 +1366,24 @@ Worker output Contract declares `produces: evidence` when it generates Evidence. ### 18.5 WorkerRun State Machine (updated) ``` -pending → running → done - → paused (pausePoint reached; awaiting human resume) - → failed (error, can retry) - → escalated (awaiting Approval from human) - → aborted (limit reached or human rejected) +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 human cancels) +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 @@ -2570,6 +2594,36 @@ cf.studio.core.evidence.v1~ // structured proof of action/validatio --- +### Domain 20 — 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. From 676e69c5879d9ed9cf7fec7e3c2a7925fd35d35c Mon Sep 17 00:00:00 2001 From: ainetx Date: Sun, 5 Jul 2026 15:13:53 +0300 Subject: [PATCH 013/106] =?UTF-8?q?docs(v2):=20add=20RAG=20model=20?= =?UTF-8?q?=E2=80=94=20Retriever=20Workers,=20WorkerImplementation.retriev?= =?UTF-8?q?al,=20chunkRef=20audit?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: ainetx Co-authored-by: Constructor Studio <291158726+constructor-studio[bot]@users.noreply.github.com> Studio-Generated-By: Constructor Studio Studio-Source-Repo: https://github.com/constructorfabric/studio Constructor-Fabric: https://github.com/constructorfabric Studio-Version: skill=1.5.9, cli=1.5.10.dev73 Studio-Workflows: cf-brainstorm --- .../state.md | 12 +++++++- v2/docs/domain-model.md | 30 ++++++++++++++++++- 2 files changed, 40 insertions(+), 2 deletions(-) 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 index c6c43b75..2053e89a 100644 --- 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 @@ -2,7 +2,7 @@ **Session ID:** studio-v2-domain-model-2026-07-03 **Date:** 2026-07-03 -**Rounds:** 26 +**Rounds:** 27 **Mode:** inline / normal **SIMPLE_MODE:** normal **BRAINSTORM_MAX_ROUNDS:** 10 (exceeded — continued by user choice) @@ -68,6 +68,7 @@ | 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 | --- @@ -217,6 +218,15 @@ - **user-journeys.md** создан в v2/docs/ с 14 ALGORITHM-format сценариями - Сценарии аннотированы: `[sync: connector_name]`, `cost tier: low|medium|high`, `automation gate: none|approved_automation` +### 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) diff --git a/v2/docs/domain-model.md b/v2/docs/domain-model.md index 5e6bc317..9d2d9525 100644 --- a/v2/docs/domain-model.md +++ b/v2/docs/domain-model.md @@ -277,6 +277,13 @@ WorkerImplementation { } parallelOutputMerge?: last | append | merge_by_key | custom // default: last; applies when DAG branches run in parallel + retrieval?: { // only for Workers with kind: utility acting as Retrievers + 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 @@ -323,7 +330,14 @@ WorkerRun extends Object { source: kit | tenant | call } externalEvents: [ - { source: string, type: string, externalId: string, url: string } + { + 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) @@ -1760,6 +1774,20 @@ kind: utility 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 (`kind: utility`) 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. + --- ## Appendix A — Studio v2 Object Type Catalog From 4399672d6d8ec22b5eec2b62da65823763a2391e Mon Sep 17 00:00:00 2001 From: ainetx Date: Sun, 5 Jul 2026 15:20:53 +0300 Subject: [PATCH 014/106] docs(v2): clarify Worker as registry definition vs WorkerRun as execution instance Signed-off-by: ainetx Co-authored-by: Constructor Studio <291158726+constructor-studio[bot]@users.noreply.github.com> Studio-Generated-By: Constructor Studio Studio-Source-Repo: https://github.com/constructorfabric/studio Constructor-Fabric: https://github.com/constructorfabric Studio-Version: skill=1.5.9, cli=1.5.10.dev73 Studio-Workflows: cf-brainstorm --- .../studio-v2-domain-model-2026-07-03/state.md | 3 ++- v2/docs/domain-model.md | 18 ++++++++++++++++-- 2 files changed, 18 insertions(+), 3 deletions(-) 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 index 2053e89a..2f539a46 100644 --- 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 @@ -2,7 +2,7 @@ **Session ID:** studio-v2-domain-model-2026-07-03 **Date:** 2026-07-03 -**Rounds:** 27 +**Rounds:** 28 **Mode:** inline / normal **SIMPLE_MODE:** normal **BRAINSTORM_MAX_ROUNDS:** 10 (exceeded — continued by user choice) @@ -69,6 +69,7 @@ | 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 | --- diff --git a/v2/docs/domain-model.md b/v2/docs/domain-model.md index 9d2d9525..31d7e05b 100644 --- a/v2/docs/domain-model.md +++ b/v2/docs/domain-model.md @@ -72,7 +72,7 @@ Outside the graph. Describe rules and configurations, not data. | Entity | Purpose | |---|---| -| `Worker` | Executor — consumes and produces Objects | +| `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` | Configuration of constraints and mandatory steps | @@ -185,7 +185,21 @@ are standard JSON Schema fields. ## 4. Worker -Executor — consumes Objects, produces Objects. Registry entity. +**Worker = registry definition.** WorkerRun (§5) = execution instance. + +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. + +User-facing labels by `kind`: + +| kind | UI / docs label | Semantic role | +|---|---|---| +| `action` | Action | Drives state transitions; may write back to external systems | +| `analyzer` | Analyzer | Detects gaps; creates Recommendations; read-only | +| `validator` | Validator | Gates transitions; produces ValidationResult + Evidence | +| `utility` | Worker (internal) | Infrastructure: Retriever, sync, export | ``` Worker { From efa2f4c1ad9b40eabe50bc72e38b5c39ba370b4d Mon Sep 17 00:00:00 2001 From: ainetx Date: Sun, 5 Jul 2026 15:26:00 +0300 Subject: [PATCH 015/106] =?UTF-8?q?docs(v2):=20add=20Overview=20section=20?= =?UTF-8?q?with=206=20high-level=20diagrams=20(DO1=E2=80=93DO6)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: ainetx Co-authored-by: Constructor Studio <291158726+constructor-studio[bot]@users.noreply.github.com> Studio-Generated-By: Constructor Studio Studio-Source-Repo: https://github.com/constructorfabric/studio Constructor-Fabric: https://github.com/constructorfabric Studio-Version: skill=1.5.9, cli=1.5.10.dev73 Studio-Workflows: cf-brainstorm --- v2/docs/domain-model.md | 203 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 203 insertions(+) diff --git a/v2/docs/domain-model.md b/v2/docs/domain-model.md index 31d7e05b..b9f4a479 100644 --- a/v2/docs/domain-model.md +++ b/v2/docs/domain-model.md @@ -4,6 +4,209 @@ --- +## 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\nRBAC/ABAC · OAGW · Models Gateway · Settings"] + 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"] + O["Object (base)\nTenant · User · Workspace · Role\nWorkerRun · FlowRun · Recommendation · Approval\nValidationSession · Evidence · 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 +``` + +--- + +### DO2 — Registry Entity Relationships + +```mermaid +classDiagram + class Kit { + scope + } + class Worker { + kind: action|analyzer|validator|utility + } + 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 + +```mermaid +classDiagram + class Object { + id · typeId · tenantId + state · createdAt · updatedAt + ownerId · validationStatus + stalenessScore · externalRef + } + class Tenant + class User + class Workspace + class Role + class WorkerRun + class FlowRun + class Recommendation + class Approval + class ValidationSession + class WorkerInteraction + class Evidence + + Object <|-- Tenant + Object <|-- 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 { + automationLevel + approvedWorkerCategories + deploymentMode + } + class User + 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) From a6d6f0d429d2ba35bb1b6457f85976710b7ddeda Mon Sep 17 00:00:00 2001 From: ainetx Date: Sun, 5 Jul 2026 15:32:39 +0300 Subject: [PATCH 016/106] docs(v2): Flow = Worker (kind: orchestrator) via GTS chaining; FlowRun extends WorkerRun Signed-off-by: ainetx Co-authored-by: Constructor Studio <291158726+constructor-studio[bot]@users.noreply.github.com> Studio-Generated-By: Constructor Studio Studio-Source-Repo: https://github.com/constructorfabric/studio Constructor-Fabric: https://github.com/constructorfabric Studio-Version: skill=1.5.9, cli=1.5.10.dev73 Studio-Workflows: cf-brainstorm --- .../state.md | 13 +++- v2/docs/domain-model.md | 60 ++++++++++++------- 2 files changed, 50 insertions(+), 23 deletions(-) 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 index 2f539a46..5ff666b2 100644 --- 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 @@ -2,7 +2,7 @@ **Session ID:** studio-v2-domain-model-2026-07-03 **Date:** 2026-07-03 -**Rounds:** 28 +**Rounds:** 30 **Mode:** inline / normal **SIMPLE_MODE:** normal **BRAINSTORM_MAX_ROUNDS:** 10 (exceeded — continued by user choice) @@ -70,6 +70,8 @@ | 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 | --- @@ -219,6 +221,15 @@ - **user-journeys.md** создан в v2/docs/ с 14 ALGORITHM-format сценариями - Сценарии аннотированы: `[sync: connector_name]`, `cost tier: low|medium|high`, `automation gate: none|approved_automation` +### 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 diff --git a/v2/docs/domain-model.md b/v2/docs/domain-model.md index b9f4a479..3358ba1f 100644 --- a/v2/docs/domain-model.md +++ b/v2/docs/domain-model.md @@ -278,9 +278,9 @@ Outside the graph. Describe rules and configurations, not data. | `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` | Configuration of constraints and mandatory steps | +| `Flow` | Worker (kind: orchestrator) — sequences mandatory steps; packaged in Kit as a Worker | | `Connector` | Integration with external system via Gears OAGW (field mapping, write-back, sync) | -| `Kit` | Extension packaging unit (types, Workers, Validators, Flows, Connectors) | +| `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) | @@ -300,7 +300,8 @@ Studio-owned base types: gts.cf.studio.core.object.v1~ ← base Object (all Studio domain objects) gts.cf.studio.core.worker.v1~ ← base Worker gts.cf.studio.core.validator.v1~ ← extends Worker; adds retry/escalation semantics -gts.cf.studio.core.flow.v1~ ← base Flow +gts.cf.studio.core.worker.v1~cf.studio.core.flow.v1~ + ← Flow = Worker (kind: orchestrator) via GTS chaining 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 @@ -402,12 +403,13 @@ User-facing labels by `kind`: | `action` | Action | Drives state transitions; may write back to external systems | | `analyzer` | Analyzer | Detects gaps; creates Recommendations; read-only | | `validator` | Validator | Gates transitions; produces ValidationResult + Evidence | +| `orchestrator` | Flow | Sequences mandatory steps; produces FlowRunResult; extends Worker via GTS | | `utility` | Worker (internal) | Infrastructure: Retriever, sync, export | ``` Worker { id: GTS Type Identifier (gts.cf.studio.core.worker.v1~...) - kind: action | analyzer | validator | utility + kind: action | analyzer | validator | utility | orchestrator input: Contract (GTS Type Schema) output: Contract (GTS Type Schema) dependencies: Worker[] (static list — security boundary) @@ -642,34 +644,48 @@ classDiagram ## 6. Flow -Constraint configuration layered on top of Workers + Contracts. Registry entity. - -``` -Flow { - id: GTS Type Identifier (gts.cf.studio.core.flow.v1~...) - entryConstraints: Contract[] - mandatorySteps: Worker[] - allowedNextSteps: map - conditionalRoutes?: [ - { - fromWorker: ref → Worker - condition: string // JSONPath expression over outputData - nextWorker: ref → Worker +**Flow = Worker (kind: orchestrator).** A Flow is not a separate registry entity — it +extends Worker through GTS chaining. Flow Workers have `runtime: orchestrator` +(declarative constraint config, no LLM/script code) and sequence mandatory steps. + +``` +// GTS type: gts.cf.studio.core.worker.v1~cf.studio.core.flow.v1~ + +Flow extends Worker { + kind: orchestrator // always + input: Contract[] // entryConstraints + output: Contract // { completedSteps, skipped } + implementationId: WorkerImplementation { + runtime: orchestrator + config: { + mandatorySteps: Worker[] + allowedNextSteps: map + conditionalRoutes?: [ + { + fromWorker: ref → Worker + condition: string // JSONPath expression over outputData + nextWorker: ref → Worker + } + ] // evaluated after allowedNextSteps; wins on match } - ] // 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 Object { +FlowRun extends WorkerRun { + // inherits all WorkerRun fields typeId: gts.cf.studio.core.object.v1~cf.studio.core.flow_run.v1~ - flowId: ref → Flow + // additional orchestrator fields: completedSteps: Worker[] skippedSteps: Worker[] - state: running | done | failed | aborted + // note: outputData = { completedSteps, skipped } (FlowRunResult, not a domain Object) } ``` @@ -789,7 +805,7 @@ classDiagram ### 10.1 Kit — the only extension unit -A Kit packages: new Object types, Workers, WorkerImplementations, Flows, +A Kit packages: new Object types, Workers of all kinds (including orchestrators / Flows), obj_ext definitions. ``` From 333ceff4240d68d753978485e803cd04f2a2d4f3 Mon Sep 17 00:00:00 2001 From: ainetx Date: Sun, 5 Jul 2026 15:35:58 +0300 Subject: [PATCH 017/106] docs(v2): add Worker extension design rule; confirm Connector stays separate Signed-off-by: ainetx Co-authored-by: Constructor Studio <291158726+constructor-studio[bot]@users.noreply.github.com> Studio-Generated-By: Constructor Studio Studio-Source-Repo: https://github.com/constructorfabric/studio Constructor-Fabric: https://github.com/constructorfabric Studio-Version: skill=1.5.9, cli=1.5.10.dev73 Studio-Workflows: cf-brainstorm --- .../studio-v2-domain-model-2026-07-03/state.md | 3 ++- v2/docs/domain-model.md | 10 ++++++++++ 2 files changed, 12 insertions(+), 1 deletion(-) 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 index 5ff666b2..7bd5f42f 100644 --- 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 @@ -2,7 +2,7 @@ **Session ID:** studio-v2-domain-model-2026-07-03 **Date:** 2026-07-03 -**Rounds:** 30 +**Rounds:** 31 **Mode:** inline / normal **SIMPLE_MODE:** normal **BRAINSTORM_MAX_ROUNDS:** 10 (exceeded — continued by user choice) @@ -72,6 +72,7 @@ | 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 | --- diff --git a/v2/docs/domain-model.md b/v2/docs/domain-model.md index 3358ba1f..217d7625 100644 --- a/v2/docs/domain-model.md +++ b/v2/docs/domain-model.md @@ -391,6 +391,16 @@ are standard JSON Schema fields. **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 From 456585c65ac68561990495bfcc9823af0949b8f1 Mon Sep 17 00:00:00 2001 From: ainetx Date: Sun, 5 Jul 2026 15:37:50 +0300 Subject: [PATCH 018/106] =?UTF-8?q?fix(v2):=20correct=20Validator=20GTS=20?= =?UTF-8?q?type=20to=20use=20Worker=20chaining=20in=20=C2=A72.1?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: ainetx Co-authored-by: Constructor Studio <291158726+constructor-studio[bot]@users.noreply.github.com> Studio-Generated-By: Constructor Studio Studio-Source-Repo: https://github.com/constructorfabric/studio Constructor-Fabric: https://github.com/constructorfabric Studio-Version: skill=1.5.9, cli=1.5.10.dev73 Studio-Workflows: cf-brainstorm --- v2/docs/domain-model.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/v2/docs/domain-model.md b/v2/docs/domain-model.md index 217d7625..45fdc78c 100644 --- a/v2/docs/domain-model.md +++ b/v2/docs/domain-model.md @@ -298,8 +298,9 @@ Studio-owned base types: ``` gts.cf.studio.core.object.v1~ ← base Object (all Studio domain objects) -gts.cf.studio.core.worker.v1~ ← base Worker -gts.cf.studio.core.validator.v1~ ← extends Worker; adds retry/escalation semantics +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 (kind: orchestrator) via GTS chaining gts.cf.studio.core.connector.v1~ ← registry entity; uses Gears OAGW as infrastructure From 51b6f61a9d9912c90edeebdc5bd7c16c9f10eb62 Mon Sep 17 00:00:00 2001 From: ainetx Date: Sun, 5 Jul 2026 15:50:58 +0300 Subject: [PATCH 019/106] docs(v2): remove Worker.kind; add requiresAutomationGate; Action becomes UI concept Signed-off-by: ainetx Co-authored-by: Constructor Studio <291158726+constructor-studio[bot]@users.noreply.github.com> Studio-Generated-By: Constructor Studio Studio-Source-Repo: https://github.com/constructorfabric/studio Constructor-Fabric: https://github.com/constructorfabric Studio-Version: skill=1.5.9, cli=1.5.10.dev73 Studio-Workflows: cf-brainstorm --- .../state.md | 13 +++- v2/docs/domain-model.md | 74 ++++++++++++------- 2 files changed, 59 insertions(+), 28 deletions(-) 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 index 7bd5f42f..a260070b 100644 --- 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 @@ -2,7 +2,7 @@ **Session ID:** studio-v2-domain-model-2026-07-03 **Date:** 2026-07-03 -**Rounds:** 31 +**Rounds:** 32 **Mode:** inline / normal **SIMPLE_MODE:** normal **BRAINSTORM_MAX_ROUNDS:** 10 (exceeded — continued by user choice) @@ -73,6 +73,7 @@ | 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 | --- @@ -222,6 +223,16 @@ - **user-journeys.md** создан в v2/docs/ с 14 ALGORITHM-format сценариями - Сценарии аннотированы: `[sync: connector_name]`, `cost tier: low|medium|high`, `automation gate: none|approved_automation` +### 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~` diff --git a/v2/docs/domain-model.md b/v2/docs/domain-model.md index 45fdc78c..140f6802 100644 --- a/v2/docs/domain-model.md +++ b/v2/docs/domain-model.md @@ -47,7 +47,7 @@ classDiagram scope } class Worker { - kind: action|analyzer|validator|utility + requiresAutomationGate: bool } class Flow class Connector @@ -278,7 +278,7 @@ Outside the graph. Describe rules and configurations, not data. | `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 (kind: orchestrator) — sequences mandatory steps; packaged in Kit as a Worker | +| `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 | @@ -302,7 +302,7 @@ 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 (kind: orchestrator) via GTS chaining + ← 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 @@ -407,25 +407,28 @@ what it consumes and produces (Contract), how it runs (WorkerImplementation), an it is allowed to call (dependencies). Workers do not execute themselves — execution creates a WorkerRun. -User-facing labels by `kind`: +**Categorization:** Workers have no `kind` field. Structural subtypes (Validator, Flow) +are expressed through GTS chaining. Behavioral policy is carried by two fields: -| kind | UI / docs label | Semantic role | -|---|---|---| -| `action` | Action | Drives state transitions; may write back to external systems | -| `analyzer` | Analyzer | Detects gaps; creates Recommendations; read-only | -| `validator` | Validator | Gates transitions; produces ValidationResult + Evidence | -| `orchestrator` | Flow | Sequences mandatory steps; produces FlowRunResult; extends Worker via GTS | -| `utility` | Worker (internal) | Infrastructure: Retriever, sync, export | +- `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~...) - kind: action | analyzer | validator | utility | orchestrator input: Contract (GTS Type Schema) output: Contract (GTS Type Schema) dependencies: Worker[] (static list — security boundary) scope: local | project | workspace | published implementationId: ref → WorkerImplementation + requiresAutomationGate: boolean // default: false + // true = Gate 1 applies (automationLevel check) trigger?: { schedule?: cron string onEvent?: { @@ -442,7 +445,17 @@ Worker { maxPendingInteractions: int // default: 1 cancellable: boolean // default: true } - // kind: free_form_intent available to any Worker at runtime + 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 + } + } } ``` @@ -507,7 +520,7 @@ WorkerImplementation { } parallelOutputMerge?: last | append | merge_by_key | custom // default: last; applies when DAG branches run in parallel - retrieval?: { // only for Workers with kind: utility acting as Retrievers + 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 @@ -655,15 +668,16 @@ classDiagram ## 6. Flow -**Flow = Worker (kind: orchestrator).** A Flow is not a separate registry entity — it -extends Worker through GTS chaining. Flow Workers have `runtime: orchestrator` +**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 { - kind: orchestrator // always + // no kind field — structural identity expressed through GTS type input: Contract[] // entryConstraints output: Contract // { completedSteps, skipped } implementationId: WorkerImplementation { @@ -1954,11 +1968,16 @@ pr_design_validator extends Validator { --- -## 24. SDLC Action Workers +## 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. -Action Workers (`kind: action`) are the "executable edges" of the Studio graph — they drive state transitions between Objects. All require `automationLevel >= approved_automation AND category in approvedWorkerCategories` (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 Action Worker Catalog +### 24.1 Worker Catalog | Worker | Runtime | Profile | Input → Output | |---|---|---|---| @@ -1978,12 +1997,12 @@ Action Workers (`kind: action`) are the "executable edges" of the Studio graph ### 24.2 Approval Gates -Action Workers are governed by two independent gates: +Workers with `requiresAutomationGate: true` are governed by two independent gates: **Gate 1 — Studio execution gate** (checked at WorkerRun creation): ``` -automationLevel >= approved_automation -AND Worker.kind == action +Worker.requiresAutomationGate == true +AND automationLevel >= approved_automation AND Worker.metadata.category in Tenant.approvedWorkerCategories ``` @@ -2005,9 +2024,10 @@ Both gates are independent and both may apply to the same WorkerRun. 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 -kind: utility +pre-installed: true +requires_kit_approval: false +requiresAutomationGate: false +metadata.category: platform ``` | Worker | Runtime | Profile | Purpose | @@ -2020,7 +2040,7 @@ Per-Kit Connectors may register additional `event_handler_worker` Workers in the ### 25.2 Retriever Workers -Retriever Workers are pre-installed platform Workers (`kind: utility`) 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. +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. From 34d760593caad93fdeff2a341da71c822f77d84c Mon Sep 17 00:00:00 2001 From: ainetx Date: Sun, 5 Jul 2026 16:05:14 +0300 Subject: [PATCH 020/106] =?UTF-8?q?docs(v2):=20add=20input=20resolution=20?= =?UTF-8?q?model=20=E2=80=94=20Worker.inputBindings,=20Contract=20security?= =?UTF-8?q?=20annotations,=20Flow=20step=20binding?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: ainetx Co-authored-by: Constructor Studio <291158726+constructor-studio[bot]@users.noreply.github.com> Studio-Generated-By: Constructor Studio Studio-Source-Repo: https://github.com/constructorfabric/studio Constructor-Fabric: https://github.com/constructorfabric Studio-Version: skill=1.5.9, cli=1.5.10.dev73 Studio-Workflows: cf-brainstorm --- .../state.md | 11 ++++++- v2/docs/domain-model.md | 33 +++++++++++++++++-- 2 files changed, 41 insertions(+), 3 deletions(-) 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 index a260070b..2d0fb2dd 100644 --- 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 @@ -2,7 +2,7 @@ **Session ID:** studio-v2-domain-model-2026-07-03 **Date:** 2026-07-03 -**Rounds:** 32 +**Rounds:** 33 **Mode:** inline / normal **SIMPLE_MODE:** normal **BRAINSTORM_MAX_ROUNDS:** 10 (exceeded — continued by user choice) @@ -74,6 +74,7 @@ | 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 | --- @@ -223,6 +224,14 @@ - **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 diff --git a/v2/docs/domain-model.md b/v2/docs/domain-model.md index 140f6802..bdf180ab 100644 --- a/v2/docs/domain-model.md +++ b/v2/docs/domain-model.md @@ -378,7 +378,8 @@ are standard JSON Schema fields. }, "workspace": { "$ref": "gts://cf.studio.core.object.v1~cf.studio.core.workspace.v1~", - "x-gts-required": true + "x-gts-required": true, + "x-gts-source": "platform" }, "style": { "type": "string", "enum": ["detailed", "sketch"] }, "language": { "type": "string" } @@ -386,6 +387,15 @@ are standard JSON Schema fields. } ``` +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 @@ -437,6 +447,16 @@ Worker { } onDemand: boolean // default: true } + 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 fallbackWorkerId?: ref → Worker // must have compatible output Contract fallbackCondition?: on_error | on_budget_exceeded | on_timeout interactionModel?: { @@ -683,7 +703,16 @@ Flow extends Worker { implementationId: WorkerImplementation { runtime: orchestrator config: { - mandatorySteps: Worker[] + steps: [ + { + workerId: ref → Worker + inputBinding?: { // overrides Worker.inputBindings for this step + // field → { source, query?, fromStep?, default? } + // e.g. "prd": { source: "chain", fromStep: "step-0" } + } + } + ] + mandatorySteps: Worker[] // subset of steps that must execute allowedNextSteps: map conditionalRoutes?: [ { From 0218f599ff249c5f8c163fbc792c960c219335c0 Mon Sep 17 00:00:00 2001 From: ainetx Date: Sun, 5 Jul 2026 16:15:03 +0300 Subject: [PATCH 021/106] =?UTF-8?q?fix(v2):=20replace=20x-gts-required=20w?= =?UTF-8?q?ith=20standard=20JSON=20Schema=20required=20array=20in=20Contra?= =?UTF-8?q?ct=20=C2=A73?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: ainetx Co-authored-by: Constructor Studio <291158726+constructor-studio[bot]@users.noreply.github.com> Studio-Generated-By: Constructor Studio Studio-Source-Repo: https://github.com/constructorfabric/studio Constructor-Fabric: https://github.com/constructorfabric Studio-Version: skill=1.5.9, cli=1.5.10.dev73 Studio-Workflows: cf-brainstorm --- v2/docs/domain-model.md | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/v2/docs/domain-model.md b/v2/docs/domain-model.md index bdf180ab..1536d2c6 100644 --- a/v2/docs/domain-model.md +++ b/v2/docs/domain-model.md @@ -361,24 +361,28 @@ gts.cf.studio.core.obj_ext.v1~jira.studio.core.jira_task_ext.v1~ ## 3. Contract -Contract = **GTS Type Schema** (JSONSchema + `x-gts-*`). +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 -are standard JSON Schema fields. +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 (`x-gts-traits`). ```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~", - "x-gts-required": true + "$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-required": true, "x-gts-source": "platform" }, "style": { "type": "string", "enum": ["detailed", "sketch"] }, From ed433f64fcbaf38f6643f3ccfd1fd65217104d92 Mon Sep 17 00:00:00 2001 From: ainetx Date: Sun, 5 Jul 2026 16:16:01 +0300 Subject: [PATCH 022/106] =?UTF-8?q?docs(v2):=20rewrite=20user-journeys.md?= =?UTF-8?q?=20=E2=80=94=20transform=20all=2022=20v1=20journeys=20to=20Stud?= =?UTF-8?q?io=20v2=20Workers/Flows/Connectors?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: ainetx Co-authored-by: Constructor Studio <291158726+constructor-studio[bot]@users.noreply.github.com> Studio-Generated-By: Constructor Studio Studio-Source-Repo: https://github.com/constructorfabric/studio Constructor-Fabric: https://github.com/constructorfabric Studio-Version: skill=1.5.9, cli=1.5.10.dev73 Studio-Workflows: cf-brainstorm --- v2/docs/user-journeys.md | 2205 +++++++++++++++++++++++++++----------- 1 file changed, 1555 insertions(+), 650 deletions(-) diff --git a/v2/docs/user-journeys.md b/v2/docs/user-journeys.md index 5dcb1b62..90dab8e4 100644 --- a/v2/docs/user-journeys.md +++ b/v2/docs/user-journeys.md @@ -2,9 +2,9 @@ ## Introduction -This document describes the fourteen primary user journeys in Studio v2. Each journey -traces the full path a user takes from intent to outcome, showing which Objects, Workers, -Flows, and Connectors are involved. +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** @@ -16,897 +16,1802 @@ Each block follows a fixed schema: 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 -- `STEPS` — the ordered sequence of actions, Workers, and Flows invoked - `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`. +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 | Cost Tier | Automation Gate | -|---|---------|-------|------|-----------------|-----------|-----------------| -| 1 | Product intent → decomposed tasks | Product Manager | prd → design → task[] in Jira | `create_design_worker` → `decompose_feature_worker` | high | approved_automation | -| 2 | Requirement gap detection | Product Manager | Detect uncovered requirements | `gap_analysis`, `traceability_analysis` | medium | none | -| 3 | Bug report → Fix PR | Developer | bug → reproduction → failing test → PR | `bug_to_fix_pr_flow` | high | approved_automation | -| 4 | Feature task → Pull Request | Developer | task → code → PR with design conformance | `implement_code_worker`, `create_pr_worker`, `pr_design_validator` | high | approved_automation | -| 5 | Accept a Recommendation | Developer | Act on an Analyzer-created Recommendation | `validationWorker` + `suggestedWorker` | low–high | approved_automation | -| 6 | PR conformance to design | Tech Lead | Validate PR against design (automatic) | `pr_design_validator` | medium | none | -| 7 | Architecture drift detection | Architect | Detect component drift from design | `architecture_drift_detection` | medium | none | -| 8 | Raise automationLevel | Architect | Unlock action Workers for a Tenant | StatePolicy transition + Approval | low | none | -| 9 | Release readiness review | Release Manager | Gate release candidate on validators | `release_readiness_review` | medium | none | -| 10 | Incident → Postmortem | SRE / On-call | incident → postmortem + prevention tasks | `incident_to_postmortem_flow` | medium–high | approved_automation | -| 11 | Deploy to environment | DevOps | build_artifact → deployment | `deploy_worker` | low | approved_automation | -| 12 | Security exception approval | Security Lead | Approve a vulnerability exception | `security_impact_analysis` + Approval | low | none | -| 13 | SBOM security scan | Security Engineer | Scan build_artifact for vulnerable deps | `security_impact_analysis` | medium | none | -| 14 | External system inbound sync | (platform) | Connector event → Object in graph | `connector_inbound_sync_worker` | low | none | +| # | 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: Product Intent → Decomposed Tasks +### Journey 1: Plan and Implement a Feature ```text -ALGORITHM ProductIntentToDecomposedTasks - ACTOR: Product Manager - GOAL: Turn a product requirement document into a validated design and - an ordered task list written back to Jira +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: [ - prd (state: draft) — authored externally or in Studio, - workspace configured with Jira Connector [sync: jira] + 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: [ - design (state: approved) — linked to prd, - decomposition — ordered feature list, - task[] [write-back: jira] — Jira issues with traceability to prd + design + 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 (create_design_worker + decompose_feature_worker, both llm) + COST TIER: high (decompose_feature_worker llm + implement_code_worker llm + + create_pr_worker hybrid) AUTOMATION GATE: approved_automation STEPS: - 1. PM selects prd Object in Studio UI or CLI. - 2. Studio invokes create_design_worker (llm, on_demand): - - Input: prd, workspace, optional style (detailed | sketch) - - Output: design (state: draft) - 3. gap_analysis_validator (hybrid, realtime) runs automatically: - - Checks prd FR coverage in candidate design - - ValidationSession created; on fail → design sent back with gaps - 4. DECISION: Design acceptable? - - YES: design state → approved (StatePolicy transition) - - NO: PM edits design manually or re-runs create_design_worker - with amended prd - 5. Studio invokes decompose_feature_worker (llm, on_demand): - - Input: design, prd, optional team capacity hint - - Output: decomposition + task[] (state: planned) - 6. DECISION: Review tasks before write-back? - - YES: PM reviews task[] in Studio; edits names, priorities, owners - - NO: proceed directly to step 7 - 7. connector_outbound_sync_worker writes task[] to Jira via - WriteBackPolicy (requiresApproval based on Tenant automationLevel). - DECISION: Approval required? - - Gate 2 (WriteBackPolicy.requiresApproval = true): - Approval Object created; PM or Tech Lead approves; write-back executes. - - Gate 2 (requiresApproval = false): write-back executes immediately. + 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: - - DesignAcceptance: approve design / re-run with amendments - - TaskReviewBeforeWriteBack: review first / write-back immediately - - WriteBackApproval: Approval required (Gate 2) / immediate + - 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 before create_design_worker - or decompose_feature_worker can be invoked, - gap_analysis_validator must pass (or PM explicitly overrides) before - design state can advance to approved, - task[] write-back to Jira must satisfy WriteBackPolicy.allowedActions, - prd must have at least one requirement before create_design_worker runs - ] - NEXT: Journey 3 (bug fix) or Journey 4 (feature implementation) per task + 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: Requirement Gap Detection +### Journey 2: Onboard a Project to Studio v2 ```text -ALGORITHM RequirementGapDetection - ACTOR: Product Manager - GOAL: Identify requirements that lack design coverage, implementation - tasks, or test cases, and receive actionable Recommendations +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: [ - requirement[] — in Studio graph (may be [sync: jira] or native), - task[] [sync: jira], - test_case[] [sync: github / test management tool], - pull_request[] [sync: github] + 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: [ - Recommendation[] (state: pending) — one per detected gap, - traceability report — coverage links visualized + .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: medium (gap_analysis hybrid + traceability_analysis hybrid) - AUTOMATION GATE: none + COST TIER: low (script Workers + WorkerInteraction menu; no LLM Workers required) + AUTOMATION GATE: approved_automation (Kit install + Connector setup write to graph) STEPS: - 1. gap_analysis Analyzer Worker runs on schedule or on_demand: - - Scans requirement[], task[], test_case[], pull_request[] - - Creates Recommendation for each uncovered requirement - - Example: "requirement R-17 has no task and no test_case" - 2. traceability_analysis Analyzer Worker runs in parallel: - - Maps requirement → design → task → pull_request → test_case chains - - Creates Recommendation for broken links in the chain - 3. PM views Recommendation[] in Studio UI: - - severity: info | warning | critical - - confidence: full | partial (when external system unavailable) - 4. DECISION: Act on Recommendations? - - YES: PM accepts Recommendations → Journey 1 (create tasks) or - assigns tasks to developers manually - - DISMISS: PM dismisses with reason; Recommendation state → dismissed - - SNOOZE: PM sets validationWorker re-check schedule + 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: - - AnalysisTrigger: scheduled (default: nightly) / on_demand - - RecommendationAction: accept / dismiss / snooze re-check + - 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: [ - Read-only — Analyzers never modify Objects, - Recommendations created only if gap persists after re-check; - stale Recommendations invalidated automatically when gap closes, - confidence: partial allowed when external Connectors unavailable - (Analyzer continues with available data) + 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: Journey 1 (create design + tasks), or Journey 4 (implement feature) + NEXT: Project ready for day-to-day v2 journeys (1, 3, 7, 9, 12) ``` --- -### Journey 3: Bug Report → Fix PR +### Journey 3: Explore Design Options and Author an ADR ```text -ALGORITHM BugToFixPR - ACTOR: Developer - GOAL: Turn an open bug report into a validated pull request with a - reproduction test, a fix, and Evidence from all Validators +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: [ - bug (state: open) [sync: jira], - component[] — in Studio graph, + 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: [ - test_case — failing test proving reproduction, - pull_request (state: review) [write-back: github], - ValidationSession[] + Evidence — one per mandatory Validator, - WorkerRun[] — full execution trail + 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 (4 LLM Workers in chain) + 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. Developer selects bug Object in Studio UI. - Flow: bug_to_fix_pr_flow activates (entryConstraints: bug, state: open). - 2. bug_description_validator (hybrid, realtime): - - Validates bug has sufficient reproduction info - - ValidationSession created; on fail → bug returned for enrichment - 3. find_suspected_component (hybrid, on_demand): - - Input: bug → Output: component[] (ranked by suspicion) - 4. deploy_test_environment (script, on_demand): - - Input: component → Output: environment (ephemeral test env) - 5. reproduce_bug (hybrid, on_demand): - - Input: bug, environment → Output: WorkerRun with reproduction Evidence - 6. create_failing_test (llm, on_demand): - - Input: bug, reproduce output → Output: test_case (state: failing) - 7. confirm_test_fails_validator (script, realtime): - - Runs test_case against baseline; validates it fails - - ValidationSession; on fail → loop back to create_failing_test - 8. implement_fix (llm, on_demand): - - Input: bug, test_case → Output: source_file[] (fix) - 9. confirm_test_passes_validator (script, realtime): - - Runs test_case against fix; validates it passes - - ValidationSession; on fail → loop back to implement_fix - 10. create_pr_worker (hybrid, on_demand): - - Input: source_file[], branch → Output: pull_request [write-back: github] - - pull_request.verifiedBy = [test_case] - - pull_request.closesIssues = [bug] - DECISION: Write-back approval required? - - Gate 2 applies if WriteBackPolicy.requiresApproval = true for github + 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: - - BugDescriptionSufficiency: pass validator / enrich bug first - - FixLoopRetry: confirm_test_passes fails → re-run implement_fix - (up to Validator.maxRetries; then Approval escalation) - - WriteBackApproval: Gate 2 (github write-back) required / immediate + - ImportVsAuthor: import via Connector / author with create_prd_worker + - PRDAcceptance: approve / re-run with amendments + - GapResolution: WorkerInteraction (kind: menu) per gap GUARDS: [ - automationLevel >= approved_automation for all action Workers, - bug_description_validator must pass before find_suspected_component runs, - test_case must demonstrate failure on baseline before implement_fix runs, - pull_request.verifiedBy must reference the test_case produced in step 6, - all three Validator WorkerRuns must reach state: done with Evidence - before pull_request is created - ] - NEXT: Journey 6 (pr_design_validator fires automatically on PR creation), - or Journey 9 (release readiness) when PR is merged + 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 4: Feature Task → Pull Request +### Journey 8: Record an Architecture Decision ```text -ALGORITHM FeatureTaskToPullRequest +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: Implement a feature from a task with feature_spec linked, - produce a PR, and get automatic design conformance validation + 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: [ - task (state: in_progress) [sync: jira], - feature_spec — linked to task, + 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 + 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. Developer selects task Object linked to feature_spec in Studio UI. - 2. implement_code_worker (llm, on_demand): - - Input: feature_spec, task → Output: source_file[] - - Writes implementation; traceability markers link code to feature_spec IDs - 3. create_pr_worker (hybrid, on_demand): - - Input: source_file[], branch → Output: pull_request [write-back: github] - - pull_request.implementsRequirements = [requirement refs from feature_spec] - - pull_request.closesIssues = [task] - 4. pr_design_validator fires automatically (realtime, onEvent: PR → review): - - Input: pull_request, design[], acceptance_criteria[] - - Output: ValidationSession + ValidationResult + Evidence - - On fail: pull_request annotated with findings; developer fixes - 5. DECISION: Conformance pass? - - PASS: pull_request.conformsToDesign[] populated with Evidence; - PR ready for human review - - FAIL: developer amends source_file[]; create_pr_worker re-runs; - pr_design_validator re-fires (up to maxRetries; then Approval escalation) + 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: - - ConformanceResult: pass immediately / fail-and-fix loop + - 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: [ - automationLevel >= approved_automation for implement_code_worker - and create_pr_worker, - feature_spec must be linked to task before implement_code_worker runs, - 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 + 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 6 (design conformance fires automatically), - Journey 9 (release readiness after merge) + NEXT: Journey 13 (Change Impact) or Journey 17 (Release Readiness) ``` --- -### Journey 5: Accept a Recommendation +### Journey 13: Analyze Change Impact ```text -ALGORITHM AcceptRecommendation - ACTOR: Developer (or PM / Tech Lead depending on Recommendation severity) - GOAL: Act on an Analyzer-created Recommendation by running the - suggested fix Worker, verifying the gap is closed, and reaching - state: done +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: [ - Recommendation (state: pending) — created by an Analyzer Worker, - Objects referenced by Recommendation.suggestedInput + Changed Object ID (e.g., prd fr[] ID), + Baseline Object state (prior version or snapshot), + Current Object state (HEAD) ] OUTPUTS: [ - Recommendation (state: done), - Object — updated by suggestedWorker output, - WorkerRun — execution record of the fix + 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: low–high (depends on suggestedWorker runtime) - AUTOMATION GATE: approved_automation (for suggestedWorker if kind: action) + COST TIER: medium (traceability_analysis hybrid + stale_artifact_detection script) + AUTOMATION GATE: none (Analyzer Workers; read-only) STEPS: - 1. User sees Recommendation in Studio UI (notification or dashboard). - Recommendation shows: reason, severity, confidence, suggestedWorker, - suggestedInput (pre-filled from last re-check). - 2. DECISION: Re-check before accepting? - - YES: validationWorker runs; checks gap still exists; refreshes - suggestedInput to current Object state; recomputes severity - if severityWorker set. - DECISION: Gap still present? - - YES: proceed to step 3 with refreshed suggestedInput - - NO: Recommendation state → invalidated (gap closed already) - - NO (accept as-is): proceed to step 3 - 3. DECISION: suggestedInput changed since Recommendation created? - - YES: Studio shows diff of suggestedInput; user confirms or cancels - - NO: proceed directly - 4. User accepts Recommendation → state: accepted. - suggestedWorker invoked (automationLevel gate checked): - - Recommendation state → executing - - WorkerRun created for suggestedWorker - 5. suggestedWorker completes: - - Recommendation state → done - - Output Object updated with fix - 6. DECISION: Write-back to external system? - - If suggestedWorker output triggers Connector write-back: - Gate 2 (WriteBackPolicy) applies + 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: - - ReCheckBeforeAccepting: yes / no - - InputChangedConfirmation: confirm updated input / cancel - - WriteBackApproval: Gate 2 if output touches external system + - AnalysisMode: cascade-tracking / release-readiness-estimation + - PerRecommendationAction: accept / dismiss / snooze GUARDS: [ - automationLevel >= approved_automation if suggestedWorker is kind: action, - suggestedInput must be confirmed by user if it changed since Recommendation - was created, - Recommendation state machine: pending → accepted → executing → done; - no skipping states, - validationWorker re-check must complete before suggestedInput diff is shown - ] - NEXT: Depends on suggestedWorker output (may chain into Journey 3 or 4) + 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 6: PR Conformance to Design (Automatic) +### Journey 14: Review a Pull Request ```text -ALGORITHM PRConformanceToDesign - ACTOR: Tech Lead (reviewer) — Studio triggers automatically - GOAL: Validate a pull request against the linked design documents - and acceptance criteria; attach Evidence to the PR +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, - acceptance_criteria[] — from feature_spec or task + adr[] — for architecture decision consistency, + prd fr[] — for requirements traceability, + feature_spec[] — for acceptance criteria ] OUTPUTS: [ - ValidationSession (state: pass | fail | escalated), - ValidationResult + Evidence attached to pull_request, - Recommendation if non-critical conformance gaps found + 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) - AUTOMATION GATE: none (Validator runs at any automationLevel) + 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): - trigger: pull_request state_changed → review - 2. Validator reads pull_request diff, design[], acceptance_criteria[]. - 3. DECISION: Conformance result? - - PASS: ValidationResult (state: pass) + Evidence created; - pull_request.conformsToDesign[] populated. - Tech Lead notified (NotificationRule). - - FAIL (within maxRetries): ValidationResult (state: fail); - pull_request annotated with findings list; - developer notified to amend. - Developer pushes fix → pr_design_validator re-fires. - - FAIL (retries exhausted): ValidationSession state → escalated; - Approval (kind: risk_acceptance) created for Tech Lead; - Tech Lead approves exception or rejects PR. - 4. Tech Lead reviews ValidationResult in Studio UI (or GitHub comment - from Connector write-back if configured). + 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: [ - pr_design_validator fires on every push to the PR branch, not just once, - ValidationResult must be attached to pull_request before state can - advance to approved, - Escalation Approval must be resolved before ValidationSession closes, - Evidence is immutable once created (state: valid); revocation requires - explicit revokedBy + revokedAt - ] - NEXT: Journey 9 (release readiness) after PR merged + 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 7: Architecture Drift Detection +### Journey 15: Reconstruct SDLC Artifacts from Code ```text -ALGORITHM ArchitectureDriftDetection - ACTOR: Chief Architect / Tech Lead - GOAL: Detect components that have drifted from their design - specification and receive prioritized Recommendations +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: [ - component[] — in Studio graph, - component_dependency[] — current dependency graph, - design[] — reference architecture documents, - repository [sync: github] — for code-level evidence + Code scope (directory or file list) [sync: github], + Existing traceability markers in code (optional), + workspace configured ] OUTPUTS: [ - Recommendation[] (state: pending) — one per drifted component, - architecture_drift report (WorkerRun output) + 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: medium (architecture_drift_detection hybrid, scheduled) - AUTOMATION GATE: none + COST TIER: high (code_retriever hybrid + reverse_engineer_worker llm chain) + AUTOMATION GATE: approved_automation STEPS: - 1. architecture_drift_detection Analyzer runs on schedule (or on_demand): - - Compares current component[] + component_dependency[] against design[] - - Detects: new dependencies not in design, missing components, - interface contract violations, boundary violations - - Creates Recommendation per drift with severity + evidence - 2. Architect reviews Recommendation[] in Studio UI. - 3. DECISION: Response per Recommendation? - - ACCEPT: Architect triggers update of design[] to reflect - intentional drift (Journey not covered here — cf-write-docs) - - FIX: Architect assigns task to developer to fix the drift - (task created via create_tasks_worker or manually) - - DISMISS: drift intentional; Recommendation dismissed with reason - - ADR: drift requires an Architecture Decision Record before actioning + 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: - - DriftTrigger: scheduled (default: nightly) / on_demand - - DriftResponse: accept (update design) / fix (create task) / - dismiss / create ADR first + - MarkerStrategy: marker-first / pattern-inference + - TargetArtifactKinds: feature_spec only / full pipeline + - PerObjectAcceptance: approve / re-run with amendments GUARDS: [ - Read-only — architecture_drift_detection never modifies Objects, - confidence: partial if repository Connector unavailable - (Analyzer continues with graph data only), - Recommendations invalidated automatically if drift closes before action taken + 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: ADR authoring (if architecture_decision required), - Journey 4 (implement fix), or Journey 2 (broader gap analysis) + NEXT: Journey 13 (change impact) or Journey 12 (implement missing features) ``` --- -### Journey 8: Raise automationLevel +### Journey 16: Full SDLC Pipeline End-to-End ```text -ALGORITHM RaiseAutomationLevel - ACTOR: Architect / CTO - GOAL: Unlock action Workers for a Tenant by raising automationLevel, - gated by an Approval requiring an architecture decision +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: [ - Tenant (current automationLevel: recommendations | readonly), - proposed automationLevel: approved_automation | enterprise + Product idea or problem statement, + Studio v2 initialized with SDLC Kit and Connectors (Journey 2), + repository [sync: github], workspace [sync: jira] ] OUTPUTS: [ - Approval (kind: architecture_decision, state: approved), - Tenant.automationLevel updated, - Tenant.approvedWorkerCategories updated + 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: low (StatePolicy transition + Approval; human-driven) - AUTOMATION GATE: none (this journey IS the gate) + COST TIER: high (full chain of LLM + hybrid Workers) + AUTOMATION GATE: approved_automation STEPS: - 1. Architect initiates automationLevel raise in Studio UI. - 2. Studio checks StatePolicy for Tenant.automationLevel transition: - raising automationLevel → requiresApproval (always). - 3. Approval Object created: - kind: architecture_decision - payload: { proposedLevel, approvedWorkerCategories, rationale, - customerImpact? } - requiredRole: CTO | VP Engineering (per Tenant policy) - 4. Approver receives notification (NotificationRule: Approval pending). - 5. DECISION: Approver action? - - APPROVE: Tenant.automationLevel updated; - Tenant.approvedWorkerCategories updated; - action Workers of approved categories now available. - - REJECT: Approval state → rejected; automationLevel unchanged. - - EXPIRE: Approval.expiresAt reached without decision; - new Approval required. - 6. DECISION: Lowering automationLevel later? - - No Approval required (narrowing, not expanding); immediate. + 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: - - ApproverDecision: approve / reject / expire - - CategoryScope: which Worker categories to approve - (studio.category in approvedWorkerCategories) - - LowerLater: immediate (no Approval needed) + - 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: [ - Approval is mandatory for any automationLevel raise; no bypass, - Tenant.approvedWorkerCategories must be set alongside automationLevel - change — empty list blocks all action Workers even at approved_automation, - Lowering automationLevel requires no Approval but immediately - blocks action Workers in removed categories, - customerImpact field required when automationLevel >= enterprise - ] - NEXT: Journeys 1, 3, 4, 10, 11 now available (action Workers unlocked) + 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 9: Release Readiness Review +### Journey 17: Release Readiness Estimation ```text -ALGORITHM ReleaseReadinessReview - ACTOR: Release Manager / Tech Lead - GOAL: Gate a release candidate on automated validators and a required - Tech Lead approval, producing Evidence for the release audit trail +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 (state: candidate), + release Object (state: candidate), release_component[] — component versions in this release, - test_run[] [sync: github / CI], pull_request[] [sync: github] — merged PRs for this release, - vulnerability[] [sync: snyk / dependabot] + Changed upstream Object ID(s), + Baseline Object state (prior release tag) ] OUTPUTS: [ - release (state: approved | blocked), + release Object (state: approved | blocked), ValidationSession[] + Evidence — per mandatory Validator, - Approval (kind: release_approval) — Tech Lead sign-off + 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 (hybrid Validators; script test coverage check) + COST TIER: medium (traceability_analysis hybrid + release_readiness_review Flow) AUTOMATION GATE: none (Validators run at any automationLevel; - Approval is StatePolicy gate, not automationLevel gate) + Approval is StatePolicy gate) STEPS: - 1. Release Manager creates release (state: candidate) in Studio. - Flow: release_readiness_review activates. - 2. gap_analysis_validator (hybrid, realtime): - - Checks all requirements in scope are implemented + tested - - ValidationSession; on fail → release blocked with gap list - 3. test_coverage_validator (script, realtime): - - Checks test coverage >= 80% for release_component[] scope - - ValidationSession; on fail → release blocked - 4. security_scan_validator (hybrid, realtime): - - Checks no critical/high vulnerability[] without approved Approval - (kind: security_exception) in release scope - - ValidationSession; on fail → release blocked unless security exceptions - are in place with valid expiresAt - 5. All three Validators pass → Approval (kind: release_approval) created: + 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, Evidence[] from all validators, - customerImpact if scope != internal } - 6. Tech Lead approves → release state: approved. - 7. DECISION: Any Validator failed? - - gap_analysis: PM/Dev must close gaps; re-run gap_analysis_validator - - test_coverage: Dev must add tests; re-run test_coverage_validator - - security_scan: Security Lead must create security_exception Approval - for each outstanding vulnerability (Journey 12) + 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 + - ValidatorFailureResolution: fix gaps / add tests / create security exception + - VersionBumpConfirmation: WorkerInteraction (kind: menu) to confirm/override - TechLeadApprovalDecision: approve / request changes / reject GUARDS: [ - All three mandatory Validators must reach ValidationSession.state: pass + All mandatory Validators must reach ValidationSession.state: pass before Approval is created, - security_exception Approvals must have valid expiresAt (not expired) - before security_scan_validator accepts them, - release state: approved requires Approval.state: approved; - StatePolicy enforces this transition, - Evidence from each Validator is immutable and attached to release audit trail + 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 11 (deploy to environment) + NEXT: Journey 12 if gaps found (implement missing features), + external deploy pipeline after release.state: approved ``` --- -### Journey 10: Incident → Postmortem +### Journey 18: PR Status Monitoring ```text -ALGORITHM IncidentToPostmortem - ACTOR: SRE / On-call Engineer - GOAL: Automatically draft a postmortem and prevention tasks from a - resolved incident +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: [ - incident (state: resolved) [sync: pagerduty / datadog], - WorkerRun[] — execution history during incident window, - alert[] [sync: datadog / pagerduty], - on_call_schedule — for postmortem ownership assignment + pull_request[] (state: review) [sync: github], + ValidationSession[] — associated with each pull_request, + workspace [sync: github] configured ] OUTPUTS: [ - postmortem (→ document) — structured incident analysis, - task[] (prevention) [write-back: jira] — action items, - Evidence — from incident_summary_validator + 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: medium–high (incident_summary_validator hybrid + - postmortem_draft_worker llm + prevention_tasks_worker hybrid) - AUTOMATION GATE: approved_automation + COST TIER: low (connector_inbound_sync_worker script + traceability_analysis) + AUTOMATION GATE: none (read-only Analyzer Workers) STEPS: - 1. connector_inbound_sync_worker receives incident (state: resolved) - from PagerDuty/Datadog via Gears OAGW. - Flow: incident_to_postmortem_flow activates. - 2. incident_summary_validator (hybrid, realtime): - - Validates incident has timeline, severity, affected systems - - ValidationSession; on fail → on-call enriches incident data - 3. postmortem_draft_worker (llm, on_demand): - - Input: incident, WorkerRun[] (execution history), alert[] - - Output: postmortem (state: draft) with: - timeline, root cause, contributing factors, impact assessment - 4. prevention_tasks_worker (hybrid, on_demand): - - Input: postmortem → Output: task[] (prevention actions) - - Tasks linked to postmortem.closedBy and relevant component[] - 5. On-call Engineer reviews postmortem in Studio UI: - DECISION: Postmortem acceptable? - - YES: postmortem state → published - - EDIT: Engineer edits draft directly; re-runs prevention_tasks_worker - if root cause changes - 6. task[] [write-back: jira] via connector_outbound_sync_worker - (Gate 2: WriteBackPolicy for jira write-back). + 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: - - IncidentDataSufficiency: validator pass / enrich first - - PostmortemAcceptance: publish as-is / edit draft - - WriteBackApproval: Gate 2 (jira write-back) + - ReviewScope: single PR / all open PRs + - ResolvedFindingAudit: surface all / only suspicious resolutions + - PerPRAction: merge / request changes / escalate GUARDS: [ - automationLevel >= approved_automation for postmortem_draft_worker - and prevention_tasks_worker, - incident_summary_validator must pass before postmortem_draft_worker runs, - postmortem must be reviewed and published by the on-call owner before - prevention tasks are written to Jira, - WorkerRun[] execution history read-only; never modified by this flow - ] - NEXT: Journey 2 (gap analysis on prevention tasks coverage), - Journey 9 (if incident triggered a release rollback) + 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 11: Deploy to Environment +### Journey 19: Traceability Coverage Gate in CI ```text -ALGORITHM DeployToEnvironment - ACTOR: DevOps / Release Manager - GOAL: Deploy a validated build_artifact to a target environment - with an optional Approval gate for production +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: [ - build_artifact — produced by CI pipeline [sync: github actions / jenkins], - environment (target: staging | prod), - release (state: approved) — for production deploys + 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: [ - deployment (state: done | failed), - deployment_status[] — one per deploy step, - WorkerRun — execution record + 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 (deploy_worker script only) - AUTOMATION GATE: approved_automation + COST TIER: low (script Worker + CI Connector; no LLM) + AUTOMATION GATE: none (script Validator; read-only) STEPS: - 1. Release Manager selects build_artifact + environment in Studio. - 2. DECISION: Production deployment? - - PROD: release must be in state: approved (Journey 9 completed); - Approval (kind: release_approval) must be present. - WriteBackPolicy.requiresApproval = true for prod environments - (Gate 2) — if not yet approved, Approval created. - - STAGING: proceed directly (WriteBackPolicy.requiresApproval = false) - 3. deploy_worker (script, on_demand): - - Input: build_artifact, environment - - Triggers CI/CD pipeline write-back [write-back: github actions / argocd] - - Output: deployment Object + deployment_status[] - 4. deployment state transitions: pending → running → done | failed - 5. DECISION: Deployment failed? - - YES: deployment state → failed; rollback decision required. - Studio creates Recommendation (suggestedWorker: rollback_worker) - - NO: deployment state → done; release state → deployed + 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: - - EnvironmentTier: staging (no Approval) / production (Approval required) - - FailureResponse: rollback / investigate / retry + - ScanScope: full codebase / scoped to feature area + - FailMode: hard fail (CI blocks merge) / warn only (advisory) GUARDS: [ - automationLevel >= approved_automation for deploy_worker, - Production deploy requires release.state: approved before deploy_worker - can be invoked, - WriteBackPolicy.allowedActions must include deploy action for the - target environment, - deployment_status[] appended on each step; never overwritten + 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: Operations monitoring (SLO/SLI tracking outside Studio), - Journey 10 if deployment triggers incident + NEXT: Add missing markers → push fix → CI re-runs → merge when PASS ``` --- -### Journey 12: Security Exception Approval +### Journey 20: Cross-Workspace Traceability Navigation ```text -ALGORITHM SecurityExceptionApproval - ACTOR: Security Lead - GOAL: Formally accept a known vulnerability that cannot be immediately - fixed, with a time-bounded exception and auto-review schedule +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: [ - vulnerability or security_finding [sync: snyk / dependabot / pentest], - risk assessment context + Workspace Object — initialized with registered sources (multi-repo), + Object ID to investigate, + All Workspace sources reachable via Connectors ] OUTPUTS: [ - Approval (kind: security_exception, state: approved), - policy_exception Object — linked to vulnerability, - scheduled re-review Approval (via autoReviewAfter Worker) + 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 (human-driven; security_impact_analysis for context only) - AUTOMATION GATE: none (Approval flow is human-driven) + COST TIER: low (object_graph_retriever hybrid; read-only) + AUTOMATION GATE: none (read-only Retriever and Analyzer Workers) STEPS: - 1. Security Lead sees vulnerability or security_finding in Studio. - DECISION: Run impact analysis first? - - YES: security_impact_analysis Analyzer (hybrid, on_demand) runs: - Input: pull_request[], vulnerability[], security_finding[] - Output: Recommendation with severity + affected component[] - - NO: proceed with known context - 2. Security Lead initiates security_exception Approval: - kind: security_exception - payload: { - expiresAt, - acceptedRisk, - mitigations: [], - secondaryApprover? (required if severity: critical), - autoReviewAfter: duration - } - 3. DECISION: Secondary approver required? - - YES (severity: critical): second Approval from CISO / VP Eng - - NO: single Security Lead approval sufficient - 4. Approval approved → policy_exception created: - linked to vulnerability; blocks security_scan_validator from - failing on this vulnerability until expiresAt - 5. autoReviewAfter schedule creates a new Approval automatically - when duration elapses — forces periodic re-evaluation. + 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: - - ImpactAnalysisFirst: run security_impact_analysis / skip - - SecondaryApproverRequired: yes (critical severity) / no - - ExceptionDuration: set expiresAt (max enforced by Tenant policy) + - 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: [ - security_exception Approval must have expiresAt set; no open-ended exceptions, - Critical severity vulnerabilities require secondaryApprover, - autoReviewAfter must be set; exceptions without review schedule are rejected, - policy_exception scope limited to the specific vulnerability Object; - wildcards not permitted + 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 9 (security_scan_validator will now accept this exception) + NEXT: Journey 13 (if change is planned), or update Object referencing this ID ``` --- -### Journey 13: SBOM Security Scan +### Journey 21: Interactive Kit Update ```text -ALGORITHM SBOMSecurityScan - ACTOR: Security Engineer / DevOps - GOAL: Scan a build artifact's SBOM for vulnerable dependencies and - generate remediation Recommendations +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: [ - build_artifact — produced by CI, - sbom — attached to build_artifact (SPDX / CycloneDX), - sbom_component[] — packages listed in SBOM, - dependency_vulnerability[] [sync: snyk / dependabot / github advisory] + Installed Kit (.cf-studio-kit.toml on disk), + Upstream Kit source (Kit Registry, local path, or GitHub ref), + Workspace with Kit installed ] OUTPUTS: [ - Recommendation[] — upgrade library_version for each vulnerable component, - compliance_check_result[] — license policy check, - task[] (remediation) — if Recommendation accepted + 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: medium (security_impact_analysis hybrid; license check script) - AUTOMATION GATE: none + COST TIER: low (Kit version check script + WorkerInteraction menus) + AUTOMATION GATE: approved_automation (Kit install Worker writes to graph) STEPS: - 1. build_artifact created → onEvent trigger fires security_impact_analysis - (Analyzer, hybrid, scheduled + onEvent). - 2. Analyzer reads sbom → sbom_component[] → library_version[]: - - Matches against dependency_vulnerability[] [sync: snyk] - - Identifies: critical/high CVEs, license policy violations - 3. For each vulnerable sbom_component: - - Recommendation created: severity per CVE cvssScore, - suggestedWorker: upgrade to fixedVersion library_version - 4. compliance_check runs (script): - - Checks sbom_license[] against Tenant license policy - - compliance_check_result: pass | fail - - On fail: Recommendation for license review or policy_exception - 5. Security Engineer reviews Recommendations: - DECISION: Per Recommendation action? - - ACCEPT → Journey 5 (accept Recommendation); upgrade triggers - create_pr_worker [write-back: github] - - EXCEPTION → Journey 12 (security_exception Approval) - - DISMISS → Recommendation dismissed with reason + 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: - - PerRecommendationAction: accept (upgrade) / exception / dismiss - - LicensePolicyViolation: accept (policy_exception) / fix (update dep) + - ProceedWithUpdate: proceed / skip / show changelog + - PerFileDecision: accept upstream / keep existing / diff and edit + (WorkerInteraction per file) + - RegenerateWorkers: yes / no GUARDS: [ - Read-only scan — never modifies sbom or build_artifact, - confidence: partial if snyk/dependabot Connector unavailable - (scan continues with available CVE data), - Recommendations linked to specific sbom_component + library_version; - not to build_artifact as a whole + 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: Journey 12 (security_exception) or Journey 5 (accept upgrade Recommendation) + NEXT: Test updated Kit Workers in a representative journey ``` --- -### Journey 14: External System Inbound Sync +### Journey 22: Object Graph Navigation ```text -ALGORITHM ExternalSystemInboundSync - ACTOR: (platform — no direct user interaction) - GOAL: Keep Studio graph Objects current with external system state - by processing inbound Connector events +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: [ - Gears OAGW event — from external system (Jira, GitHub, PagerDuty, etc.), - Connector (registry entity) — defines FieldMappings + syncProtocol, - {vendor}_event_handler_worker (per-Kit) — custom mapping logic + 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: [ - Object (created | updated) — in Studio graph, - externalRef populated: { connectorId, externalId, externalUrl, lastSyncedAt }, - WorkerRun — execution record of sync Worker + 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 (script Workers) - AUTOMATION GATE: none (platform Worker; not subject to automationLevel gate) + 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. External system emits event (push) or Studio polls (pull) via Gears OAGW. - Connector.syncProtocol determines push vs pull: - - push: webhook received via OAGW webhookPath; secret verified - - pull: scheduled interval poll; incremental if supported - 2. connector_inbound_sync_worker (script, realtime): - - Receives raw OAGW event payload - - Looks up Connector FieldMappings for this event type - - Invokes per-Kit {vendor}_event_handler_worker for custom logic - 3. {vendor}_event_handler_worker (per-Kit): - DECISION: Object exists in Studio graph? - - YES (externalRef.externalId matches): UPDATE Object - - Apply FieldMappings: direct | lookup | transform Worker - - Update Object.updatedAt, externalRef.lastSyncedAt - - Emit object_updated event → may trigger Analyzers - - NO: CREATE Object - - Assign GTS Type ID from Connector Kit type mapping - - Populate Object fields via FieldMappings - - Set externalRef - - Emit object_created event - 4. WorkerRun recorded (write-ahead: externalEvents[] populated before - any Object modification begins). - 5. DECISION: Conflict detected (Object modified in Studio since last sync)? - - Connector.WriteBackPolicy.conflictStrategy applies: - - overwrite: external wins - - skip: Studio version kept; event logged - - merge: field-level merge (if FieldMapping supports) - - escalate (default): Approval (kind: custom) created for human resolution + 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: - - SyncDirection: push (event-driven) / pull (scheduled interval) - - ObjectExistence: create / update - - ConflictResolution: overwrite / skip / merge / escalate + - 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: [ - externalEvents[] write-ahead must complete before Object is modified, - FieldMappings must not map external fields to Object.id or Object.tenantId, - Connector scopeFilter (per Tenant) must be evaluated before Object creation - — events outside scope silently dropped, - rateLimit enforced by Gears OAGW upstream; sync Worker never called - above the Kit-declared rate - ] - NEXT: Object now available in Studio graph for Analyzer Workers, - Recommendations, and user-driven journeys + 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 -### Object lifecycle as the common thread +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. -All journeys operate on named Objects (bug, task, pull_request, incident, release, etc.) -that flow through Studio's graph. Workers move Objects from state to state. -Connectors bring external Objects in (inbound sync) and push Studio actions back -(outbound write-back). The graph is the source of truth; external systems are peers. +### Worker-Chain Pattern -### Validator-first quality gate +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. -Journeys 3, 4, 6, 9, and 10 all include mandatory Validator steps before an Object -can advance to its next state. Validators produce ValidationSessions and Evidence — -immutable proof that quality gates were cleared. Evidence is attached to the Object -(pull_request.conformsToDesign, release audit trail) and cannot be retracted without -explicit revocation. +### Validator-First Quality Gate -### automationLevel as the permission dial +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. -Journeys 1, 3, 4, 10, and 11 require `automationLevel >= approved_automation` for -action Workers (Workers that change state or write back to external systems). Read-only -Analyzers and Validators (Journeys 2, 6, 7, 9) run at any automationLevel. Journey 8 -is the explicit gate for raising the level. Lowering it requires no approval. +### automationLevel Dial -### Connector-mediated Objects +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. -Most journeys include Objects synced from external systems (`[sync: jira]`, -`[sync: github]`, `[sync: pagerduty]`). 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-Mediated Objects -### Write-back as a two-gate operation - -Any action that modifies an external system (creating a Jira issue, opening a GitHub PR, -triggering a deploy) passes through two independent gates: +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). -- **Gate 1 (Studio execution):** `automationLevel >= approved_automation AND - category in approvedWorkerCategories` — controls whether the action Worker runs at all. -- **Gate 2 (Connector write-back):** `WriteBackPolicy.requiresApproval` — controls - whether the output is sent to the external system; may require a separate Approval. +### WorkerInteraction Mid-Run -Both gates must pass; Gate 1 does not imply Gate 2 clearance. +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 and audit trail +### 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`. The combination forms a complete audit trail -from intent to production. +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. From 2093ba5e37d019f68fe493196c92a8480bcc166e Mon Sep 17 00:00:00 2001 From: ainetx Date: Sun, 5 Jul 2026 16:25:51 +0300 Subject: [PATCH 023/106] docs(v2): split Worker.trigger into canInvokeOnDemand, eventTrigger, WorkerImplementation.defaultSchedule Signed-off-by: ainetx Co-authored-by: Constructor Studio <291158726+constructor-studio[bot]@users.noreply.github.com> Studio-Generated-By: Constructor Studio Studio-Source-Repo: https://github.com/constructorfabric/studio Constructor-Fabric: https://github.com/constructorfabric Studio-Version: skill=1.5.9, cli=1.5.10.dev73 Studio-Workflows: cf-brainstorm --- v2/docs/domain-model.md | 23 ++++++++++++----------- 1 file changed, 12 insertions(+), 11 deletions(-) diff --git a/v2/docs/domain-model.md b/v2/docs/domain-model.md index 1536d2c6..590ee944 100644 --- a/v2/docs/domain-model.md +++ b/v2/docs/domain-model.md @@ -443,14 +443,13 @@ Worker { implementationId: ref → WorkerImplementation requiresAutomationGate: boolean // default: false // true = Gate 1 applies (automationLevel check) - trigger?: { - schedule?: cron string - onEvent?: { - pattern: GTS Type Identifier - debounce: duration // default: 0 - } - onDemand: boolean // default: true + 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 @@ -542,6 +541,8 @@ WorkerImplementation { 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 @@ -1378,7 +1379,7 @@ Recommendation extends Object { ```mermaid flowchart TD - AW["Analyzer Worker\n(schedule/onEvent/onDemand)"] -->|creates| REC["Recommendation\nextends Object"] + AW["Analyzer Worker\n(defaultSchedule/eventTrigger)"] -->|creates| REC["Recommendation\nextends Object"] REC -->|state| S1[pending] S1 -->|user accepts| S2[accepted] @@ -1393,8 +1394,8 @@ flowchart TD ### 15.2 Analyzer Workers -Detect gaps and create Recommendations. Use standard Worker `trigger` with -`schedule`, `onEvent` (+ `debounce`), and `onDemand`. +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. @@ -1811,7 +1812,7 @@ Declared per Object type. Tenant can override via `obj_ext`. `stale_artifact_detection` Analyzer Worker (from Flow Library): - Updates `stalenessScore` on affected Objects -- Profile: `realtime`; trigger: `schedule: "*/15 * * * *"` + `onEvent` with `debounce: 5m` +- Profile: `realtime`; `defaultSchedule: "*/15 * * * *"`; `eventTrigger.debounce: 5m` - Creates `Recommendation` when `stalenessScore >= recommendationThreshold` --- From fe93bf323723e4a4459bfeb4c2d2b1d286d96663 Mon Sep 17 00:00:00 2001 From: ainetx Date: Sun, 5 Jul 2026 16:35:15 +0300 Subject: [PATCH 024/106] =?UTF-8?q?docs(v2):=20add=20Flow=20checklist=20mo?= =?UTF-8?q?del=20=E2=80=94=20stepStatus,=20activeStepId,=20stepDependencie?= =?UTF-8?q?s?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: ainetx Co-authored-by: Constructor Studio <291158726+constructor-studio[bot]@users.noreply.github.com> Studio-Generated-By: Constructor Studio Studio-Source-Repo: https://github.com/constructorfabric/studio Constructor-Fabric: https://github.com/constructorfabric Studio-Version: skill=1.5.9, cli=1.5.10.dev73 Studio-Workflows: cf-brainstorm --- .../studio-v2-domain-model-2026-07-03/state.md | 4 +++- v2/docs/domain-model.md | 14 +++++++++++--- 2 files changed, 14 insertions(+), 4 deletions(-) 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 index 2d0fb2dd..7da182fb 100644 --- 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 @@ -2,7 +2,7 @@ **Session ID:** studio-v2-domain-model-2026-07-03 **Date:** 2026-07-03 -**Rounds:** 33 +**Rounds:** 35 **Mode:** inline / normal **SIMPLE_MODE:** normal **BRAINSTORM_MAX_ROUNDS:** 10 (exceeded — continued by user choice) @@ -75,6 +75,8 @@ | 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 | --- diff --git a/v2/docs/domain-model.md b/v2/docs/domain-model.md index 590ee944..c213b26d 100644 --- a/v2/docs/domain-model.md +++ b/v2/docs/domain-model.md @@ -717,8 +717,11 @@ Flow extends Worker { } } ] - mandatorySteps: Worker[] // subset of steps that must execute - allowedNextSteps: map + mandatorySteps: Worker[] // ordered list = planned checklist items + stepDependencies?: map + // explicit deps for UI dependency graph; + // if absent: steps assumed sequential per mandatorySteps order + allowedNextSteps: map conditionalRoutes?: [ { fromWorker: ref → Worker @@ -741,9 +744,14 @@ 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~ - // additional orchestrator fields: + // 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) } ``` From 2f1272e820870fe3a608a5d884a0866bc0d4a628 Mon Sep 17 00:00:00 2001 From: ainetx Date: Sun, 5 Jul 2026 16:36:43 +0300 Subject: [PATCH 025/106] fix(v2): add repositoryId ref and name to Workspace; refine sources schema with role enum Signed-off-by: ainetx Co-authored-by: Constructor Studio <291158726+constructor-studio[bot]@users.noreply.github.com> Studio-Generated-By: Constructor Studio Studio-Source-Repo: https://github.com/constructorfabric/studio Constructor-Fabric: https://github.com/constructorfabric Studio-Version: skill=1.5.9, cli=1.5.10.dev73 Studio-Workflows: cf-brainstorm --- v2/docs/domain-model.md | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/v2/docs/domain-model.md b/v2/docs/domain-model.md index c213b26d..373516dc 100644 --- a/v2/docs/domain-model.md +++ b/v2/docs/domain-model.md @@ -830,12 +830,25 @@ Multi-repo configuration. **Extends Object.** ``` Workspace extends Object { typeId: gts.cf.studio.core.object.v1~cf.studio.core.workspace.v1~ + name: string sources: [ - { path: string, role: string, adapter?: string, url?: string, branch?: string } + { + 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 From 2b03289f61c950a9b7c3cab9c5bf4a89d01f769a Mon Sep 17 00:00:00 2001 From: ainetx Date: Sun, 5 Jul 2026 16:37:46 +0300 Subject: [PATCH 026/106] =?UTF-8?q?docs(v2):=20update=20D27=20Workspace=20?= =?UTF-8?q?diagram=20=E2=80=94=20add=20repositoryId=20ref,=20name,=20role?= =?UTF-8?q?=20enum?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: ainetx Co-authored-by: Constructor Studio <291158726+constructor-studio[bot]@users.noreply.github.com> Studio-Generated-By: Constructor Studio Studio-Source-Repo: https://github.com/constructorfabric/studio Constructor-Fabric: https://github.com/constructorfabric Studio-Version: skill=1.5.9, cli=1.5.10.dev73 Studio-Workflows: cf-brainstorm --- v2/docs/domain-model.md | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/v2/docs/domain-model.md b/v2/docs/domain-model.md index 373516dc..db5219c9 100644 --- a/v2/docs/domain-model.md +++ b/v2/docs/domain-model.md @@ -854,16 +854,21 @@ or `url` alone is sufficient (CLI-only or unsynced workspace). ```mermaid classDiagram class Workspace { + name: string tenantId: ref Tenant sources: SourceEntry[] } class SourceEntry { - path: string + repositoryId: ref repository? + path: string? url: string? - role: 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 @@ -874,7 +879,7 @@ classDiagram } Workspace "1" --> "many" SourceEntry : sources - SourceEntry --> repository : resolves to + SourceEntry "0..1" --> "0..1" repository : repositoryId (auto-resolved by Connector) Tenant "1" --> "many" Kit : installed Kits Workspace --> Tenant : tenantId ``` From da69ec615cceff331b5c6d9a154fa9fa56db8935 Mon Sep 17 00:00:00 2001 From: ainetx Date: Sun, 5 Jul 2026 16:40:10 +0300 Subject: [PATCH 027/106] docs(v2): move D1 (Registry vs Object Graph) into Overview section Signed-off-by: ainetx Co-authored-by: Constructor Studio <291158726+constructor-studio[bot]@users.noreply.github.com> Studio-Generated-By: Constructor Studio Studio-Source-Repo: https://github.com/constructorfabric/studio Constructor-Fabric: https://github.com/constructorfabric Studio-Version: skill=1.5.9, cli=1.5.10.dev73 Studio-Workflows: cf-brainstorm --- v2/docs/domain-model.md | 54 ++++++++++++++++++++++------------------- 1 file changed, 29 insertions(+), 25 deletions(-) diff --git a/v2/docs/domain-model.md b/v2/docs/domain-model.md index db5219c9..ff4285c0 100644 --- a/v2/docs/domain-model.md +++ b/v2/docs/domain-model.md @@ -39,6 +39,34 @@ flowchart TB --- +### 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 +``` + +--- + ### DO2 — Registry Entity Relationships ```mermaid @@ -963,31 +991,7 @@ Kit manifest: ## 11. System Overview -### D1 — System Overview: Registry vs Object Graph - -```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 -``` +See D1 and DO1–DO6 in the Overview section above for high-level diagrams. ### D31 — Full Object Reference Map (top-level) From 4d3bb02da939b62315fdbb734479004ed94d92c6 Mon Sep 17 00:00:00 2001 From: ainetx Date: Sun, 5 Jul 2026 16:42:25 +0300 Subject: [PATCH 028/106] =?UTF-8?q?docs(v2):=20move=20ASCII=20system=20ove?= =?UTF-8?q?rview=20(DO1b)=20to=20Overview=20section;=20remove=20from=20?= =?UTF-8?q?=C2=A711?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: ainetx Co-authored-by: Constructor Studio <291158726+constructor-studio[bot]@users.noreply.github.com> Studio-Generated-By: Constructor Studio Studio-Source-Repo: https://github.com/constructorfabric/studio Constructor-Fabric: https://github.com/constructorfabric Studio-Version: skill=1.5.9, cli=1.5.10.dev73 Studio-Workflows: cf-brainstorm --- v2/docs/domain-model.md | 66 ++++++++++++++++++++++------------------- 1 file changed, 35 insertions(+), 31 deletions(-) diff --git a/v2/docs/domain-model.md b/v2/docs/domain-model.md index ff4285c0..128fc906 100644 --- a/v2/docs/domain-model.md +++ b/v2/docs/domain-model.md @@ -67,6 +67,41 @@ flowchart TD --- +### 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 + ▼ +┌─────────────────────────────────────────────────────────────┐ +│ OBJECT GRAPH │ +│ gts.cf.studio.core.object.v1~ (base) │ +│ │ +│ Tenant* Workspace WorkerRun FlowRun │ +│ User* Role Recommendation │ +│ Requirement Task PullRequest Build │ +│ Design Incident IdentityMapping │ +│ PolicyOverride PolicyDelegation SavedAuditQuery │ +│ NotificationRuleOverride NotificationSubscription │ +│ │ +│ * extends Gears base types (AM/RG) │ +└─────────────────────────────────────────────────────────────┘ +``` + +--- + ### DO2 — Registry Entity Relationships ```mermaid @@ -1017,37 +1052,6 @@ flowchart TD end ``` -``` -┌─────────────────────────────────────────────────────────────┐ -│ 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 - ▼ -┌─────────────────────────────────────────────────────────────┐ -│ OBJECT GRAPH │ -│ gts.cf.studio.core.object.v1~ (base) │ -│ │ -│ Tenant* Workspace WorkerRun FlowRun │ -│ User* Role Recommendation │ -│ Requirement Task PullRequest Build │ -│ Design Incident IdentityMapping │ -│ PolicyOverride PolicyDelegation SavedAuditQuery │ -│ NotificationRuleOverride NotificationSubscription │ -│ │ -│ * extends Gears base types (AM/RG) │ -└─────────────────────────────────────────────────────────────┘ -``` - --- ## 12. Object Lifecycle & State Transitions From e158efbb8456082566420b20eb5a3d830dc25ad7 Mon Sep 17 00:00:00 2001 From: ainetx Date: Mon, 6 Jul 2026 12:43:42 +0300 Subject: [PATCH 029/106] =?UTF-8?q?docs(v2):=20add=20ModelRouter,=20Prompt?= =?UTF-8?q?Experiment,=20Tenant.modelOverrides=20=E2=80=94=20AI=20cost=20r?= =?UTF-8?q?outing?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: ainetx Co-authored-by: Constructor Studio <291158726+constructor-studio[bot]@users.noreply.github.com> Studio-Generated-By: Constructor Studio Studio-Source-Repo: https://github.com/constructorfabric/studio Constructor-Fabric: https://github.com/constructorfabric Studio-Version: skill=1.5.9, cli=1.5.10.dev73 Studio-Workflows: cf-brainstorm --- .../state.md | 3 +- v2/docs/domain-model.md | 85 +++++++++++++++++-- 2 files changed, 81 insertions(+), 7 deletions(-) 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 index 7da182fb..47d23825 100644 --- 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 @@ -2,7 +2,7 @@ **Session ID:** studio-v2-domain-model-2026-07-03 **Date:** 2026-07-03 -**Rounds:** 35 +**Rounds:** 36 **Mode:** inline / normal **SIMPLE_MODE:** normal **BRAINSTORM_MAX_ROUNDS:** 10 (exceeded — continued by user choice) @@ -77,6 +77,7 @@ | 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 | --- diff --git a/v2/docs/domain-model.md b/v2/docs/domain-model.md index 128fc906..9a88f3ec 100644 --- a/v2/docs/domain-model.md +++ b/v2/docs/domain-model.md @@ -408,6 +408,7 @@ 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~ ``` ### 2.4 Vendor (Kit) Extensions @@ -586,7 +587,9 @@ WorkerImplementation { version: semver runtime: llm | script | hybrid config: { - // llm: { model, prompt, temperature, ... } + // llm: { model: GTS Model ID, prompt, temperature, ... + // modelRouterId?: ref → ModelRouter // dynamic model selection + // } // script: { entrypoint, language, ... } // hybrid: { steps[] } } @@ -626,7 +629,74 @@ WorkerImplementation { } ``` -### 4.2 Composability +### 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 + 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 — @@ -827,10 +897,13 @@ 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 + 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 } ``` From 112bdf8578dba5487841a1b4f9d48891dc869070 Mon Sep 17 00:00:00 2001 From: ainetx Date: Mon, 6 Jul 2026 12:47:49 +0300 Subject: [PATCH 030/106] docs(v2): add Kit.metadata (referenceArchitecture, deploymentPatterns) and Tenant.allowedKitPatterns Signed-off-by: ainetx Co-authored-by: Constructor Studio <291158726+constructor-studio[bot]@users.noreply.github.com> Studio-Generated-By: Constructor Studio Studio-Source-Repo: https://github.com/constructorfabric/studio Constructor-Fabric: https://github.com/constructorfabric Studio-Version: skill=1.5.9, cli=1.5.10.dev73 Studio-Workflows: cf-brainstorm --- .../state.md | 3 +- v2/docs/domain-model.md | 31 +++++++++++++++++++ 2 files changed, 33 insertions(+), 1 deletion(-) 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 index 47d23825..569660ec 100644 --- 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 @@ -2,7 +2,7 @@ **Session ID:** studio-v2-domain-model-2026-07-03 **Date:** 2026-07-03 -**Rounds:** 36 +**Rounds:** 37 **Mode:** inline / normal **SIMPLE_MODE:** normal **BRAINSTORM_MAX_ROUNDS:** 10 (exceeded — continued by user choice) @@ -78,6 +78,7 @@ | 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 | --- diff --git a/v2/docs/domain-model.md b/v2/docs/domain-model.md index 9a88f3ec..1b7afb2a 100644 --- a/v2/docs/domain-model.md +++ b/v2/docs/domain-model.md @@ -904,6 +904,10 @@ Tenant { 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 } ``` @@ -1095,6 +1099,33 @@ Kit manifest: - 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 } +``` + +`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 From b84e6bc47dc57286ab9ae2e8d8abaec8f7798c6f Mon Sep 17 00:00:00 2001 From: ainetx Date: Mon, 6 Jul 2026 12:50:19 +0300 Subject: [PATCH 031/106] =?UTF-8?q?docs(v2):=20close=20all=20remaining=20o?= =?UTF-8?q?pen=20questions=20=E2=80=94=20indexes,=20component=20kinds,=20P?= =?UTF-8?q?romptExperiment=20sig,=20conditionalRoutes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: ainetx Co-authored-by: Constructor Studio <291158726+constructor-studio[bot]@users.noreply.github.com> Studio-Generated-By: Constructor Studio Studio-Source-Repo: https://github.com/constructorfabric/studio Constructor-Fabric: https://github.com/constructorfabric Studio-Version: skill=1.5.9, cli=1.5.10.dev73 Studio-Workflows: cf-brainstorm --- .../state.md | 3 +- v2/docs/domain-model.md | 28 ++++++++++++++++--- 2 files changed, 26 insertions(+), 5 deletions(-) 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 index 569660ec..06b9b1ff 100644 --- 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 @@ -2,7 +2,7 @@ **Session ID:** studio-v2-domain-model-2026-07-03 **Date:** 2026-07-03 -**Rounds:** 37 +**Rounds:** 38 **Mode:** inline / normal **SIMPLE_MODE:** normal **BRAINSTORM_MAX_ROUNDS:** 10 (exceeded — continued by user choice) @@ -79,6 +79,7 @@ | 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 | --- diff --git a/v2/docs/domain-model.md b/v2/docs/domain-model.md index 1b7afb2a..c765d05e 100644 --- a/v2/docs/domain-model.md +++ b/v2/docs/domain-model.md @@ -434,7 +434,19 @@ 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 (`x-gts-traits`). +(`x-gts-source: platform | never-user`), traits + indexes (`x-gts-traits`). + +`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 } + ] +} +``` ```json { @@ -524,7 +536,10 @@ Worker { } ] // Flow.config.steps[].inputBinding overrides Worker.inputBindings per step - fallbackWorkerId?: ref → Worker // must have compatible output Contract + 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 @@ -676,6 +691,8 @@ PromptExperiment extends Object { 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 @@ -859,6 +876,7 @@ Flow extends Worker { { 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 @@ -2261,7 +2279,9 @@ cf.studio.core.decomposition.v1~ // → document (Studio SDLC DECOMPOSIT ``` 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 (service, module, library, subsystem) +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~ @@ -2276,7 +2296,7 @@ cf.studio.core.architecture_diagram.v1~ classDiagram class component { name: string - kind: service|library|module|subsystem + kind: service|library|module|subsystem|frontend|backend|data-pipeline|sdk|plugin|cli|agent|gateway ownerId: ref team repositoryId: ref repository } From aa4bb1ec81458ad64df8711e635a6687e6a3f8d2 Mon Sep 17 00:00:00 2001 From: ainetx Date: Mon, 6 Jul 2026 14:24:23 +0300 Subject: [PATCH 032/106] docs(v2): typed Worker.dependencies with required/mode; deprecate dependencies_mode; circular dep hard block Signed-off-by: ainetx Co-authored-by: Constructor Studio <291158726+constructor-studio[bot]@users.noreply.github.com> Studio-Generated-By: Constructor Studio Studio-Source-Repo: https://github.com/constructorfabric/studio Constructor-Fabric: https://github.com/constructorfabric Studio-Version: skill=1.5.9, cli=1.5.10.dev73 Studio-Workflows: cf-brainstorm --- .../studio-v2-domain-model-2026-07-03/state.md | 3 ++- v2/docs/domain-model.md | 14 ++++++++++---- 2 files changed, 12 insertions(+), 5 deletions(-) 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 index 06b9b1ff..91510809 100644 --- 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 @@ -2,7 +2,7 @@ **Session ID:** studio-v2-domain-model-2026-07-03 **Date:** 2026-07-03 -**Rounds:** 38 +**Rounds:** 39 **Mode:** inline / normal **SIMPLE_MODE:** normal **BRAINSTORM_MAX_ROUNDS:** 10 (exceeded — continued by user choice) @@ -80,6 +80,7 @@ | 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 | --- diff --git a/v2/docs/domain-model.md b/v2/docs/domain-model.md index c765d05e..287331b2 100644 --- a/v2/docs/domain-model.md +++ b/v2/docs/domain-model.md @@ -514,7 +514,15 @@ Worker { id: GTS Type Identifier (gts.cf.studio.core.worker.v1~...) input: Contract (GTS Type Schema) output: Contract (GTS Type Schema) - dependencies: Worker[] (static list — security boundary) + dependencies: [ // static list — security boundary + { + workerId: ref → Worker + required: boolean // default: true; false = optional call + mode: sync | async // default: sync + } + ] + // 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 @@ -608,9 +616,7 @@ WorkerImplementation { // script: { entrypoint, language, ... } // hybrid: { steps[] } } - dependencies_mode: { - // workerId → { mode: sync | async } - } + // dependencies_mode: deprecated — mode is now in Worker.dependencies[].mode checkpoint: { enabled: boolean ttl: duration From c1f3704e30799ea7b018cc7cf778510c56edea76 Mon Sep 17 00:00:00 2001 From: ainetx Date: Mon, 6 Jul 2026 14:58:35 +0300 Subject: [PATCH 033/106] docs(v2): add EventSubscription (outbound webhooks/event-bus) with CloudEvents format Signed-off-by: ainetx Co-authored-by: Constructor Studio <291158726+constructor-studio[bot]@users.noreply.github.com> Studio-Generated-By: Constructor Studio Studio-Source-Repo: https://github.com/constructorfabric/studio Constructor-Fabric: https://github.com/constructorfabric Studio-Version: skill=1.5.9, cli=1.5.10.dev73 Studio-Workflows: cf-brainstorm --- v2/docs/domain-model.md | 51 ++++++++++++++++++++++++++++++++++++++++- 1 file changed, 50 insertions(+), 1 deletion(-) diff --git a/v2/docs/domain-model.md b/v2/docs/domain-model.md index 287331b2..fe8f9467 100644 --- a/v2/docs/domain-model.md +++ b/v2/docs/domain-model.md @@ -409,6 +409,7 @@ 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~ ``` ### 2.4 Vendor (Kit) Extensions @@ -1653,6 +1654,9 @@ 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): @@ -3084,7 +3088,52 @@ cf.studio.core.evidence.v1~ // structured proof of action/validatio --- -### Domain 20 — Worker Interactions +### 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 | raw // default: cloudevents + state: active | paused | failed + retryPolicy: { + maxRetries: int // default: 3 + backoff: linear | exponential + } +} +``` + +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 From 195bce15fd973975f644c3c281ff942f3deca35c Mon Sep 17 00:00:00 2001 From: ainetx Date: Mon, 6 Jul 2026 15:22:39 +0300 Subject: [PATCH 034/106] docs(v2): add Approval chain fields (sequential, parallel, delegation) Signed-off-by: ainetx Co-authored-by: Constructor Studio <291158726+constructor-studio[bot]@users.noreply.github.com> Studio-Generated-By: Constructor Studio Studio-Source-Repo: https://github.com/constructorfabric/studio Constructor-Fabric: https://github.com/constructorfabric Studio-Version: skill=1.5.9, cli=1.5.10.dev73 Studio-Workflows: cf-brainstorm --- .../studio-v2-domain-model-2026-07-03/state.md | 4 +++- v2/docs/domain-model.md | 10 ++++++++++ 2 files changed, 13 insertions(+), 1 deletion(-) 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 index 91510809..5120a10f 100644 --- 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 @@ -2,7 +2,7 @@ **Session ID:** studio-v2-domain-model-2026-07-03 **Date:** 2026-07-03 -**Rounds:** 39 +**Rounds:** 41 **Mode:** inline / normal **SIMPLE_MODE:** normal **BRAINSTORM_MAX_ROUNDS:** 10 (exceeded — continued by user choice) @@ -81,6 +81,8 @@ | 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 | --- diff --git a/v2/docs/domain-model.md b/v2/docs/domain-model.md index fe8f9467..5aa2191b 100644 --- a/v2/docs/domain-model.md +++ b/v2/docs/domain-model.md @@ -2002,6 +2002,16 @@ Approval extends Object { 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 } ``` From 5fc951f8ef586afbcb7b3c1428a5646a01bf8ac3 Mon Sep 17 00:00:00 2001 From: ainetx Date: Mon, 6 Jul 2026 15:28:22 +0300 Subject: [PATCH 035/106] docs(v2): add KitInstallation Object, Kit semver convention, changelog requirement for MAJOR Signed-off-by: ainetx Co-authored-by: Constructor Studio <291158726+constructor-studio[bot]@users.noreply.github.com> Studio-Generated-By: Constructor Studio Studio-Source-Repo: https://github.com/constructorfabric/studio Constructor-Fabric: https://github.com/constructorfabric Studio-Version: skill=1.5.9, cli=1.5.10.dev73 Studio-Workflows: cf-brainstorm --- .../state.md | 3 +- v2/docs/domain-model.md | 40 +++++++++++++++++++ 2 files changed, 42 insertions(+), 1 deletion(-) 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 index 5120a10f..d5db1e70 100644 --- 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 @@ -2,7 +2,7 @@ **Session ID:** studio-v2-domain-model-2026-07-03 **Date:** 2026-07-03 -**Rounds:** 41 +**Rounds:** 42 **Mode:** inline / normal **SIMPLE_MODE:** normal **BRAINSTORM_MAX_ROUNDS:** 10 (exceeded — continued by user choice) @@ -83,6 +83,7 @@ | 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 | --- diff --git a/v2/docs/domain-model.md b/v2/docs/domain-model.md index 5aa2191b..7ea5306f 100644 --- a/v2/docs/domain-model.md +++ b/v2/docs/domain-model.md @@ -410,6 +410,7 @@ 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~ ``` ### 2.4 Vendor (Kit) Extensions @@ -1108,6 +1109,44 @@ flowchart TD - 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 + 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 ``` @@ -1145,6 +1184,7 @@ Kit manifest: ] // 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 ``` `Tenant.allowedKitPatterns` (see §7) acts as a soft governance filter: installing From b169304e6a4f885de97d4aa576d89a367654b8ee Mon Sep 17 00:00:00 2001 From: ainetx Date: Mon, 6 Jul 2026 17:41:51 +0300 Subject: [PATCH 036/106] =?UTF-8?q?docs(v2):=20apply=20challenge=20round?= =?UTF-8?q?=2039-42=20=E2=80=94=20dep=20mode=20in=20WorkerImpl,=20auto=3DP?= =?UTF-8?q?ATCH,=20gts=5Fnative=20format,=20required=20advisory=20for=20ll?= =?UTF-8?q?m?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: ainetx Co-authored-by: Constructor Studio <291158726+constructor-studio[bot]@users.noreply.github.com> Studio-Generated-By: Constructor Studio Studio-Source-Repo: https://github.com/constructorfabric/studio Constructor-Fabric: https://github.com/constructorfabric Studio-Version: skill=1.5.9, cli=1.5.10.dev73 Studio-Workflows: cf-brainstorm --- v2/docs/domain-model.md | 18 ++++++++++++++---- 1 file changed, 14 insertions(+), 4 deletions(-) diff --git a/v2/docs/domain-model.md b/v2/docs/domain-model.md index 7ea5306f..1992fe76 100644 --- a/v2/docs/domain-model.md +++ b/v2/docs/domain-model.md @@ -519,10 +519,12 @@ Worker { dependencies: [ // static list — security boundary { workerId: ref → Worker - required: boolean // default: true; false = optional call - mode: sync | async // default: sync + 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 @@ -618,7 +620,9 @@ WorkerImplementation { // script: { entrypoint, language, ... } // hybrid: { steps[] } } - // dependencies_mode: deprecated — mode is now in Worker.dependencies[].mode + dependencyModes?: map + // per-dependency call mode; default: sync + // overrides Worker.dependencies default without changing Worker schema checkpoint: { enabled: boolean ttl: duration @@ -1133,6 +1137,9 @@ KitInstallation extends Object { 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) @@ -3160,7 +3167,7 @@ EventSubscription extends Object { secret?: ref requiredSettings // HMAC signing secret sinkRef?: string // Gears sink ID (kind: event_bus) } - format: cloudevents | raw // default: cloudevents + format: cloudevents | gts_native // default: cloudevents state: active | paused | failed retryPolicy: { maxRetries: int // default: 3 @@ -3169,6 +3176,9 @@ EventSubscription extends Object { } ``` +// gts_native = raw GTS event JSON without CloudEvents envelope +// (for Tenants already consuming Gears Events Broker directly) + CloudEvents envelope (when format: cloudevents): ```json { From e1904936dc35d142ea60fbd883acbf7392011f36 Mon Sep 17 00:00:00 2001 From: ainetx Date: Mon, 6 Jul 2026 18:00:15 +0300 Subject: [PATCH 037/106] docs(v2): add x-gts-traits.contains_pii annotation and DataErasureRequest Object (GDPR) Signed-off-by: ainetx Co-authored-by: Constructor Studio <291158726+constructor-studio[bot]@users.noreply.github.com> Studio-Generated-By: Constructor Studio Studio-Source-Repo: https://github.com/constructorfabric/studio Constructor-Fabric: https://github.com/constructorfabric Studio-Version: skill=1.5.9, cli=1.5.10.dev73 Studio-Workflows: cf-brainstorm --- .../studio-v2-domain-model-2026-07-03/state.md | 3 ++- v2/docs/domain-model.md | 16 ++++++++++++++++ 2 files changed, 18 insertions(+), 1 deletion(-) 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 index d5db1e70..108f2da6 100644 --- 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 @@ -2,7 +2,7 @@ **Session ID:** studio-v2-domain-model-2026-07-03 **Date:** 2026-07-03 -**Rounds:** 42 +**Rounds:** 43 **Mode:** inline / normal **SIMPLE_MODE:** normal **BRAINSTORM_MAX_ROUNDS:** 10 (exceeded — continued by user choice) @@ -84,6 +84,7 @@ | 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 | --- diff --git a/v2/docs/domain-model.md b/v2/docs/domain-model.md index 1992fe76..03d2335c 100644 --- a/v2/docs/domain-model.md +++ b/v2/docs/domain-model.md @@ -411,6 +411,7 @@ 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 @@ -450,6 +451,18 @@ awareness (`x-gts-state-requires`, `x-gts-state-sets`), platform security } ``` +`x-gts-traits.contains_pii` — marks Object types that carry personally identifiable information: + +```json +"x-gts-traits": { + "contains_pii": true, + "pii_fields": ["assignee", "description", "authorEmail"] +} +``` + +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~", @@ -2982,6 +2995,9 @@ 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, infrastructure cost ``` From cbd8040d3743398d62160b41c98dad374653cdec Mon Sep 17 00:00:00 2001 From: ainetx Date: Mon, 6 Jul 2026 18:02:27 +0300 Subject: [PATCH 038/106] =?UTF-8?q?docs(v2):=20add=20data=5Ferasure=5Fwork?= =?UTF-8?q?er=20to=20=C2=A725;=20fix=20pii=5Ffields=20to=20use=20dot-notat?= =?UTF-8?q?ion=20paths?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: ainetx Co-authored-by: Constructor Studio <291158726+constructor-studio[bot]@users.noreply.github.com> Studio-Generated-By: Constructor Studio Studio-Source-Repo: https://github.com/constructorfabric/studio Constructor-Fabric: https://github.com/constructorfabric Studio-Version: skill=1.5.9, cli=1.5.10.dev73 Studio-Workflows: cf-brainstorm --- v2/docs/domain-model.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/v2/docs/domain-model.md b/v2/docs/domain-model.md index 03d2335c..1d611e1d 100644 --- a/v2/docs/domain-model.md +++ b/v2/docs/domain-model.md @@ -456,7 +456,8 @@ awareness (`x-gts-state-requires`, `x-gts-state-sets`), platform security ```json "x-gts-traits": { "contains_pii": true, - "pii_fields": ["assignee", "description", "authorEmail"] + "pii_fields": ["assignee", "description", "externalRef.externalId", "payload.*"] + // dot-notation paths; wildcard * = all fields within that prefix } ``` @@ -2305,6 +2306,7 @@ metadata.category: platform | `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. | 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. From 2a662a473e04ed3f62a39da9165a0f83a83af271 Mon Sep 17 00:00:00 2001 From: ainetx Date: Mon, 6 Jul 2026 18:13:21 +0300 Subject: [PATCH 039/106] =?UTF-8?q?docs(v2):=20add=20=C2=A726=20Gears=20In?= =?UTF-8?q?tegration=20Reference;=20fix=20Credentials=20Store=20vs=20Setti?= =?UTF-8?q?ngs;=20WorkerRun.trigger?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: ainetx Co-authored-by: Constructor Studio <291158726+constructor-studio[bot]@users.noreply.github.com> Studio-Generated-By: Constructor Studio Studio-Source-Repo: https://github.com/constructorfabric/studio Constructor-Fabric: https://github.com/constructorfabric Studio-Version: skill=1.5.9, cli=1.5.10.dev73 Studio-Workflows: cf-brainstorm --- .../state.md | 3 +- v2/docs/domain-model.md | 62 ++++++++++++++++++- 2 files changed, 61 insertions(+), 4 deletions(-) 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 index 108f2da6..685b453e 100644 --- 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 @@ -2,7 +2,7 @@ **Session ID:** studio-v2-domain-model-2026-07-03 **Date:** 2026-07-03 -**Rounds:** 43 +**Rounds:** 44 **Mode:** inline / normal **SIMPLE_MODE:** normal **BRAINSTORM_MAX_ROUNDS:** 10 (exceeded — continued by user choice) @@ -85,6 +85,7 @@ | 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 | --- diff --git a/v2/docs/domain-model.md b/v2/docs/domain-model.md index 1d611e1d..27646cfd 100644 --- a/v2/docs/domain-model.md +++ b/v2/docs/domain-model.md @@ -787,6 +787,15 @@ WorkerRun extends Object { interactions: WorkerInteraction[] // history of all interactions (immutable once answered) cancelledBy?: ref → User cancelCascade?: boolean // were child WorkerRuns also cancelled + trigger: { // immutable after set; platform sets at creation + kind: scheduled | onEvent | onDemand | chain + // 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) + // chain: sub-Worker call from parent WorkerRun + parentEventId?: string // Gears Event ID (for kind: onEvent) + scheduleName?: string // Gears Jobs Manager schedule name (for kind: scheduled) + } cost?: { promptTokens: int completionTokens: int @@ -1177,7 +1186,7 @@ Kit manifest: - write: [ GTS Type Identifier, ... ] - call: [ GTS Type Identifier, ... ] requiredSettings: - - { key: string, secret: boolean } // credentials stored in Gears Settings + - { key: string, secret: boolean } // secrets stored in Gears Credentials Store ``` - Tenant explicitly approves at installation @@ -1821,7 +1830,8 @@ classDiagram **Core (Gears, pre-installed):** `in_app`, `email`, `webhook` **Vendor Kits** register additional channels. Kit declares `requiredSettings` -for credentials; Tenant fills via Gears Settings Service. No secrets in Kit. +for credentials; Tenant fills via Gears Credentials Store. No secrets in Kit. +// Note: Gears Settings Service = preferences/feature flags (not secrets) --- @@ -1946,7 +1956,8 @@ 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 // reference to OAGW upstream (created at Kit install) + oagwUpstreamRef: string // Gears Outbound API Gateway upstream resource ID + // created at Kit install via Outbound API Interface rateLimit: { requestsPerHour: int burstSize: int @@ -2326,6 +2337,51 @@ Indexing is triggered automatically via `onEvent: object_created / object_update --- +## 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 | Studio Objects stored as Durable Objects (GTS-typed resources) | +| `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 | Studio Approval Object uses Gears Approvals for multi-step chains | +| `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. + +--- + ## Appendix A — Studio v2 Object Type Catalog All types follow the pattern: From 884501399f60a7bf4516739785d29ed7fd658f78 Mon Sep 17 00:00:00 2001 From: ainetx Date: Mon, 6 Jul 2026 18:15:46 +0300 Subject: [PATCH 040/106] =?UTF-8?q?docs(v2):=20apply=20challenge=20round?= =?UTF-8?q?=2044=20=E2=80=94=20soften=20Durable=20Objects=20claim,=20Appro?= =?UTF-8?q?val=20independence,=20remove=20trigger=20chain?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: ainetx Co-authored-by: Constructor Studio <291158726+constructor-studio[bot]@users.noreply.github.com> Studio-Generated-By: Constructor Studio Studio-Source-Repo: https://github.com/constructorfabric/studio Constructor-Fabric: https://github.com/constructorfabric Studio-Version: skill=1.5.9, cli=1.5.10.dev73 Studio-Workflows: cf-brainstorm --- v2/docs/domain-model.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/v2/docs/domain-model.md b/v2/docs/domain-model.md index 27646cfd..420c5347 100644 --- a/v2/docs/domain-model.md +++ b/v2/docs/domain-model.md @@ -788,11 +788,11 @@ WorkerRun extends Object { cancelledBy?: ref → User cancelCascade?: boolean // were child WorkerRuns also cancelled trigger: { // immutable after set; platform sets at creation - kind: scheduled | onEvent | onDemand | chain + 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) - // chain: sub-Worker call from parent WorkerRun + // 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) } @@ -2346,7 +2346,7 @@ maps Studio domain concepts to the Gears they depend on. |---|---|---| | `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 | Studio Objects stored as Durable Objects (GTS-typed resources) | +| `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 | @@ -2357,7 +2357,7 @@ maps Studio domain concepts to the Gears they depend on. | 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 | Studio Approval Object uses Gears Approvals for multi-step chains | +| `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 | From 03aaf089202c141e00327584eb1515128e9346df Mon Sep 17 00:00:00 2001 From: ainetx Date: Mon, 6 Jul 2026 18:18:00 +0300 Subject: [PATCH 041/106] =?UTF-8?q?docs(v2):=20add=20Studio=20as=20MCP=20s?= =?UTF-8?q?erver=20=E2=80=94=20Kit.mcpTools,=20Tenant.mcpSettings?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: ainetx Co-authored-by: Constructor Studio <291158726+constructor-studio[bot]@users.noreply.github.com> Studio-Generated-By: Constructor Studio Studio-Source-Repo: https://github.com/constructorfabric/studio Constructor-Fabric: https://github.com/constructorfabric Studio-Version: skill=1.5.9, cli=1.5.10.dev73 Studio-Workflows: cf-brainstorm --- .../studio-v2-domain-model-2026-07-03/state.md | 3 ++- v2/docs/domain-model.md | 13 +++++++++++++ 2 files changed, 15 insertions(+), 1 deletion(-) 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 index 685b453e..35268793 100644 --- 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 @@ -2,7 +2,7 @@ **Session ID:** studio-v2-domain-model-2026-07-03 **Date:** 2026-07-03 -**Rounds:** 44 +**Rounds:** 45 **Mode:** inline / normal **SIMPLE_MODE:** normal **BRAINSTORM_MAX_ROUNDS:** 10 (exceeded — continued by user choice) @@ -86,6 +86,7 @@ | 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, serviceAccount } | --- diff --git a/v2/docs/domain-model.md b/v2/docs/domain-model.md index 420c5347..fbadd2fc 100644 --- a/v2/docs/domain-model.md +++ b/v2/docs/domain-model.md @@ -961,6 +961,11 @@ Tenant { 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 + serviceAccount: ref → User // MCP clients authenticate as this User (scoped Role) + } } ``` @@ -1215,6 +1220,14 @@ Kit manifest: 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 From 4f48293710aaf695402d00ab125117858bbcf951 Mon Sep 17 00:00:00 2001 From: ainetx Date: Mon, 6 Jul 2026 18:19:49 +0300 Subject: [PATCH 042/106] docs(v2): consolidate Flow steps[].required; MCP mcpRole instead of serviceAccount Signed-off-by: ainetx Co-authored-by: Constructor Studio <291158726+constructor-studio[bot]@users.noreply.github.com> Studio-Generated-By: Constructor Studio Studio-Source-Repo: https://github.com/constructorfabric/studio Constructor-Fabric: https://github.com/constructorfabric Studio-Version: skill=1.5.9, cli=1.5.10.dev73 Studio-Workflows: cf-brainstorm --- v2/docs/domain-model.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/v2/docs/domain-model.md b/v2/docs/domain-model.md index fbadd2fc..c8467cba 100644 --- a/v2/docs/domain-model.md +++ b/v2/docs/domain-model.md @@ -896,16 +896,18 @@ Flow extends Worker { 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[] // ordered list = planned checklist items + // mandatorySteps: Worker[] — deprecated; derived from steps.filter(required == true) stepDependencies?: map // explicit deps for UI dependency graph; - // if absent: steps assumed sequential per mandatorySteps order + // if absent: steps assumed sequential per steps[] order allowedNextSteps: map conditionalRoutes?: [ { @@ -964,7 +966,8 @@ Tenant { mcpSettings?: { enabled: boolean // default: false; MCP access disabled unless explicitly enabled allowedKits?: string[] // null = all installed Kits with mcpTools; whitelist otherwise - serviceAccount: ref → User // MCP clients authenticate as this User (scoped Role) + mcpRole: ref → Role // MCP clients authenticate with permissions of this Role only + // Role survives DataErasureRequest; avoids full User identity } } ``` From 79b22382e92161d80ea4f313a4a7011e0c58ddf5 Mon Sep 17 00:00:00 2001 From: ainetx Date: Mon, 6 Jul 2026 18:28:26 +0300 Subject: [PATCH 043/106] docs(v2): add BenchmarkSample Object and Tenant.worldModelParticipation for World Model Signed-off-by: ainetx Co-authored-by: Constructor Studio <291158726+constructor-studio[bot]@users.noreply.github.com> Studio-Generated-By: Constructor Studio Studio-Source-Repo: https://github.com/constructorfabric/studio Constructor-Fabric: https://github.com/constructorfabric Studio-Version: skill=1.5.9, cli=1.5.10.dev73 Studio-Workflows: cf-brainstorm --- .../state.md | 5 +-- v2/docs/domain-model.md | 33 +++++++++++++++++++ 2 files changed, 36 insertions(+), 2 deletions(-) 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 index 35268793..635b8ca6 100644 --- 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 @@ -2,7 +2,7 @@ **Session ID:** studio-v2-domain-model-2026-07-03 **Date:** 2026-07-03 -**Rounds:** 45 +**Rounds:** 46 **Mode:** inline / normal **SIMPLE_MODE:** normal **BRAINSTORM_MAX_ROUNDS:** 10 (exceeded — continued by user choice) @@ -86,7 +86,8 @@ | 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, serviceAccount } | +| 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 | --- diff --git a/v2/docs/domain-model.md b/v2/docs/domain-model.md index c8467cba..8961d9aa 100644 --- a/v2/docs/domain-model.md +++ b/v2/docs/domain-model.md @@ -969,9 +969,40 @@ Tenant { mcpRole: ref → Role // MCP clients authenticate with permissions of this Role only // Role survives DataErasureRequest; avoids full User identity } + 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. @@ -3201,6 +3232,8 @@ 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) ``` From 3f9fb81561b036b0b15e1e858a3b7cee7cd649b9 Mon Sep 17 00:00:00 2001 From: ainetx Date: Mon, 6 Jul 2026 18:31:03 +0300 Subject: [PATCH 044/106] docs(v2): add CostReport schema, Tenant.aiCostBudget, WorkerRun.costAttributedTo Signed-off-by: ainetx Co-authored-by: Constructor Studio <291158726+constructor-studio[bot]@users.noreply.github.com> Studio-Generated-By: Constructor Studio Studio-Source-Repo: https://github.com/constructorfabric/studio Constructor-Fabric: https://github.com/constructorfabric Studio-Version: skill=1.5.9, cli=1.5.10.dev73 Studio-Workflows: cf-brainstorm --- .../state.md | 3 +- v2/docs/domain-model.md | 38 ++++++++++++++++++- 2 files changed, 39 insertions(+), 2 deletions(-) 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 index 635b8ca6..e49c379f 100644 --- 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 @@ -2,7 +2,7 @@ **Session ID:** studio-v2-domain-model-2026-07-03 **Date:** 2026-07-03 -**Rounds:** 46 +**Rounds:** 47 **Mode:** inline / normal **SIMPLE_MODE:** normal **BRAINSTORM_MAX_ROUNDS:** 10 (exceeded — continued by user choice) @@ -88,6 +88,7 @@ | 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 | --- diff --git a/v2/docs/domain-model.md b/v2/docs/domain-model.md index 8961d9aa..120e4606 100644 --- a/v2/docs/domain-model.md +++ b/v2/docs/domain-model.md @@ -787,6 +787,11 @@ WorkerRun extends Object { 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 + flowRunId?: ref → FlowRun // enables per-Flow cost aggregation + } trigger: { // immutable after set; platform sets at creation kind: scheduled | onEvent | onDemand // scheduled: Gears Jobs Manager created this run from Worker.defaultSchedule @@ -969,6 +974,11 @@ Tenant { 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 @@ -3103,7 +3113,33 @@ 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, infrastructure cost +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 From 9e3301b6223dc4a1e9e69f085c52b46a9b1b98ab Mon Sep 17 00:00:00 2001 From: ainetx Date: Mon, 6 Jul 2026 18:34:38 +0300 Subject: [PATCH 045/106] docs(v2): add TraceabilityReport Object with coverage metrics; typed output for traceability_analysis Signed-off-by: ainetx Co-authored-by: Constructor Studio <291158726+constructor-studio[bot]@users.noreply.github.com> Studio-Generated-By: Constructor Studio Studio-Source-Repo: https://github.com/constructorfabric/studio Constructor-Fabric: https://github.com/constructorfabric Studio-Version: skill=1.5.9, cli=1.5.10.dev73 Studio-Workflows: cf-brainstorm --- .../state.md | 3 +- v2/docs/domain-model.md | 46 ++++++++++++++++++- 2 files changed, 47 insertions(+), 2 deletions(-) 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 index e49c379f..c9157144 100644 --- 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 @@ -2,7 +2,7 @@ **Session ID:** studio-v2-domain-model-2026-07-03 **Date:** 2026-07-03 -**Rounds:** 47 +**Rounds:** 48 **Mode:** inline / normal **SIMPLE_MODE:** normal **BRAINSTORM_MAX_ROUNDS:** 10 (exceeded — continued by user choice) @@ -89,6 +89,7 @@ | 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 | --- diff --git a/v2/docs/domain-model.md b/v2/docs/domain-model.md index 120e4606..4969f05f 100644 --- a/v2/docs/domain-model.md +++ b/v2/docs/domain-model.md @@ -2167,7 +2167,7 @@ Approval extends Object { | Name | Runtime | Profile | Input Objects | |---|---|---|---| | `gap_analysis` | hybrid | scheduled | requirement, task, test_case, pull_request | -| `traceability_analysis` | hybrid | scheduled | requirement, design, task, pull_request, test_case | +| `traceability_analysis` | hybrid | scheduled | requirement, design, task, pull_request, test_case → TraceabilityReport + Recommendation[] | | `contradiction_detection` | llm | on_demand | document[] (any two or more) | | `bloat_detection` | hybrid | on_demand | requirement[], task[] | | `stale_artifact_detection` | script | realtime | Object (wildcard — any type) | @@ -3304,6 +3304,50 @@ cf.studio.core.evidence.v1~ // structured proof of action/validatio --- +### 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 ``` From 6dca9995b0c097be38ef889710932beab06162b5 Mon Sep 17 00:00:00 2001 From: ainetx Date: Mon, 6 Jul 2026 18:36:58 +0300 Subject: [PATCH 046/106] =?UTF-8?q?docs(v2):=20add=20Output=20column=20to?= =?UTF-8?q?=20=C2=A722.1=20Analyzer=20table;=20document=20stale=5Fartifact?= =?UTF-8?q?=5Fdetection=20write=20exception?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: ainetx Co-authored-by: Constructor Studio <291158726+constructor-studio[bot]@users.noreply.github.com> Studio-Generated-By: Constructor Studio Studio-Source-Repo: https://github.com/constructorfabric/studio Constructor-Fabric: https://github.com/constructorfabric Studio-Version: skill=1.5.9, cli=1.5.10.dev73 Studio-Workflows: cf-brainstorm --- .../state.md | 3 +- v2/docs/domain-model.md | 30 ++++++++++--------- 2 files changed, 18 insertions(+), 15 deletions(-) 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 index c9157144..58d7ae33 100644 --- 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 @@ -2,7 +2,7 @@ **Session ID:** studio-v2-domain-model-2026-07-03 **Date:** 2026-07-03 -**Rounds:** 48 +**Rounds:** 49 **Mode:** inline / normal **SIMPLE_MODE:** normal **BRAINSTORM_MAX_ROUNDS:** 10 (exceeded — continued by user choice) @@ -90,6 +90,7 @@ | 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) | --- diff --git a/v2/docs/domain-model.md b/v2/docs/domain-model.md index 4969f05f..79e76a52 100644 --- a/v2/docs/domain-model.md +++ b/v2/docs/domain-model.md @@ -2164,20 +2164,22 @@ Approval extends Object { ### 22.1 Analyzer Workers (12) — detect gaps → create Recommendations -| Name | Runtime | Profile | Input Objects | -|---|---|---|---| -| `gap_analysis` | hybrid | scheduled | requirement, task, test_case, pull_request | -| `traceability_analysis` | hybrid | scheduled | requirement, design, task, pull_request, test_case → TraceabilityReport + Recommendation[] | -| `contradiction_detection` | llm | on_demand | document[] (any two or more) | -| `bloat_detection` | hybrid | on_demand | requirement[], task[] | -| `stale_artifact_detection` | script | realtime | Object (wildcard — any type) | -| `ownership_gap_analysis` | script | realtime | Object (wildcard — ownerId == null) | -| `duplicate_work_detection` | llm | on_demand | task[], requirement[] | -| `architecture_drift_detection` | hybrid | scheduled | component, component_dependency, design | -| `security_impact_analysis` | hybrid | scheduled | pull_request, vulnerability, security_finding | -| `test_gap_detection` | hybrid | scheduled | requirement, test_case | -| `operations_metrics_analysis` | hybrid | scheduled | slo, sli, metric_definition, alert | -| `ai_cost_efficiency_analysis` | script | scheduled | WorkerRun[], cost_report | +All Analyzers are read-only except `stale_artifact_detection` which also writes `Object.stalenessScore`. + +| 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 (2) — mandatory step sequences From d4c2bd188b2be4b25c2e6ee7ad8d7cb822471ad7 Mon Sep 17 00:00:00 2001 From: ainetx Date: Mon, 6 Jul 2026 18:39:38 +0300 Subject: [PATCH 047/106] docs(v2): add ops Workers (alert_to_incident, triage, rollback); runbook = Flow pattern Signed-off-by: ainetx Co-authored-by: Constructor Studio <291158726+constructor-studio[bot]@users.noreply.github.com> Studio-Generated-By: Constructor Studio Studio-Source-Repo: https://github.com/constructorfabric/studio Constructor-Fabric: https://github.com/constructorfabric Studio-Version: skill=1.5.9, cli=1.5.10.dev73 Studio-Workflows: cf-brainstorm --- .../studio-v2-domain-model-2026-07-03/state.md | 3 ++- v2/docs/domain-model.md | 10 +++++++++- 2 files changed, 11 insertions(+), 2 deletions(-) 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 index 58d7ae33..39e69f09 100644 --- 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 @@ -2,7 +2,7 @@ **Session ID:** studio-v2-domain-model-2026-07-03 **Date:** 2026-07-03 -**Rounds:** 49 +**Rounds:** 50 **Mode:** inline / normal **SIMPLE_MODE:** normal **BRAINSTORM_MAX_ROUNDS:** 10 (exceeded — continued by user choice) @@ -91,6 +91,7 @@ | 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 | --- diff --git a/v2/docs/domain-model.md b/v2/docs/domain-model.md index 79e76a52..395ad05d 100644 --- a/v2/docs/domain-model.md +++ b/v2/docs/domain-model.md @@ -2181,7 +2181,12 @@ All Analyzers are read-only except `stale_artifact_detection` which also writes | `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 (2) — mandatory step sequences +### 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: ``` @@ -2335,6 +2340,9 @@ sufficient permissions and `automationLevel >= approved_automation`. | `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 | +| `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 From 9f31ddc66b827eb839da15f50aa2517c2c581001 Mon Sep 17 00:00:00 2001 From: ainetx Date: Mon, 6 Jul 2026 18:41:42 +0300 Subject: [PATCH 048/106] =?UTF-8?q?docs(v2):=20challenge=20round=2046-50?= =?UTF-8?q?=20=E2=80=94=20requirement.priority,=20alert=20eventTrigger,=20?= =?UTF-8?q?stale=20gate,=20flowRunId=20type=20fix?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: ainetx Co-authored-by: Constructor Studio <291158726+constructor-studio[bot]@users.noreply.github.com> Studio-Generated-By: Constructor Studio Studio-Source-Repo: https://github.com/constructorfabric/studio Constructor-Fabric: https://github.com/constructorfabric Studio-Version: skill=1.5.9, cli=1.5.10.dev73 Studio-Workflows: cf-brainstorm --- v2/docs/domain-model.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/v2/docs/domain-model.md b/v2/docs/domain-model.md index 395ad05d..78556283 100644 --- a/v2/docs/domain-model.md +++ b/v2/docs/domain-model.md @@ -790,7 +790,8 @@ WorkerRun extends Object { costAttributedTo?: { // platform sets at creation from trigger context userId?: ref → User workspaceId?: ref → Workspace - flowRunId?: ref → FlowRun // enables per-Flow cost aggregation + 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 @@ -2340,7 +2341,7 @@ sufficient permissions and `automationLevel >= approved_automation`. | `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 | +| `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 | @@ -2470,7 +2471,8 @@ cf.studio.core.prompt.v1~ // base for all AI prompt artifacts cf.studio.core.prd.v1~ // → document cf.studio.core.epic.v1~ cf.studio.core.user_story.v1~ -cf.studio.core.requirement.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~ From 16d5b13b30f80fe284d62e3b236eb9b8f8d581b1 Mon Sep 17 00:00:00 2001 From: ainetx Date: Tue, 7 Jul 2026 11:14:32 +0300 Subject: [PATCH 049/106] =?UTF-8?q?fix(v2):=20correct=20DO3/D2=20diagrams?= =?UTF-8?q?=20=E2=80=94=20Tenant/User=20extend=20Gears=20RG/AM,=20not=20St?= =?UTF-8?q?udio=20Object?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: ainetx Co-authored-by: Constructor Studio <291158726+constructor-studio[bot]@users.noreply.github.com> Studio-Generated-By: Constructor Studio Studio-Source-Repo: https://github.com/constructorfabric/studio Constructor-Fabric: https://github.com/constructorfabric Studio-Version: skill=1.5.9, cli=1.5.10.dev73 Studio-Workflows: cf-brainstorm --- v2/docs/domain-model.md | 24 +++++++++++++++++------- 1 file changed, 17 insertions(+), 7 deletions(-) diff --git a/v2/docs/domain-model.md b/v2/docs/domain-model.md index 78556283..efce7d3b 100644 --- a/v2/docs/domain-model.md +++ b/v2/docs/domain-model.md @@ -143,6 +143,9 @@ classDiagram ### 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 { @@ -151,8 +154,10 @@ classDiagram ownerId · validationStatus stalenessScore · externalRef } - class Tenant - class User + 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 @@ -163,8 +168,8 @@ classDiagram class WorkerInteraction class Evidence - Object <|-- Tenant - Object <|-- User + GearsRG <|-- Tenant + GearsAM <|-- User Object <|-- Workspace Object <|-- Role Object <|-- WorkerRun @@ -315,14 +320,18 @@ classDiagram createdAt: datetime updatedAt: datetime } - class Tenant + 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 - Object <|-- Tenant + GearsRG <|-- Tenant + GearsAM <|-- User Object <|-- Workspace Object <|-- WorkerRun Object <|-- FlowRun @@ -330,7 +339,8 @@ classDiagram Object <|-- Recommendation ``` -All object types are derived from the base `Object` via GTS chained IDs. +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 From 5320b6515c1323f10a61c2d2852ce6aa4ba772c9 Mon Sep 17 00:00:00 2001 From: ainetx Date: Tue, 7 Jul 2026 13:35:33 +0300 Subject: [PATCH 050/106] =?UTF-8?q?docs(v2):=20add=20GTS=20Type=20ID=20ver?= =?UTF-8?q?sioning=20policy=20=C2=A72.0;=20Worker.deprecatedBy;=20close=20?= =?UTF-8?q?review=20Q-3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: ainetx Co-authored-by: Constructor Studio <291158726+constructor-studio[bot]@users.noreply.github.com> Studio-Generated-By: Constructor Studio Studio-Source-Repo: https://github.com/constructorfabric/studio Constructor-Fabric: https://github.com/constructorfabric Studio-Version: skill=1.5.9, cli=1.5.10.dev73 Studio-Workflows: cf-brainstorm --- v2/docs/domain-model.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/v2/docs/domain-model.md b/v2/docs/domain-model.md index efce7d3b..4c87bc7a 100644 --- a/v2/docs/domain-model.md +++ b/v2/docs/domain-model.md @@ -365,6 +365,22 @@ Outside the graph. Describe rules and configurations, not data. 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: @@ -572,6 +588,8 @@ Worker { } ] // Flow.config.steps[].inputBinding overrides Worker.inputBindings per step + deprecatedBy?: ref → Worker // set on MAJOR contract change; points to successor Worker + // deprecated Workers remain in Registry; old WorkerRuns valid 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 From 319fecee69dc7c4ce08ff91ff0b5add1df3439d7 Mon Sep 17 00:00:00 2001 From: ainetx Date: Tue, 7 Jul 2026 13:42:27 +0300 Subject: [PATCH 051/106] fix(v2): clarify Tenant/User as Gears-extended types in DO1, DO1b, DO3, DO5 diagrams Signed-off-by: ainetx Co-authored-by: Constructor Studio <291158726+constructor-studio[bot]@users.noreply.github.com> Studio-Generated-By: Constructor Studio Studio-Source-Repo: https://github.com/constructorfabric/studio Constructor-Fabric: https://github.com/constructorfabric Studio-Version: skill=1.5.9, cli=1.5.10.dev73 Studio-Workflows: cf-brainstorm --- v2/docs/domain-model.md | 25 ++++++++++++++----------- 1 file changed, 14 insertions(+), 11 deletions(-) diff --git a/v2/docs/domain-model.md b/v2/docs/domain-model.md index 4c87bc7a..1a70e2b8 100644 --- a/v2/docs/domain-model.md +++ b/v2/docs/domain-model.md @@ -28,7 +28,8 @@ flowchart TB end subgraph GRAPH["Object Graph — Runtime Instances"] - O["Object (base)\nTenant · User · Workspace · Role\nWorkerRun · FlowRun · Recommendation · Approval\nValidationSession · Evidence · WorkerInteraction\n…all domain types (task, PR, incident, design, …)"] + O["gts.cf.studio.core.object.v1~ (base)\nWorkspace · Role · WorkerRun · FlowRun\nRecommendation · Approval · ValidationSession\nEvidence · WorkerInteraction\n…all domain types (task, PR, incident, design, …)"] + G2["Gears-extended (NOT Studio Object base)\nTenant (extends Gears RG)\nUser (extends Gears AM)"] end REGISTRY -->|executes / produces| GRAPH @@ -89,14 +90,16 @@ flowchart TD │ OBJECT GRAPH │ │ gts.cf.studio.core.object.v1~ (base) │ │ │ -│ Tenant* Workspace WorkerRun FlowRun │ -│ User* Role Recommendation │ -│ Requirement Task PullRequest Build │ -│ Design Incident IdentityMapping │ -│ PolicyOverride PolicyDelegation SavedAuditQuery │ -│ NotificationRuleOverride NotificationSubscription │ +│ Workspace WorkerRun FlowRun Role │ +│ Requirement Task PullRequest Build │ +│ Design Incident Recommendation │ +│ IdentityMapping PolicyOverride PolicyDelegation │ +│ SavedAuditQuery NotificationRuleOverride NotificationSub │ │ │ -│ * extends Gears base types (AM/RG) │ +├─────────────────────────────────────────────────────────────┤ +│ Gears-extended (NOT gts.cf.studio.core.object.v1~) │ +│ Tenant (gts.cf.core.rg.type.v1~...cf.studio.tenant.v1~) │ +│ User (gts.cf.core.am.user.v1~...cf.studio.user.v1~) │ └─────────────────────────────────────────────────────────────┘ ``` @@ -223,12 +226,12 @@ flowchart LR ```mermaid classDiagram - class Tenant { + class Tenant["Tenant\n(extends Gears RG)"] { automationLevel approvedWorkerCategories deploymentMode } - class User + class User["User\n(extends Gears AM)"] class Role class Policy { rules: Rule[] @@ -1049,7 +1052,7 @@ Isolation enforced via ABAC policies using GTS wildcard patterns. ```mermaid classDiagram - class Tenant { + class Tenant["Tenant\n(extends Gears RG, NOT Studio Object)"] { parentId: ref Tenant? name: string checkpointTTL: duration From c7008e1f498024ea1c490f13da3fe8bbb0540c09 Mon Sep 17 00:00:00 2001 From: ainetx Date: Tue, 7 Jul 2026 13:46:53 +0300 Subject: [PATCH 052/106] fix(v2): move Tenant/User to Gears layer in DO1/DO1b; Worker.deprecation struct with grace period Signed-off-by: ainetx Co-authored-by: Constructor Studio <291158726+constructor-studio[bot]@users.noreply.github.com> Studio-Generated-By: Constructor Studio Studio-Source-Repo: https://github.com/constructorfabric/studio Constructor-Fabric: https://github.com/constructorfabric Studio-Version: skill=1.5.9, cli=1.5.10.dev73 Studio-Workflows: cf-brainstorm --- v2/docs/domain-model.md | 40 +++++++++++++++++++++++++++------------- 1 file changed, 27 insertions(+), 13 deletions(-) diff --git a/v2/docs/domain-model.md b/v2/docs/domain-model.md index 1a70e2b8..ed8bbb99 100644 --- a/v2/docs/domain-model.md +++ b/v2/docs/domain-model.md @@ -20,16 +20,15 @@ These two worlds are connected by execution: a Worker (definition) produces Work ```mermaid flowchart TB subgraph GEARS["Gears Platform — Infrastructure"] - G["Events Broker · Notifications · Account Management\nRBAC/ABAC · OAGW · Models Gateway · Settings"] + 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"] - O["gts.cf.studio.core.object.v1~ (base)\nWorkspace · Role · WorkerRun · FlowRun\nRecommendation · Approval · ValidationSession\nEvidence · WorkerInteraction\n…all domain types (task, PR, incident, design, …)"] - G2["Gears-extended (NOT Studio Object base)\nTenant (extends Gears RG)\nUser (extends Gears AM)"] + 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 @@ -87,19 +86,30 @@ flowchart TD │ executes / produces ▼ ┌─────────────────────────────────────────────────────────────┐ -│ OBJECT GRAPH │ -│ gts.cf.studio.core.object.v1~ (base) │ +│ 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 │ -│ │ -├─────────────────────────────────────────────────────────────┤ -│ Gears-extended (NOT gts.cf.studio.core.object.v1~) │ -│ Tenant (gts.cf.core.rg.type.v1~...cf.studio.tenant.v1~) │ -│ User (gts.cf.core.am.user.v1~...cf.studio.user.v1~) │ └─────────────────────────────────────────────────────────────┘ ``` @@ -591,8 +601,12 @@ Worker { } ] // Flow.config.steps[].inputBinding overrides Worker.inputBindings per step - deprecatedBy?: ref → Worker // set on MAJOR contract change; points to successor Worker - // deprecated Workers remain in Registry; old WorkerRuns valid + 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 From dc25a03a4950204be3c9f86c602be07d15f6e23d Mon Sep 17 00:00:00 2001 From: ainetx Date: Tue, 7 Jul 2026 18:39:50 +0300 Subject: [PATCH 053/106] =?UTF-8?q?docs(v2):=20add=20Object.links[]=20Jira?= =?UTF-8?q?-style=20typed=20graph=20edges;=20LINK=5FKIND=20enum;=20two-lay?= =?UTF-8?q?er=20model=20in=20=C2=A723?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: ainetx Co-authored-by: Constructor Studio <291158726+constructor-studio[bot]@users.noreply.github.com> Studio-Generated-By: Constructor Studio Studio-Source-Repo: https://github.com/constructorfabric/studio Constructor-Fabric: https://github.com/constructorfabric Studio-Version: skill=1.5.9, cli=1.5.10.dev73 Studio-Workflows: cf-brainstorm --- v2/docs/domain-model.md | 41 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 41 insertions(+) diff --git a/v2/docs/domain-model.md b/v2/docs/domain-model.md index ed8bbb99..eb16d48e 100644 --- a/v2/docs/domain-model.md +++ b/v2/docs/domain-model.md @@ -318,7 +318,36 @@ Object { externalUrl: string lastSyncedAt: datetime } + links?: [ // Jira-style typed graph edges + { + targetId: ref → Object // any Object in the graph + targetType: GTS Type ID // for type-safe querying + kind: LINK_KIND // see below; or Kit-custom GTS Type ID string + confidence: direct | inferred // direct = user-declared; inferred = from WorkerRun provenance + createdBy: ref → User? // null when platform-inferred + sourceRunId?: ref → WorkerRun // WorkerRun that produced this link (when inferred) + } + ] } + +// LINK_KIND — core closed set (platform understands semantics for traceability): +// derived_from — B created from A (prd→design, design→feature_spec) +// decomposes_into — A breaks down into B items (design→decomposition, decomp→task) +// implements — A implements requirement/spec B (task implements requirement) +// references — weak link: A uses B as context/input (design references adr) +// incorporates — A merges or extends B (composite design) +// validates — A proves B correct (test_case validates requirement) +// supersedes — A replaces B (design v2 supersedes design v1) +// informs — A provides context for B (adr informs design) +// +// Kit-extensible: use GTS Type ID string for custom kinds +// (e.g. "gts.cf.sdlc.link.kind.v1~cf.mykit.tested_by.v1~") +// Platform stores but ignores custom kinds in traceability computation. +// +// 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 ``` ### D2 — Object Base Hierarchy @@ -2303,6 +2332,18 @@ metadata: { ## 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 all + contextual relationships between any Objects. Used for: prd→design (derived_from), + design→adr (references), design→design (incorporates), etc. + `traceability_analysis` Analyzer traverses `links[]` using core LINK_KINDs. + +2. **Spec-level Contract fields** — explicit refs required by Validator Workers: + `pull_request.conformsToDesign`, `pull_request.implementsRequirements`, + `test_case.verifiesRequirements`. These are NOT in `links[]` — they are + Contract inputs read by `pr_design_validator` and other Validators. + ### D19 — SDLC Traceability Chain ```mermaid From 3ab7250421ec0867d6de1071469b4941168628d0 Mon Sep 17 00:00:00 2001 From: ainetx Date: Tue, 7 Jul 2026 18:41:39 +0300 Subject: [PATCH 054/106] =?UTF-8?q?docs(v2):=20refine=20Object.links=20?= =?UTF-8?q?=E2=80=94=20remove=20confidence=20field;=20restrict=20to=20non-?= =?UTF-8?q?execution-record=20Objects?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: ainetx Co-authored-by: Constructor Studio <291158726+constructor-studio[bot]@users.noreply.github.com> Studio-Generated-By: Constructor Studio Studio-Source-Repo: https://github.com/constructorfabric/studio Constructor-Fabric: https://github.com/constructorfabric Studio-Version: skill=1.5.9, cli=1.5.10.dev73 Studio-Workflows: cf-brainstorm --- v2/docs/domain-model.md | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/v2/docs/domain-model.md b/v2/docs/domain-model.md index eb16d48e..39ce890f 100644 --- a/v2/docs/domain-model.md +++ b/v2/docs/domain-model.md @@ -319,13 +319,16 @@ Object { lastSyncedAt: datetime } 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 - targetType: GTS Type ID // for type-safe querying - kind: LINK_KIND // see below; or Kit-custom GTS Type ID string - confidence: direct | inferred // direct = user-declared; inferred = from WorkerRun provenance - createdBy: ref → User? // null when platform-inferred - sourceRunId?: ref → WorkerRun // WorkerRun that produced this link (when inferred) + targetId: ref → Object // any Object in the graph + targetType: GTS Type ID // for type-safe querying + kind: LINK_KIND // see below; or Kit-custom GTS Type ID string + // 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 } ] } From d6b3f3340a5ce3d99eb350b58003f57f3835eb9c Mon Sep 17 00:00:00 2001 From: ainetx Date: Tue, 7 Jul 2026 18:44:51 +0300 Subject: [PATCH 055/106] =?UTF-8?q?docs(v2):=20LINK=5FKIND=20as=20GTS=20Ty?= =?UTF-8?q?pe=20IDs;=20add=20gts.cf.studio.link.kind.v1~=20base=20type=20t?= =?UTF-8?q?o=20=C2=A72.1?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: ainetx Co-authored-by: Constructor Studio <291158726+constructor-studio[bot]@users.noreply.github.com> Studio-Generated-By: Constructor Studio Studio-Source-Repo: https://github.com/constructorfabric/studio Constructor-Fabric: https://github.com/constructorfabric Studio-Version: skill=1.5.9, cli=1.5.10.dev73 Studio-Workflows: cf-brainstorm --- v2/docs/domain-model.md | 30 +++++++++++++++++------------- 1 file changed, 17 insertions(+), 13 deletions(-) diff --git a/v2/docs/domain-model.md b/v2/docs/domain-model.md index 39ce890f..b1188783 100644 --- a/v2/docs/domain-model.md +++ b/v2/docs/domain-model.md @@ -325,7 +325,10 @@ Object { { targetId: ref → Object // any Object in the graph targetType: GTS Type ID // for type-safe querying - kind: LINK_KIND // see below; or Kit-custom GTS Type ID string + 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 @@ -333,19 +336,19 @@ Object { ] } -// LINK_KIND — core closed set (platform understands semantics for traceability): -// derived_from — B created from A (prd→design, design→feature_spec) -// decomposes_into — A breaks down into B items (design→decomposition, decomp→task) -// implements — A implements requirement/spec B (task implements requirement) -// references — weak link: A uses B as context/input (design references adr) -// incorporates — A merges or extends B (composite design) -// validates — A proves B correct (test_case validates requirement) -// supersedes — A replaces B (design v2 supersedes design v1) -// informs — A provides context for B (adr informs design) +// 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: use GTS Type ID string for custom kinds -// (e.g. "gts.cf.sdlc.link.kind.v1~cf.mykit.tested_by.v1~") -// Platform stores but ignores custom kinds in traceability computation. +// 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. // // Two-layer model: // Object.links[] = flexible, user- and platform-declared contextual links @@ -440,6 +443,7 @@ gts.cf.studio.core.worker.v1~cf.studio.core.flow.v1~ 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**: From 5f6089769b9293fbf829c40e40457b6926769455 Mon Sep 17 00:00:00 2001 From: ainetx Date: Tue, 7 Jul 2026 20:14:15 +0300 Subject: [PATCH 056/106] docs(v2): add Object.concurrentEditors (visibility) and Object.writeLock (optional exclusive) Signed-off-by: ainetx Co-authored-by: Constructor Studio <291158726+constructor-studio[bot]@users.noreply.github.com> Studio-Generated-By: Constructor Studio Studio-Source-Repo: https://github.com/constructorfabric/studio Constructor-Fabric: https://github.com/constructorfabric Studio-Version: skill=1.5.9, cli=1.5.10.dev73 Studio-Workflows: cf-brainstorm --- v2/docs/domain-model.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/v2/docs/domain-model.md b/v2/docs/domain-model.md index b1188783..db93b6e2 100644 --- a/v2/docs/domain-model.md +++ b/v2/docs/domain-model.md @@ -318,6 +318,23 @@ Object { externalUrl: string lastSyncedAt: datetime } + concurrentEditors?: [ // "you are not alone" — visibility of concurrent access + { + agentId: ref → WorkerRun | ref → User + 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 → WorkerRun | ref → 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, From 1b61d4f8b57e20c42c6efecdccfa2f703356c1cd Mon Sep 17 00:00:00 2001 From: ainetx Date: Tue, 7 Jul 2026 20:15:50 +0300 Subject: [PATCH 057/106] docs(v2): fix concurrentEditors union ref; add scope note (not for execution records) Signed-off-by: ainetx Co-authored-by: Constructor Studio <291158726+constructor-studio[bot]@users.noreply.github.com> Studio-Generated-By: Constructor Studio Studio-Source-Repo: https://github.com/constructorfabric/studio Constructor-Fabric: https://github.com/constructorfabric Studio-Version: skill=1.5.9, cli=1.5.10.dev73 Studio-Workflows: cf-brainstorm --- v2/docs/domain-model.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/v2/docs/domain-model.md b/v2/docs/domain-model.md index db93b6e2..ca2c83e4 100644 --- a/v2/docs/domain-model.md +++ b/v2/docs/domain-model.md @@ -318,9 +318,12 @@ Object { externalUrl: string lastSyncedAt: datetime } + // 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 → WorkerRun | ref → User + 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 @@ -329,7 +332,8 @@ Object { // 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 → WorkerRun | ref → User + 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 From 7ac39faefb553ae2675e6f558429f4632e06e6ad Mon Sep 17 00:00:00 2001 From: ainetx Date: Tue, 7 Jul 2026 20:22:10 +0300 Subject: [PATCH 058/106] docs(v2): add Object.createdByRunId and lastModifiedByRunId for provenance and cost attribution Signed-off-by: ainetx Co-authored-by: Constructor Studio <291158726+constructor-studio[bot]@users.noreply.github.com> Studio-Generated-By: Constructor Studio Studio-Source-Repo: https://github.com/constructorfabric/studio Constructor-Fabric: https://github.com/constructorfabric Studio-Version: skill=1.5.9, cli=1.5.10.dev73 Studio-Workflows: cf-brainstorm --- v2/docs/domain-model.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/v2/docs/domain-model.md b/v2/docs/domain-model.md index ca2c83e4..7d1d63ec 100644 --- a/v2/docs/domain-model.md +++ b/v2/docs/domain-model.md @@ -318,6 +318,10 @@ Object { externalUrl: string lastSyncedAt: datetime } + createdByRunId?: ref → WorkerRun // WorkerRun that created this Object; null if user-created + lastModifiedByRunId?: ref → WorkerRun // WorkerRun that last modified; null if user-modified + // Together with createdAt/updatedAt: full provenance chain + // Object → WorkerRun.cost → WorkerRun.costAttributedTo → User/Flow (cost attribution) // 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 From 23d21a4bee1c1cd7867d4b8813bccadf6241e80d Mon Sep 17 00:00:00 2001 From: ainetx Date: Tue, 7 Jul 2026 20:25:22 +0300 Subject: [PATCH 059/106] docs(v2): add x-gts-traits.capabilities opt-in; clarify provenance vs semantic links Signed-off-by: ainetx Co-authored-by: Constructor Studio <291158726+constructor-studio[bot]@users.noreply.github.com> Studio-Generated-By: Constructor Studio Studio-Source-Repo: https://github.com/constructorfabric/studio Constructor-Fabric: https://github.com/constructorfabric Studio-Version: skill=1.5.9, cli=1.5.10.dev73 Studio-Workflows: cf-brainstorm --- v2/docs/domain-model.md | 26 ++++++++++++++++++++++++-- 1 file changed, 24 insertions(+), 2 deletions(-) diff --git a/v2/docs/domain-model.md b/v2/docs/domain-model.md index 7d1d63ec..5219612d 100644 --- a/v2/docs/domain-model.md +++ b/v2/docs/domain-model.md @@ -318,10 +318,19 @@ Object { externalUrl: string lastSyncedAt: datetime } + // --- 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 - // Together with createdAt/updatedAt: full provenance chain - // Object → WorkerRun.cost → WorkerRun.costAttributedTo → User/Flow (cost attribution) + // 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 + // Execution records (WorkerRun, Evidence, etc.) and infra types declare no capabilities. // 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 @@ -539,6 +548,19 @@ required fields use the standard `required` array, not a custom annotation. awareness (`x-gts-state-requires`, `x-gts-state-sets`), platform security (`x-gts-source: platform | never-user`), traits + indexes (`x-gts-traits`). +`x-gts-traits.capabilities` — opt-in Object capabilities declaration: + +```json +"x-gts-traits": { + "capabilities": ["linkable", "tracked"] +} +``` + +- `linkable` — Object supports `links[]`, `concurrentEditors`, `writeLock` (content Objects: design, requirement, task, etc.) +- `tracked` — Object supports `createdByRunId`, `lastModifiedByRunId` (all mutable content Objects) +- Execution records (WorkerRun, Evidence, etc.) and infra types declare no capabilities. +- Platform uses capabilities to apply appropriate behaviors and validations. + `x-gts-traits.indexes` — hint to persistence layer which fields to index: ```json From ceb7e9eabb060b12d4be0aee957f6aa6e98541e5 Mon Sep 17 00:00:00 2001 From: ainetx Date: Tue, 7 Jul 2026 20:28:27 +0300 Subject: [PATCH 060/106] docs(v2): add versioned capability; superseded state; dual versioning strategy for SDLC vs operational Signed-off-by: ainetx Co-authored-by: Constructor Studio <291158726+constructor-studio[bot]@users.noreply.github.com> Studio-Generated-By: Constructor Studio Studio-Source-Repo: https://github.com/constructorfabric/studio Constructor-Fabric: https://github.com/constructorfabric Studio-Version: skill=1.5.9, cli=1.5.10.dev73 Studio-Workflows: cf-brainstorm --- v2/docs/domain-model.md | 22 ++++++++++++++++++---- 1 file changed, 18 insertions(+), 4 deletions(-) diff --git a/v2/docs/domain-model.md b/v2/docs/domain-model.md index 5219612d..9b8b0c63 100644 --- a/v2/docs/domain-model.md +++ b/v2/docs/domain-model.md @@ -330,6 +330,7 @@ Object { // 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. // NOT applicable to execution records (WorkerRun, Evidence, ValidationSession, // WorkerInteraction, FlowRun) — they are immutable or have specialized lifecycle @@ -556,10 +557,23 @@ awareness (`x-gts-state-requires`, `x-gts-state-sets`), platform security } ``` -- `linkable` — Object supports `links[]`, `concurrentEditors`, `writeLock` (content Objects: design, requirement, task, etc.) -- `tracked` — Object supports `createdByRunId`, `lastModifiedByRunId` (all mutable content Objects) -- Execution records (WorkerRun, Evidence, etc.) and infra types declare no capabilities. -- Platform uses capabilities to apply appropriate behaviors and validations. +- `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, feature_spec, adr. +- 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: From a045b609f7c2380ff26f916d92da85ba716957e4 Mon Sep 17 00:00:00 2001 From: ainetx Date: Tue, 7 Jul 2026 20:30:17 +0300 Subject: [PATCH 061/106] docs(v2): add decomposition to versioned types; auto-transition on supersedes; Analyzer chain awareness Signed-off-by: ainetx Co-authored-by: Constructor Studio <291158726+constructor-studio[bot]@users.noreply.github.com> Studio-Generated-By: Constructor Studio Studio-Source-Repo: https://github.com/constructorfabric/studio Constructor-Fabric: https://github.com/constructorfabric Studio-Version: skill=1.5.9, cli=1.5.10.dev73 Studio-Workflows: cf-brainstorm --- v2/docs/domain-model.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/v2/docs/domain-model.md b/v2/docs/domain-model.md index 9b8b0c63..6675a9ed 100644 --- a/v2/docs/domain-model.md +++ b/v2/docs/domain-model.md @@ -563,7 +563,9 @@ awareness (`x-gts-state-requires`, `x-gts-state-sets`), platform security 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, feature_spec, adr. + 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. @@ -2309,6 +2311,11 @@ Approval extends Object { 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[] | From f9821dbb0221473872709e35ec0b175a024dbc73 Mon Sep 17 00:00:00 2001 From: ainetx Date: Wed, 8 Jul 2026 10:04:56 +0300 Subject: [PATCH 062/106] =?UTF-8?q?docs(v2):=20add=20pre-built=20ABAC=20co?= =?UTF-8?q?ndition=20Workers=20to=20=C2=A725;=20allowedFields=20placeholde?= =?UTF-8?q?r=20in=20Policy.rules?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: ainetx Co-authored-by: Constructor Studio <291158726+constructor-studio[bot]@users.noreply.github.com> Studio-Generated-By: Constructor Studio Studio-Source-Repo: https://github.com/constructorfabric/studio Constructor-Fabric: https://github.com/constructorfabric Studio-Version: skill=1.5.9, cli=1.5.10.dev73 Studio-Workflows: cf-brainstorm --- v2/docs/domain-model.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/v2/docs/domain-model.md b/v2/docs/domain-model.md index 6675a9ed..f8521b0b 100644 --- a/v2/docs/domain-model.md +++ b/v2/docs/domain-model.md @@ -1609,7 +1609,11 @@ Policy (registry) { 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 + allowedFields?: string[] // Phase 3: field-level restriction (dot-notation) + // null = all fields accessible (default, Phase 1-2) } ] } @@ -2547,6 +2551,9 @@ metadata.category: platform | `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: `allowed = object.assigneeId == principal.id OR object.ownerId == principal.id`. Standard building block for Policy.rules.condition. | +| `is_workspace_member_worker` | script | on_demand | ABAC condition: `allowed = principal is member of object.workspaceId`. Workspace-scoped access control. | +| `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. From 8b597f0593d20ea49aa8ed1b462cfbf405dd2a96 Mon Sep 17 00:00:00 2001 From: ainetx Date: Wed, 8 Jul 2026 10:10:44 +0300 Subject: [PATCH 063/106] docs(v2): add Object.workspaceId; remove links.targetType; remove allowedFields placeholder Signed-off-by: ainetx Co-authored-by: Constructor Studio <291158726+constructor-studio[bot]@users.noreply.github.com> Studio-Generated-By: Constructor Studio Studio-Source-Repo: https://github.com/constructorfabric/studio Constructor-Fabric: https://github.com/constructorfabric Studio-Version: skill=1.5.9, cli=1.5.10.dev73 Studio-Workflows: cf-brainstorm --- v2/docs/domain-model.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/v2/docs/domain-model.md b/v2/docs/domain-model.md index f8521b0b..0690d6ac 100644 --- a/v2/docs/domain-model.md +++ b/v2/docs/domain-model.md @@ -332,6 +332,8 @@ Object { // "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 @@ -358,8 +360,7 @@ Object { // WorkerRun, Evidence, ValidationSession, // WorkerInteraction, FlowRun use specialized refs { - targetId: ref → Object // any Object in the graph - targetType: GTS Type ID // for type-safe querying + 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 @@ -1612,8 +1613,7 @@ Policy (registry) { // pre-built: is_assigned_to_principal_worker, // is_workspace_member_worker, is_object_owner_worker conditionCache: { ttl: duration } // default: 60s - allowedFields?: string[] // Phase 3: field-level restriction (dot-notation) - // null = all fields accessible (default, Phase 1-2) + // Phase 3 TODO: allowedFields?: string[] — field-level restriction (not yet implemented) } ] } From f9a8dd1662074b98c9f759d39b05fad2607554cf Mon Sep 17 00:00:00 2001 From: ainetx Date: Wed, 8 Jul 2026 10:16:01 +0300 Subject: [PATCH 064/106] =?UTF-8?q?docs(v2):=20add=20graph=20traversal=20A?= =?UTF-8?q?PI=20note=20to=20=C2=A71.1;=20mixed=20traversal=20pattern=20in?= =?UTF-8?q?=20=C2=A723?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: ainetx Co-authored-by: Constructor Studio <291158726+constructor-studio[bot]@users.noreply.github.com> Studio-Generated-By: Constructor Studio Studio-Source-Repo: https://github.com/constructorfabric/studio Constructor-Fabric: https://github.com/constructorfabric Studio-Version: skill=1.5.9, cli=1.5.10.dev73 Studio-Workflows: cf-brainstorm --- v2/docs/domain-model.md | 28 ++++++++++++++++++++++------ 1 file changed, 22 insertions(+), 6 deletions(-) diff --git a/v2/docs/domain-model.md b/v2/docs/domain-model.md index 0690d6ac..9cc9b71d 100644 --- a/v2/docs/domain-model.md +++ b/v2/docs/domain-model.md @@ -390,6 +390,12 @@ Object { // 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 @@ -2413,15 +2419,25 @@ metadata: { Studio uses a **two-layer link model**: -1. **`Object.links[]`** — generic Jira-style typed graph edges (see §1.1) for all - contextual relationships between any Objects. Used for: prd→design (derived_from), - design→adr (references), design→design (incorporates), etc. - `traceability_analysis` Analyzer traverses `links[]` using core LINK_KINDs. +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`. These are NOT in `links[]` — they are - Contract inputs read by `pr_design_validator` and other Validators. + `test_case.verifiesRequirements`. Contract inputs — NOT in `links[]`. + +**Mixed traversal pattern** (used by `traceability_analysis`): + +``` +requirement + --[links[]: implements]──→ task (flexible, declared by Worker/user) + task ←── pull_request.closesIssues (spec-level Contract field) + pull_request.verifiedBy ──→ test_case (spec-level Contract field) +``` + +`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 From 7acbb430f420e6d56133ce0aed5447a6161f0e7c Mon Sep 17 00:00:00 2001 From: ainetx Date: Wed, 8 Jul 2026 13:15:56 +0300 Subject: [PATCH 065/106] =?UTF-8?q?docs(v2):=20fix=20implements=20link=20d?= =?UTF-8?q?irection=20in=20=C2=A723;=20clarify=20ABAC=20condition=20Worker?= =?UTF-8?q?=20semantics?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: ainetx Co-authored-by: Constructor Studio <291158726+constructor-studio[bot]@users.noreply.github.com> Studio-Generated-By: Constructor Studio Studio-Source-Repo: https://github.com/constructorfabric/studio Constructor-Fabric: https://github.com/constructorfabric Studio-Version: skill=1.5.9, cli=1.5.10.dev73 Studio-Workflows: cf-brainstorm --- v2/docs/domain-model.md | 18 ++++++++++++------ 1 file changed, 12 insertions(+), 6 deletions(-) diff --git a/v2/docs/domain-model.md b/v2/docs/domain-model.md index 9cc9b71d..ffadf0f5 100644 --- a/v2/docs/domain-model.md +++ b/v2/docs/domain-model.md @@ -2430,12 +2430,18 @@ Studio uses a **two-layer link model**: **Mixed traversal pattern** (used by `traceability_analysis`): ``` -requirement - --[links[]: implements]──→ task (flexible, declared by Worker/user) - task ←── pull_request.closesIssues (spec-level Contract field) - pull_request.verifiedBy ──→ test_case (spec-level Contract field) +// 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. @@ -2567,8 +2573,8 @@ metadata.category: platform | `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: `allowed = object.assigneeId == principal.id OR object.ownerId == principal.id`. Standard building block for Policy.rules.condition. | -| `is_workspace_member_worker` | script | on_demand | ABAC condition: `allowed = principal is member of object.workspaceId`. Workspace-scoped access control. | +| `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. From 18990a99b0c84b4e9e9ac80868c003fb3fdbb54c Mon Sep 17 00:00:00 2001 From: ainetx Date: Wed, 8 Jul 2026 13:19:27 +0300 Subject: [PATCH 066/106] docs(v2): add x-gts-creates annotation; WorkerRun.createdObjectIds; Object materialization flow Signed-off-by: ainetx Co-authored-by: Constructor Studio <291158726+constructor-studio[bot]@users.noreply.github.com> Studio-Generated-By: Constructor Studio Studio-Source-Repo: https://github.com/constructorfabric/studio Constructor-Fabric: https://github.com/constructorfabric Studio-Version: skill=1.5.9, cli=1.5.10.dev73 Studio-Workflows: cf-brainstorm --- v2/docs/domain-model.md | 28 +++++++++++++++++++++++++++- 1 file changed, 27 insertions(+), 1 deletion(-) diff --git a/v2/docs/domain-model.md b/v2/docs/domain-model.md index ffadf0f5..02b5c5ec 100644 --- a/v2/docs/domain-model.md +++ b/v2/docs/domain-model.md @@ -318,6 +318,11 @@ Object { 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). @@ -554,7 +559,28 @@ 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`). +(`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: WorkerRun → done → platform reads output Contract → +for each `x-gts-creates: true` field → creates Object → sets `WorkerRun.createdObjectIds`. `x-gts-traits.capabilities` — opt-in Object capabilities declaration: From f7f7a7ba71af2e6a4bfb9cdeabc843b1665cee9b Mon Sep 17 00:00:00 2001 From: ainetx Date: Wed, 8 Jul 2026 13:22:31 +0300 Subject: [PATCH 067/106] =?UTF-8?q?docs(v2):=20specify=20materialization?= =?UTF-8?q?=20order=20(creates=E2=86=92state-sets);=20auto-links=20scope?= =?UTF-8?q?=20(=20only,=20x-gts-link=20opt-out)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: ainetx Co-authored-by: Constructor Studio <291158726+constructor-studio[bot]@users.noreply.github.com> Studio-Generated-By: Constructor Studio Studio-Source-Repo: https://github.com/constructorfabric/studio Constructor-Fabric: https://github.com/constructorfabric Studio-Version: skill=1.5.9, cli=1.5.10.dev73 Studio-Workflows: cf-brainstorm --- v2/docs/domain-model.md | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/v2/docs/domain-model.md b/v2/docs/domain-model.md index 02b5c5ec..7a092971 100644 --- a/v2/docs/domain-model.md +++ b/v2/docs/domain-model.md @@ -579,8 +579,13 @@ context (tenantId, workspaceId, ownerId, createdByRunId auto-set): } ``` -Materialization flow: WorkerRun → done → platform reads output Contract → -for each `x-gts-creates: true` field → creates Object → sets `WorkerRun.createdObjectIds`. +Materialization flow (order matters; non-atomic — retry via WorkerRun.checkpoint): + 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) from new Objects to input Objects: + - Only for input Contract fields with `$ref` (Object refs), NOT scalar fields + - Opt-out: `x-gts-link: false` on $ref field = skip auto-link (e.g. workspace context fields) + 4. WorkerRun.createdObjectIds = [new Object ids] `x-gts-traits.capabilities` — opt-in Object capabilities declaration: From 23e393c259c100a65d56f5e1b8752c1f69ac422c Mon Sep 17 00:00:00 2001 From: ainetx Date: Wed, 8 Jul 2026 13:29:02 +0300 Subject: [PATCH 068/106] =?UTF-8?q?docs(v2):=20add=20cross-workspace=20lin?= =?UTF-8?q?k=20policy;=20Tenant-level=20shared=20artifact=20pattern=20in?= =?UTF-8?q?=20=C2=A79?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: ainetx Co-authored-by: Constructor Studio <291158726+constructor-studio[bot]@users.noreply.github.com> Studio-Generated-By: Constructor Studio Studio-Source-Repo: https://github.com/constructorfabric/studio Constructor-Fabric: https://github.com/constructorfabric Studio-Version: skill=1.5.9, cli=1.5.10.dev73 Studio-Workflows: cf-brainstorm --- v2/docs/domain-model.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/v2/docs/domain-model.md b/v2/docs/domain-model.md index 7a092971..e5adb72f 100644 --- a/v2/docs/domain-model.md +++ b/v2/docs/domain-model.md @@ -391,6 +391,13 @@ Object { // 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) @@ -1252,6 +1259,11 @@ User { 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~ From 624fdb757f3a5d1ee9401e5f6f589be89331f7a4 Mon Sep 17 00:00:00 2001 From: ainetx Date: Wed, 8 Jul 2026 13:30:58 +0300 Subject: [PATCH 069/106] docs(v2): idempotent materialization (skip if createdObjectIds set); x-gts-link opt-in Signed-off-by: ainetx Co-authored-by: Constructor Studio <291158726+constructor-studio[bot]@users.noreply.github.com> Studio-Generated-By: Constructor Studio Studio-Source-Repo: https://github.com/constructorfabric/studio Constructor-Fabric: https://github.com/constructorfabric Studio-Version: skill=1.5.9, cli=1.5.10.dev73 Studio-Workflows: cf-brainstorm --- v2/docs/domain-model.md | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/v2/docs/domain-model.md b/v2/docs/domain-model.md index e5adb72f..495f7790 100644 --- a/v2/docs/domain-model.md +++ b/v2/docs/domain-model.md @@ -586,12 +586,15 @@ context (tenantId, workspaceId, ownerId, createdByRunId auto-set): } ``` -Materialization flow (order matters; non-atomic — retry via WorkerRun.checkpoint): +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) from new Objects to input Objects: - - Only for input Contract fields with `$ref` (Object refs), NOT scalar fields - - Opt-out: `x-gts-link: false` on $ref field = skip auto-link (e.g. workspace context fields) + 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: From 5d43d52eeb80e758c936c4ad218fbeb2fdb3bed5 Mon Sep 17 00:00:00 2001 From: ainetx Date: Wed, 8 Jul 2026 14:33:51 +0300 Subject: [PATCH 070/106] fix(v2/poc/ui-1): apply domain.ts type review findings (F-001 through F-036) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Applies all approved review fixes to the PoC domain type definitions: - F-025: add validation_session, evidence, worker_interaction to ObjectTypeId - F-032: add 'superseded' to ObjectState - F-013: replace non-canonical LinkKind values with core GTS kinds per §1.1 - F-015: remove label from ObjectLink; add createdBy/sourceRunId provenance union - F-036: remove 'skipped' from ValidationStatus; add escalated/aborted to FlowStepStatus - F-001: fix stalenessScore comment to 0.0–1.0 float per §20.1 - F-014: add 'ai-cost' to WorkerCategory - F-002: add 'escalated'|'aborted' to WorkerRunState - F-024: add requiredRole to WorkerInteractionDef - F-009: add entryConstraints to FlowDef; add skippedSteps to FlowRun - F-004: add 'invalidated' to RecommendationState - F-011: add RecommendationConfidence type and confidence field to Recommendation - F-012: add sourceRunId, reason, validationWorkerId, severityWorkerId to Recommendation - F-017: replace 'installing' with 'rolling_back' in KitStatus - F-030: add 'config' to WorkspaceSource.role union Co-authored-by: Constructor Studio <291158726+constructor-studio[bot]@users.noreply.github.com> Studio-Generated-By: Constructor Studio Studio-Source-Repo: https://github.com/constructorfabric/studio Constructor-Fabric: https://github.com/constructorfabric Signed-off-by: ainetx --- v2/poc/ui-1/src/types/domain.ts | 326 ++++++++++++++++++++++++++++++++ 1 file changed, 326 insertions(+) create mode 100644 v2/poc/ui-1/src/types/domain.ts diff --git a/v2/poc/ui-1/src/types/domain.ts b/v2/poc/ui-1/src/types/domain.ts new file mode 100644 index 00000000..fc40209b --- /dev/null +++ b/v2/poc/ui-1/src/types/domain.ts @@ -0,0 +1,326 @@ +// ─── Core Object Types ──────────────────────────────────────────────────────── + +export type ObjectTypeId = + | 'prd' + | 'design' + | 'task' + | 'pull_request' + | 'incident' + | 'adr' + | 'feature_spec' + | 'decomposition' + | 'build' + | 'worker_run' + | 'flow_run' + | 'recommendation' + | 'approval' + | 'validation_session' + | 'evidence' + | 'worker_interaction' + +export type ObjectState = + | 'draft' + | 'approved' + | 'in_progress' + | 'planned' + | 'done' + | 'failed' + | 'stale' + | 'open' + | 'review' + | 'running' + | 'merged' + | 'closed' + | 'superseded' + +// Core GTS link kinds per §1.1. Kit-extensible custom kinds (triggers, blocks, related_to) are not pre-registered core kinds. +export type LinkKind = + | 'derived_from' + | 'decomposes_into' + | 'implements' + | 'references' + | 'incorporates' + | 'validates' + | 'supersedes' + | 'informs' + +export type ValidationStatus = 'pass' | 'fail' | 'pending' | 'none' + +export interface ObjectLink { + targetId: string + kind: LinkKind + // Exactly one of createdBy (User ref) or sourceRunId (WorkerRun ref) should be set per §1.1 + createdBy?: string + sourceRunId?: string +} + +export interface StudioObject { + id: string + typeId: ObjectTypeId + tenantId: string + title: string + state: ObjectState + validationStatus: ValidationStatus + stalenessScore: number // 0.0–1.0 float per §20.1; 0.0=fresh, 1.0=stale + links: ObjectLink[] + createdAt: string + updatedAt: string + description?: string + metadata?: Record +} + +// ─── Worker Types ───────────────────────────────────────────────────────────── + +export type WorkerCategory = 'quality' | 'security' | 'ops' | 'ai-cost' | 'traceability' | 'retrieval' | 'platform' +export type WorkerProfile = 'realtime' | 'scheduled' | 'on_demand' +export type WorkerRunState = 'pending' | 'running' | 'awaiting_input' | 'paused' | 'done' | 'failed' | 'escalated' | 'aborted' +export type InteractionKind = 'menu' | 'input_request' | 'free_form_intent' + +export interface WorkerInteractionDef { + kind: InteractionKind + prompt: string + options?: string[] + requiredRole?: string // role pattern restricting who may answer; null = any authorized user +} + +export interface WorkerDef { + id: string + label: string + description: string + requiresAutomationGate: boolean + category: WorkerCategory + profile: WorkerProfile + actionLabel: string + applicableTypes: ObjectTypeId[] + interaction?: WorkerInteractionDef +} + +// ─── Worker Run ─────────────────────────────────────────────────────────────── + +export interface WorkerRun { + id: string + workerId: string + workerLabel: string + objectId: string + objectTitle: string + state: WorkerRunState + progress: number // 0-100 + startedAt: string + completedAt?: string + output?: string + error?: string + interaction?: WorkerInteractionDef + interactionResponse?: string + // Cost & performance + costUsd?: number + tokensIn?: number + tokensOut?: number + model?: string + durationMs?: number +} + +// ─── Flow Types ─────────────────────────────────────────────────────────────── + +export type FlowStepStatus = 'pending' | 'running' | 'done' | 'failed' | 'skipped' | 'escalated' | 'aborted' + +export interface FlowStep { + id: string + workerId: string + workerLabel: string + objectTypeTarget: ObjectTypeId + status: FlowStepStatus + workerRunId?: string +} + +export interface FlowDef { + id: string + label: string + description: string + steps: FlowStep[] + entryConstraints?: { typeId: ObjectTypeId; requiredStates?: ObjectState[] }[] +} + +export interface FlowRun { + id: string + flowId: string + flowLabel: string + state: WorkerRunState + completedSteps: string[] + skippedSteps: string[] + activeStepId?: string + stepStatus: Record + startedAt: string + completedAt?: string +} + +// ─── Recommendation Types ───────────────────────────────────────────────────── + +export type RecommendationSeverity = 'info' | 'warning' | 'critical' +export type RecommendationState = 'pending' | 'accepted' | 'executing' | 'done' | 'dismissed' | 'invalidated' +export type RecommendationConfidence = 'full' | 'partial' | 'low' + +export interface Recommendation { + id: string + title: string + description: string + severity: RecommendationSeverity + state: RecommendationState + confidence?: RecommendationConfidence + suggestedWorkerId: string // PoC denormalization of doc's suggestedWorker ref + suggestedWorkerLabel: string + relatedObjectIds: string[] + createdAt: string + sourceRunId?: string // ref → WorkerRun that produced this recommendation + reason?: string // machine-readable gap description (distinct from description) + validationWorkerId?: string + severityWorkerId?: string +} + +// ─── App View Types ─────────────────────────────────────────────────────────── + +export type AppView = 'graph' | 'flows' | 'activity' | 'recommendations' | 'files' | 'kits' | 'workspaces' | 'chat' + +export interface GraphNodeData { + object: StudioObject + selected?: boolean +} + +export interface FileNode { + id: string + name: string + type: 'file' | 'folder' + children?: FileNode[] + language?: 'markdown' | 'typescript' | 'sql' | 'toml' | 'text' + linkedObjectId?: string + isDraft?: boolean +} + +// ─── Flow Graph Types ───────────────────────────────────────────────────────── + +export type FlowNodeType = 'start' | 'end' | 'worker' | 'gate' | 'human' | 'escalation' | 'decision' +export type FlowEdgeKind = 'default' | 'pass' | 'fail' | 'retry' | 'branch' +export type FlowNodeExecState = 'idle' | 'running' | 'passed' | 'failed' | 'retrying' | 'skipped' | 'done' | 'waiting' + +export interface FlowInteractionOption { + id: string + label: string + description?: string + color?: string // optional accent color for the button + nextNodeHint?: string // which path this takes (informational) +} + +export interface FlowNodeInteraction { + kind: 'menu' | 'input' | 'approval' + prompt: string + options?: FlowInteractionOption[] // for kind: menu | approval + inputPlaceholder?: string // for kind: input + pauseAfterMs?: number // delay before pausing (default: after worker runs) +} + +export interface FlowGraphNode { + id: string + nodeType: FlowNodeType + label: string + sublabel?: string + maxRetries?: number + interaction?: FlowNodeInteraction // pauses flow for user input + position: { x: number; y: number } +} + +export interface FlowGraphEdge { + id: string + source: string + target: string + edgeKind: FlowEdgeKind + label?: string + branchOptionId?: string // only active when this option was chosen at source decision/gate +} + +export interface FlowGraphDef { + id: string + name: string + description: string + category: string + nodes: FlowGraphNode[] + edges: FlowGraphEdge[] +} + +export interface FlowArtifact { + label: string + nodeType: string + nodeId: string +} + +export interface FlowPendingInteraction { + nodeId: string + interaction: FlowNodeInteraction + resumeAfterOptionId?: string // set after user picks, used to route branches +} + +export interface FlowExecState { + flowId: string + status: 'running' | 'done' | 'failed' | 'waiting_input' + nodeStates: Record + retryCounters: Record + currentNodeId: string | null + producedArtifacts: FlowArtifact[] + startedAt: number + pendingInteraction?: FlowPendingInteraction + takenBranches: Record // nodeId → chosen option id + inputResponses: Record // nodeId → text input +} + +// ─── Kit Types ──────────────────────────────────────────────────────────────── + +export type KitStatus = 'active' | 'update_available' | 'rolling_back' | 'failed' + +export interface KitDef { + id: string + name: string + description: string + version: string + latestVersion?: string + status: KitStatus + category: string + workerCount: number + connectorCount: number + author: string + tags: string[] + installedAt: string + workers: Array<{ id: string; label: string; category: string }> +} + +// ─── Workspace Types ────────────────────────────────────────────────────────── + +export type WorkspaceStatus = 'active' | 'syncing' | 'error' | 'offline' + +export interface WorkspaceSource { + id: string + url: string + role: 'main' | 'docs' | 'platform' | 'shared' | 'test' | 'config' + branch: string + lastSyncedAt: string +} + +export interface WorkspaceDef { + id: string + name: string + description?: string + status: WorkspaceStatus + sources: WorkspaceSource[] + installedKitIds: string[] + automationLevel: 'recommendations' | 'approved_automation' | 'enterprise' + lastSyncedAt: string + objectCount: number +} + +export interface LineAction { + visible: boolean + top?: number + left?: number + startLine?: number + endLine?: number + selectedText?: string + fileId?: string + language?: string +} From e8d4101a49de9ed323f8f147241a8ab40ef3039d Mon Sep 17 00:00:00 2001 From: ainetx Date: Wed, 8 Jul 2026 14:45:28 +0300 Subject: [PATCH 071/106] fix(poc/ui-1): apply review fixes F-001/F-008/F-010/F-016/F-027/F-028/F-035 to mock-data MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - F-001: convert all stalenessScore integers to 0.0–1.0 float scale (÷100) - F-008: fix release_readiness_review Flow steps to match §22.2 (gap analysis, test coverage ≥80%, security scan, tech lead approval) - F-010: set requiresAutomationGate:true and category:'quality' on all five SDLC producer Workers (create_prd, create_design, decompose_feature, create_feature_spec, create_adr) - F-016: fix bug_fix_flow mandatory steps to §22.2 bug_to_fix_pr_flow order; replace gap_analysis_validator step-1 with bug_description_validator, add confirm_test_fails_validator and confirm_test_passes_validator after implement, remove reverse_engineer_worker step - F-027: fix link direction errors — remove wrong prd-001 derived_from links to ADRs/design; change adr-001/adr-002 links to informs kind; fix design-001 decomp link to decomposes_into; remove duplicate task-001→pr-001 produces link; strip all label fields from every link object - F-028: replace reverse_engineer_worker definition with find_suspected_component (doc-defined analyzer Worker per §22.2) - F-035: add comment in Kit workers array noting release_readiness_review is a Flow, not a plain Worker Co-authored-by: Constructor Studio <291158726+constructor-studio[bot]@users.noreply.github.com> Studio-Generated-By: Constructor Studio Studio-Source-Repo: https://github.com/constructorfabric/studio Constructor-Fabric: https://github.com/constructorfabric Signed-off-by: ainetx --- v2/poc/ui-1/src/data/mock-data.ts | 1084 +++++++++++++++++++++++++++++ 1 file changed, 1084 insertions(+) create mode 100644 v2/poc/ui-1/src/data/mock-data.ts diff --git a/v2/poc/ui-1/src/data/mock-data.ts b/v2/poc/ui-1/src/data/mock-data.ts new file mode 100644 index 00000000..693dae6e --- /dev/null +++ b/v2/poc/ui-1/src/data/mock-data.ts @@ -0,0 +1,1084 @@ +import type { StudioObject, WorkerDef, FlowDef, Recommendation } from '../types/domain' + +// ─── Objects ────────────────────────────────────────────────────────────────── + +export const MOCK_OBJECTS: StudioObject[] = [ + { + id: 'prd-001', + typeId: 'prd', + tenantId: 'tenant-acme', + title: 'Billing Service v2', + state: 'approved', + validationStatus: 'pass', + stalenessScore: 0.05, + description: 'Product requirements for multi-tenant billing service v2, including Stripe integration, invoice generation, and ledger management.', + links: [ + // F-027: removed derived_from/drives links to adr-001, adr-002, design-001 — wrong direction; + // ADRs inform prd-001 (adr→prd), design-001 derives from prd-001 (design→prd) + ], + createdAt: '2026-06-01T09:00:00Z', + updatedAt: '2026-06-15T14:30:00Z', + metadata: { version: '2.0', owner: 'product@acme.com', priority: 'P0' }, + }, + { + id: 'adr-001', + typeId: 'adr', + tenantId: 'tenant-acme', + title: 'Event-driven billing architecture', + state: 'approved', + validationStatus: 'pass', + stalenessScore: 0.08, + description: 'Decision to use event-driven architecture for billing processing to enable async invoice generation and webhook handling.', + links: [ + { targetId: 'prd-001', kind: 'informs' }, + { targetId: 'design-001', kind: 'informs' }, + ], + createdAt: '2026-06-02T10:00:00Z', + updatedAt: '2026-06-10T11:00:00Z', + metadata: { status: 'accepted', supersedes: null }, + }, + { + id: 'adr-002', + typeId: 'adr', + tenantId: 'tenant-acme', + title: 'PostgreSQL for billing ledger', + state: 'approved', + validationStatus: 'pass', + stalenessScore: 0.03, + description: 'Decision to use PostgreSQL with partitioning for the billing ledger to support high-volume transaction data.', + links: [ + { targetId: 'prd-001', kind: 'informs' }, + { targetId: 'design-001', kind: 'informs' }, + { targetId: 'task-003', kind: 'informs' }, + ], + createdAt: '2026-06-02T11:00:00Z', + updatedAt: '2026-06-10T11:30:00Z', + metadata: { status: 'accepted', alternatives: ['MySQL', 'CockroachDB'] }, + }, + { + id: 'design-001', + typeId: 'design', + tenantId: 'tenant-acme', + title: 'Billing Service Architecture', + state: 'approved', + validationStatus: 'pass', + stalenessScore: 0.12, + description: 'System design for billing service v2 covering webhook ingestion, event bus, invoice generation service, ledger schema and API contracts.', + links: [ + { targetId: 'prd-001', kind: 'derived_from' }, + { targetId: 'adr-001', kind: 'references' }, + { targetId: 'adr-002', kind: 'references' }, + { targetId: 'decomp-001', kind: 'decomposes_into' }, + ], + createdAt: '2026-06-05T09:00:00Z', + updatedAt: '2026-06-18T16:00:00Z', + metadata: { version: '1.2', reviewers: ['arch@acme.com'] }, + }, + { + id: 'decomp-001', + typeId: 'decomposition', + tenantId: 'tenant-acme', + title: 'Billing v2 Tasks', + state: 'approved', + validationStatus: 'pass', + stalenessScore: 0.10, + description: 'Task decomposition for billing service v2 implementation, ordered by dependency.', + links: [ + { targetId: 'design-001', kind: 'derived_from' }, + { targetId: 'task-001', kind: 'decomposes_into' }, + { targetId: 'task-002', kind: 'decomposes_into' }, + { targetId: 'task-003', kind: 'decomposes_into' }, + ], + createdAt: '2026-06-10T10:00:00Z', + updatedAt: '2026-06-20T09:00:00Z', + }, + { + id: 'task-001', + typeId: 'task', + tenantId: 'tenant-acme', + title: 'Implement Stripe Webhook Handler', + state: 'in_progress', + validationStatus: 'pending', + stalenessScore: 0.0, + description: 'Implement the Stripe webhook ingestion endpoint, signature verification, and event dispatch to internal billing event bus.', + links: [ + { targetId: 'decomp-001', kind: 'derived_from' }, + { targetId: 'fspec-001', kind: 'implements' }, + // F-027: removed derived_from/produces link to pr-001 — pr-001 already has implements→task-001 + ], + createdAt: '2026-06-20T10:00:00Z', + updatedAt: '2026-07-05T11:00:00Z', + metadata: { assignee: 'dev1@acme.com', sprint: 'Sprint 42', points: 5 }, + }, + { + id: 'task-002', + typeId: 'task', + tenantId: 'tenant-acme', + title: 'Implement Invoice Generation Worker', + state: 'planned', + validationStatus: 'none', + stalenessScore: 0.0, + description: 'Build the async invoice generation worker that processes billing events and produces PDF invoices stored in S3.', + links: [ + { targetId: 'decomp-001', kind: 'derived_from' }, + { targetId: 'fspec-002', kind: 'implements' }, + ], + createdAt: '2026-06-20T10:30:00Z', + updatedAt: '2026-06-25T09:00:00Z', + metadata: { assignee: null, sprint: 'Sprint 43', points: 8 }, + }, + { + id: 'task-003', + typeId: 'task', + tenantId: 'tenant-acme', + title: 'Billing Ledger Schema Migration', + state: 'done', + validationStatus: 'pass', + stalenessScore: 0.45, + description: 'PostgreSQL schema migration for billing ledger with partitioning by tenant and month.', + links: [ + { targetId: 'decomp-001', kind: 'derived_from' }, + { targetId: 'adr-002', kind: 'implements' }, + ], + createdAt: '2026-06-15T09:00:00Z', + updatedAt: '2026-06-28T14:00:00Z', + metadata: { assignee: 'dev2@acme.com', sprint: 'Sprint 41', points: 3 }, + }, + { + id: 'fspec-001', + typeId: 'feature_spec', + tenantId: 'tenant-acme', + title: 'Stripe Webhook Flow', + state: 'approved', + validationStatus: 'pass', + stalenessScore: 0.05, + description: 'Feature specification for the Stripe webhook handler including all event types, error handling, retry logic, and idempotency guarantees.', + links: [ + { targetId: 'task-001', kind: 'derived_from' }, + { targetId: 'design-001', kind: 'derived_from' }, + ], + createdAt: '2026-06-22T09:00:00Z', + updatedAt: '2026-07-01T10:00:00Z', + metadata: { testScenarios: 12, coverage: '95%' }, + }, + { + id: 'fspec-002', + typeId: 'feature_spec', + tenantId: 'tenant-acme', + title: 'Invoice Generation Flow', + state: 'draft', + validationStatus: 'pending', + stalenessScore: 0.0, + description: 'Feature specification for invoice generation worker. Currently missing test scenarios and error handling flows.', + links: [ + { targetId: 'task-002', kind: 'derived_from' }, + { targetId: 'design-001', kind: 'derived_from' }, + ], + createdAt: '2026-06-28T14:00:00Z', + updatedAt: '2026-07-02T09:00:00Z', + metadata: { testScenarios: 0, coverage: '0%' }, + }, + { + id: 'pr-001', + typeId: 'pull_request', + tenantId: 'tenant-acme', + title: 'feat/stripe-webhook-handler', + state: 'review', + validationStatus: 'pending', + stalenessScore: 0.0, + description: 'Pull request implementing the Stripe webhook handler per feature spec. Awaiting design validation and security review.', + links: [ + { targetId: 'task-001', kind: 'implements' }, + { targetId: 'fspec-001', kind: 'validates' }, + ], + createdAt: '2026-07-04T15:00:00Z', + updatedAt: '2026-07-06T10:00:00Z', + metadata: { prNumber: 247, branch: 'feat/stripe-webhook-handler', commits: 8, additions: 1240, deletions: 45 }, + }, + { + id: 'build-001', + typeId: 'build', + tenantId: 'tenant-acme', + title: 'ci-run-4521', + state: 'running', + validationStatus: 'pending', + stalenessScore: 0.0, + description: 'CI build for PR #247 feat/stripe-webhook-handler. Running unit tests, integration tests and coverage check.', + links: [ + { targetId: 'pr-001', kind: 'validates' }, + ], + createdAt: '2026-07-06T10:05:00Z', + updatedAt: '2026-07-06T10:05:00Z', + metadata: { pipeline: 'billing-service-ci', runner: 'github-actions', duration: '4m 32s' }, + }, + { + id: 'inc-001', + typeId: 'incident', + tenantId: 'tenant-acme', + title: 'Billing duplicate charge INC-441', + state: 'open', + validationStatus: 'none', + stalenessScore: 0.0, + description: 'Production incident: customers being charged twice for subscription renewals. Severity P1. Billing event deduplication logic suspect.', + links: [ + { targetId: 'fspec-001', kind: 'related_to' }, + { targetId: 'design-001', kind: 'related_to' }, + ], + createdAt: '2026-07-06T08:00:00Z', + updatedAt: '2026-07-06T11:00:00Z', + metadata: { severity: 'P1', affectedTenants: 12, status: 'investigating' }, + }, +] + +// ─── Graph Node Positions ───────────────────────────────────────────────────── + +export const NODE_POSITIONS: Record = { + 'prd-001': { x: 60, y: 200 }, + 'adr-001': { x: 60, y: 60 }, + 'adr-002': { x: 60, y: 340 }, + 'design-001': { x: 320, y: 200 }, + 'decomp-001': { x: 580, y: 200 }, + 'task-001': { x: 840, y: 80 }, + 'task-002': { x: 840, y: 220 }, + 'task-003': { x: 840, y: 360 }, + 'fspec-001': { x: 1100, y: 80 }, + 'fspec-002': { x: 1100, y: 220 }, + 'pr-001': { x: 1360, y: 80 }, + 'build-001': { x: 1620, y: 80 }, + 'inc-001': { x: 1360, y: 300 }, +} + +// ─── Worker Definitions ─────────────────────────────────────────────────────── + +export const WORKER_DEFS: WorkerDef[] = [ + // F-010: SDLC producer Workers — requiresAutomationGate: true, category: 'quality' + { + id: 'create_prd_worker', + label: 'Create PRD', + description: 'Generates a product requirements document from a high-level intent description.', + requiresAutomationGate: true, + category: 'quality', + profile: 'on_demand', + actionLabel: 'Create PRD', + applicableTypes: ['prd'], + }, + { + id: 'create_design_worker', + label: 'Create Design', + description: 'Generates a system design document from an approved PRD.', + requiresAutomationGate: true, + category: 'quality', + profile: 'on_demand', + actionLabel: 'Create Design', + applicableTypes: ['prd'], + interaction: { + kind: 'input_request', + prompt: 'Specify any architectural constraints or technology preferences for this design:', + }, + }, + { + id: 'decompose_feature_worker', + label: 'Decompose into Tasks', + description: 'Decomposes a design document into ordered, implementable tasks.', + requiresAutomationGate: true, + category: 'quality', + profile: 'on_demand', + actionLabel: 'Decompose', + applicableTypes: ['design'], + interaction: { + kind: 'menu', + prompt: 'Choose decomposition strategy:', + options: ['Dependency order', 'Risk-first', 'Value-first'], + }, + }, + { + id: 'create_feature_spec_worker', + label: 'Create Feature Spec', + description: 'Authors a detailed feature specification with test scenarios from a task definition.', + requiresAutomationGate: true, + category: 'quality', + profile: 'on_demand', + actionLabel: 'Create Feature Spec', + applicableTypes: ['task'], + }, + { + id: 'implement_code_worker', + label: 'Implement Code', + description: 'Writes implementation code from a feature spec or task definition.', + requiresAutomationGate: true, + category: 'platform', + profile: 'on_demand', + actionLabel: 'Implement', + applicableTypes: ['task', 'feature_spec'], + interaction: { + kind: 'input_request', + prompt: 'Clarify the implementation scope (e.g. files to touch, patterns to follow, tests to write):', + }, + }, + { + id: 'create_pr_worker', + label: 'Create Pull Request', + description: 'Creates a GitHub pull request from completed implementation work.', + requiresAutomationGate: true, + category: 'platform', + profile: 'on_demand', + actionLabel: 'Create PR', + applicableTypes: ['pull_request', 'task'], + }, + { + id: 'create_adr_worker', + label: 'Create ADR', + description: 'Authors an architecture decision record capturing context, options and decision.', + requiresAutomationGate: true, + category: 'quality', + profile: 'on_demand', + actionLabel: 'Create ADR', + applicableTypes: ['adr'], + }, + { + id: 'gap_analysis_validator', + label: 'Gap Analysis', + description: 'Validates coverage and identifies missing requirements, test scenarios or traceability gaps.', + requiresAutomationGate: false, + category: 'quality', + profile: 'scheduled', + actionLabel: 'Run Gap Analysis', + applicableTypes: ['prd', 'design', 'feature_spec', 'incident'], + }, + { + id: 'pr_design_validator', + label: 'Validate PR vs Design', + description: 'Validates that a pull request implements the design correctly. Raises findings for deviations.', + requiresAutomationGate: false, + category: 'quality', + profile: 'realtime', + actionLabel: 'Validate vs Design', + applicableTypes: ['pull_request'], + interaction: { + kind: 'menu', + prompt: 'Select action for finding: "Missing event deduplication guard"', + options: ['Fix', 'Skip', 'Accept Risk'], + }, + }, + { + id: 'traceability_analysis', + label: 'Traceability Analysis', + description: 'Traces coverage from requirements through design, tasks, code and tests.', + requiresAutomationGate: false, + category: 'traceability', + profile: 'scheduled', + actionLabel: 'Analyze Traceability', + applicableTypes: ['prd', 'design', 'decomposition'], + }, + { + id: 'stale_artifact_detection', + label: 'Detect Stale Artifacts', + description: 'Identifies artifacts that have drifted from source and need updating.', + requiresAutomationGate: false, + category: 'quality', + profile: 'scheduled', + actionLabel: 'Check Staleness', + applicableTypes: ['task', 'feature_spec', 'design'], + }, + { + id: 'security_impact_analysis', + label: 'Security Impact Analysis', + description: 'Analyzes security implications of a pull request or design change.', + requiresAutomationGate: false, + category: 'security', + profile: 'on_demand', + actionLabel: 'Security Review', + applicableTypes: ['pull_request', 'design'], + }, + { + id: 'object_graph_retriever', + label: 'Retrieve Context', + description: 'Retrieves relevant object context and related artifacts for analysis.', + requiresAutomationGate: false, + category: 'retrieval', + profile: 'realtime', + actionLabel: 'Retrieve Context', + applicableTypes: ['prd', 'design', 'task', 'feature_spec'], + }, + // F-028: replaced reverse_engineer_worker with doc-defined find_suspected_component + { + id: 'find_suspected_component', + label: 'Find Suspected Component', + description: 'Identifies the component most likely responsible for the bug', + requiresAutomationGate: false, + category: 'quality', + profile: 'analyzer', + applicableTypes: ['incident', 'task'], + }, + // F-016: validators required by bug_fix_flow per §22.2 + { + id: 'bug_description_validator', + label: 'Bug Description Validation', + description: 'Validates that a bug report contains sufficient information for triage and reproduction.', + requiresAutomationGate: false, + category: 'quality', + profile: 'on_demand', + actionLabel: 'Validate Bug', + applicableTypes: ['incident', 'task'], + }, + { + id: 'confirm_test_fails_validator', + label: 'Confirm Test Fails', + description: 'Confirms that the regression test for the bug fails before the fix is applied.', + requiresAutomationGate: false, + category: 'quality', + profile: 'on_demand', + actionLabel: 'Confirm Fails', + applicableTypes: ['incident', 'task'], + }, + { + id: 'confirm_test_passes_validator', + label: 'Confirm Test Passes', + description: 'Confirms that the regression test passes after the fix is applied.', + requiresAutomationGate: false, + category: 'quality', + profile: 'on_demand', + actionLabel: 'Confirm Passes', + applicableTypes: ['incident', 'task'], + }, + // F-008: validators required by release_readiness_review per §22.2 + { + id: 'test_coverage_validator', + label: 'Test Coverage (>=80%)', + description: 'Validates that test coverage meets or exceeds the 80% threshold.', + requiresAutomationGate: false, + category: 'quality', + profile: 'scheduled', + actionLabel: 'Check Coverage', + applicableTypes: ['pull_request', 'task', 'feature_spec'], + }, + { + id: 'security_scan_validator', + label: 'Security Scan', + description: 'Runs automated security scanning against the release candidate.', + requiresAutomationGate: false, + category: 'security', + profile: 'scheduled', + actionLabel: 'Security Scan', + applicableTypes: ['pull_request', 'design'], + }, + { + id: 'tech_lead_approval', + label: 'Tech Lead Approval', + description: 'Human approval gate requiring sign-off from a tech lead before release.', + requiresAutomationGate: false, + category: 'quality', + profile: 'on_demand', + actionLabel: 'Approve', + applicableTypes: ['prd', 'design', 'pull_request'], + }, +] + +// ─── Workers by Object Type ─────────────────────────────────────────────────── + +export function getWorkersForObject(typeId: string): WorkerDef[] { + return WORKER_DEFS.filter(w => w.applicableTypes.includes(typeId as never)) +} + +// ─── Flow Definitions ───────────────────────────────────────────────────────── + +export const FLOW_DEFS: FlowDef[] = [ + { + id: 'sdlc_pipeline_flow', + label: 'SDLC Pipeline', + description: 'Full SDLC pipeline from PRD through design, decomposition, feature spec, implementation to pull request.', + steps: [ + { id: 'step-prd', workerId: 'create_prd_worker', workerLabel: 'Create PRD', objectTypeTarget: 'prd', status: 'pending' }, + { id: 'step-adr', workerId: 'create_adr_worker', workerLabel: 'Create ADR', objectTypeTarget: 'adr', status: 'pending' }, + { id: 'step-design', workerId: 'create_design_worker', workerLabel: 'Create Design', objectTypeTarget: 'design', status: 'pending' }, + { id: 'step-decomp', workerId: 'decompose_feature_worker', workerLabel: 'Decompose Tasks', objectTypeTarget: 'decomposition', status: 'pending' }, + { id: 'step-fspec', workerId: 'create_feature_spec_worker', workerLabel: 'Create Feature Spec', objectTypeTarget: 'feature_spec', status: 'pending' }, + { id: 'step-impl', workerId: 'implement_code_worker', workerLabel: 'Implement', objectTypeTarget: 'task', status: 'pending' }, + { id: 'step-pr', workerId: 'create_pr_worker', workerLabel: 'Create PR', objectTypeTarget: 'pull_request', status: 'pending' }, + ], + }, + // F-008/STALE-001: steps fixed to match §22.2 — gap analysis, test coverage, security scan, tech lead approval + { + id: 'release_readiness_review', + label: 'Release Readiness Review', + description: 'Pre-release quality gate: gap analysis, test coverage, security scan, and tech lead approval.', + steps: [ + { id: 'step-gap', workerId: 'gap_analysis_validator', workerLabel: 'Gap Analysis', objectTypeTarget: 'feature_spec', status: 'pending' }, + { id: 'step-coverage', workerId: 'test_coverage_validator', workerLabel: 'Test Coverage (>=80%)', objectTypeTarget: 'pull_request', status: 'pending' }, + { id: 'step-security', workerId: 'security_scan_validator', workerLabel: 'Security Scan', objectTypeTarget: 'pull_request', status: 'pending' }, + { id: 'step-approval', workerId: 'tech_lead_approval', workerLabel: 'Tech Lead Approval', objectTypeTarget: 'pull_request', status: 'pending' }, + ], + }, + // F-016: steps fixed to match §22.2 bug_to_fix_pr_flow + { + id: 'bug_fix_flow', + label: 'Bug Fix Flow', + description: 'Structured bug fix: validate description, implement fix, confirm tests, create PR.', + steps: [ + { id: 'step-validate', workerId: 'bug_description_validator', workerLabel: 'Bug Description Validation', objectTypeTarget: 'incident', status: 'pending' }, + { id: 'step-fix', workerId: 'implement_code_worker', workerLabel: 'Implement Fix', objectTypeTarget: 'task', status: 'pending' }, + { id: 'step-confirm-fails', workerId: 'confirm_test_fails_validator', workerLabel: 'Confirm Test Fails', objectTypeTarget: 'task', status: 'pending' }, + { id: 'step-confirm-passes', workerId: 'confirm_test_passes_validator', workerLabel: 'Confirm Test Passes', objectTypeTarget: 'task', status: 'pending' }, + { id: 'step-pr', workerId: 'create_pr_worker', workerLabel: 'Create Fix PR', objectTypeTarget: 'pull_request', status: 'pending' }, + ], + }, +] + +// ─── Recommendations ────────────────────────────────────────────────────────── + +export const MOCK_RECOMMENDATIONS: Recommendation[] = [ + { + id: 'rec-001', + title: 'Invoice Generation Flow spec missing test scenarios', + description: 'Feature spec "Invoice Generation Flow" has 0 test scenarios defined. This leaves the implementation unverifiable and risks regression.', + severity: 'critical', + state: 'pending', + suggestedWorkerId: 'gap_analysis_validator', + suggestedWorkerLabel: 'Gap Analysis', + relatedObjectIds: ['fspec-002', 'task-002'], + createdAt: '2026-07-06T07:00:00Z', + }, + { + id: 'rec-002', + title: 'Billing Ledger Migration has no traceability markers in source code', + description: 'Task "Billing Ledger Schema Migration" is marked done but no @cpt-* traceability markers were found in the merged code. Coverage gap detected.', + severity: 'warning', + state: 'pending', + suggestedWorkerId: 'stale_artifact_detection', + suggestedWorkerLabel: 'Detect Stale Artifacts', + relatedObjectIds: ['task-003'], + createdAt: '2026-07-05T16:00:00Z', + }, + { + id: 'rec-003', + title: 'PR feat/stripe-webhook-handler has no security review', + description: 'PR #247 has been in review for 2 days without a security impact analysis. Webhook handler touches payment data and should be reviewed.', + severity: 'info', + state: 'pending', + suggestedWorkerId: 'security_impact_analysis', + suggestedWorkerLabel: 'Security Impact Analysis', + relatedObjectIds: ['pr-001'], + createdAt: '2026-07-06T09:00:00Z', + }, + { + id: 'rec-004', + title: 'Design references ADR-001 but no code implements event-driven pattern', + description: 'Billing Service Architecture references event-driven pattern from ADR-001, but traceability analysis found no event bus implementation in merged code.', + severity: 'warning', + state: 'pending', + suggestedWorkerId: 'traceability_analysis', + suggestedWorkerLabel: 'Traceability Analysis', + relatedObjectIds: ['design-001', 'adr-001'], + createdAt: '2026-07-06T08:30:00Z', + }, +] + +// ─── Flow Graph Definitions ─────────────────────────────────────────────────── + +import type { FlowGraphDef, KitDef, WorkspaceDef } from '../types/domain' + +export const FLOW_GRAPH_DEFS: FlowGraphDef[] = [ + // ─── Flow 1: SDLC Pipeline (with branching + interactions) ───────────────── + { + id: 'flow-sdlc-pipeline', + name: 'SDLC Pipeline', + description: 'PRD → Design → Decompose → Implement → PR — with validation gates, branching decisions, and human interactions', + category: 'sdlc', + nodes: [ + { id: 'n-start', nodeType: 'start', label: 'Start', position: { x: 280, y: 20 } }, + + // Decision: how to create PRD? + { id: 'n-prd-source', nodeType: 'decision', label: 'PRD Source?', + interaction: { + kind: 'menu', prompt: 'How do you want to create the PRD?', + options: [ + { id: 'author', label: 'Author with AI', description: 'Use create_prd_worker to draft from intent', color: '#818cf8', nextNodeHint: 'n-prd' }, + { id: 'import', label: 'Import from Confluence', description: 'Sync existing PRD via Connector', color: '#22d3ee', nextNodeHint: 'n-import' }, + ] + }, + position: { x: 260, y: 110 } }, + + { id: 'n-import', nodeType: 'worker', label: 'Import PRD', sublabel: 'script · connector', position: { x: 60, y: 220 } }, + { id: 'n-prd', nodeType: 'worker', label: 'Create PRD', sublabel: 'LLM · quality', position: { x: 460, y: 220 } }, + + // Gate: PRD valid? + { id: 'n-gate-prd', nodeType: 'gate', label: 'PRD Valid?', maxRetries: 2, + interaction: { + kind: 'menu', prompt: 'Validation failed — how to proceed?', + options: [ + { id: 'fix', label: 'Fix gaps and retry', description: 'Re-run PRD worker with corrections', color: '#818cf8' }, + { id: 'risk', label: 'Accept risk', description: 'Create risk_acceptance Approval and continue', color: '#f59e0b' }, + { id: 'escalate',label: 'Escalate', description: 'Block and notify tech lead', color: '#f87171' }, + ] + }, + position: { x: 262, y: 340 } }, + + { id: 'n-escalate-prd',nodeType: 'escalation',label: 'Escalate', position: { x: 480, y: 340 } }, + { id: 'n-design', nodeType: 'worker', label: 'Create Design', sublabel: 'LLM · quality', position: { x: 260, y: 460 } }, + + // Gate: Design valid? + { id: 'n-gate-design', nodeType: 'gate', label: 'Design Valid?', maxRetries: 2, + interaction: { + kind: 'menu', prompt: 'Design validation failed — what now?', + options: [ + { id: 'fix', label: 'Fix and retry', description: 'Regenerate with gap feedback', color: '#818cf8' }, + { id: 'risk', label: 'Accept risk', description: 'Continue with known gaps', color: '#f59e0b' }, + ] + }, + position: { x: 262, y: 580 } }, + + // Worker with mid-run interaction + { id: 'n-decomp', nodeType: 'worker', label: 'Decompose Tasks', sublabel: 'LLM · quality', + interaction: { + kind: 'menu', prompt: 'Choose task ordering strategy:', + options: [ + { id: 'dependency', label: 'Dependency order', description: 'Critical path first — ensures unblocked execution', color: '#10b981' }, + { id: 'risk', label: 'Risk-first', description: 'Tackle high-risk tasks early for fast feedback', color: '#f87171' }, + { id: 'value', label: 'Value-first', description: 'Deliver customer value as early as possible', color: '#f59e0b' }, + ] + }, + position: { x: 260, y: 700 } }, + + { id: 'n-gate-decomp', nodeType: 'gate', label: 'Tasks Valid?', maxRetries: 1, position: { x: 262, y: 820 } }, + { id: 'n-impl', nodeType: 'worker', label: 'Implement', sublabel: 'LLM · coding', position: { x: 260, y: 940 } }, + { id: 'n-gate-pr', nodeType: 'gate', label: 'PR Valid?', maxRetries: 3, + interaction: { + kind: 'menu', prompt: 'PR validation found issues — per-finding action:', + options: [ + { id: 'fix', label: 'Fix all findings', description: 'Auto-fix with implement_code_worker', color: '#10b981' }, + { id: 'skip', label: 'Skip minor issues', description: 'Dismiss info-level findings', color: '#f59e0b' }, + { id: 'risk', label: 'Accept all risks', description: 'Create risk_acceptance Approval', color: '#f87171' }, + ] + }, + position: { x: 262, y: 1060 } }, + { id: 'n-end', nodeType: 'end', label: 'Done', position: { x: 278, y: 1180 } }, + ], + edges: [ + { id: 'e1', source: 'n-start', target: 'n-prd-source', edgeKind: 'default' }, + // Decision branches + { id: 'e2a', source: 'n-prd-source', target: 'n-prd', edgeKind: 'branch', label: 'Author', branchOptionId: 'author' }, + { id: 'e2b', source: 'n-prd-source', target: 'n-import', edgeKind: 'branch', label: 'Import', branchOptionId: 'import' }, + // Merge both branches into gate + { id: 'e3a', source: 'n-prd', target: 'n-gate-prd', edgeKind: 'default' }, + { id: 'e3b', source: 'n-import', target: 'n-gate-prd', edgeKind: 'default' }, + // Gate outcomes + { id: 'e4', source: 'n-gate-prd', target: 'n-design', edgeKind: 'pass', label: 'PASS' }, + { id: 'e5', source: 'n-gate-prd', target: 'n-escalate-prd',edgeKind: 'fail', label: 'Escalate', branchOptionId: 'escalate' }, + { id: 'e6', source: 'n-gate-prd', target: 'n-design', edgeKind: 'pass', label: 'Accept risk', branchOptionId: 'risk' }, + { id: 'e7', source: 'n-gate-prd', target: 'n-prd', edgeKind: 'retry', label: 'retry', branchOptionId: 'fix' }, + // Design + { id: 'e8', source: 'n-design', target: 'n-gate-design', edgeKind: 'default' }, + { id: 'e9', source: 'n-gate-design', target: 'n-decomp', edgeKind: 'pass', label: 'PASS' }, + { id: 'e10', source: 'n-gate-design', target: 'n-design', edgeKind: 'retry', label: 'retry' }, + // Decompose + gate + { id: 'e11', source: 'n-decomp', target: 'n-gate-decomp', edgeKind: 'default' }, + { id: 'e12', source: 'n-gate-decomp', target: 'n-impl', edgeKind: 'pass', label: 'PASS' }, + { id: 'e13', source: 'n-gate-decomp', target: 'n-decomp', edgeKind: 'retry', label: 'retry' }, + // Implement + PR gate + { id: 'e14', source: 'n-impl', target: 'n-gate-pr', edgeKind: 'default' }, + { id: 'e15', source: 'n-gate-pr', target: 'n-end', edgeKind: 'pass', label: 'PASS' }, + { id: 'e16', source: 'n-gate-pr', target: 'n-impl', edgeKind: 'retry', label: 'retry' }, + ], + }, + + // ─── Flow 2: Bug Fix (with branching + interactions) ─────────────────────── + { + id: 'flow-bug-fix', + name: 'Bug Fix', + description: 'Bug report → environment choice → reproduce → test → fix → CI → PR', + category: 'ops', + nodes: [ + { id: 'b-start', nodeType: 'start', label: 'Bug Report', position: { x: 200, y: 20 } }, + + // Decision: environment + { id: 'b-env', nodeType: 'decision', label: 'Environment?', + interaction: { + kind: 'menu', prompt: 'Where to reproduce the bug?', + options: [ + { id: 'staging', label: 'Staging', description: 'Use shared staging environment (fast)', color: '#10b981' }, + { id: 'local', label: 'Local dev env', description: 'Reproduce on developer machine', color: '#60a5fa' }, + { id: 'deploy', label: 'Deploy test env', description: 'Deploy isolated environment (slower)', color: '#f59e0b' }, + ] + }, + position: { x: 180, y: 110 } }, + + { id: 'b-validate', nodeType: 'gate', label: 'Bug Valid?', maxRetries: 1, + interaction: { + kind: 'menu', prompt: 'Bug validation failed — what to do?', + options: [ + { id: 'info', label: 'Request more info', description: 'Ask reporter for steps to reproduce', color: '#60a5fa' }, + { id: 'assume', label: 'Proceed with assumptions', description: 'Continue based on description', color: '#f59e0b' }, + { id: 'close', label: 'Close as invalid', description: 'Mark bug as not reproducible', color: '#f87171' }, + ] + }, + position: { x: 182, y: 220 } }, + + { id: 'b-closed', nodeType: 'escalation',label: 'Closed (invalid)', position: { x: 400, y: 220 } }, + { id: 'b-find', nodeType: 'worker', label: 'Find Component', sublabel: 'script · ops', position: { x: 180, y: 340 } }, + { id: 'b-reproduce',nodeType: 'worker', label: 'Reproduce Bug', sublabel: 'hybrid · ops', position: { x: 180, y: 460 } }, + + // Decision: TDD or not? + { id: 'b-approach', nodeType: 'decision', label: 'Test approach?', + interaction: { + kind: 'menu', prompt: 'How do you want to approach the fix?', + options: [ + { id: 'tdd', label: 'Test-first (TDD)', description: 'Write failing test, then fix', color: '#10b981' }, + { id: 'impl', label: 'Implement first', description: 'Fix then add regression test', color: '#818cf8' }, + ] + }, + position: { x: 180, y: 570 } }, + + { id: 'b-test', nodeType: 'worker', label: 'Create Failing Test', sublabel: 'LLM · quality', position: { x: 30, y: 680 } }, + { id: 'b-fix', nodeType: 'worker', label: 'Implement Fix', sublabel: 'LLM · coding', position: { x: 180, y: 790 } }, + { id: 'b-gate-ci', nodeType: 'gate', label: 'CI Passes?', maxRetries: 3, + interaction: { + kind: 'menu', prompt: 'CI is failing — how to handle?', + options: [ + { id: 'retry', label: 'Fix and retry', description: 'Amend the implementation', color: '#818cf8' }, + { id: 'issue', label: 'Open follow-up', description: 'Merge with tech debt ticket', color: '#f59e0b' }, + ] + }, + position: { x: 182, y: 910 } }, + { id: 'b-pr', nodeType: 'worker', label: 'Create PR', sublabel: 'hybrid · platform', position: { x: 180, y: 1030 } }, + + // Human approval + { id: 'b-review', nodeType: 'human', label: 'Tech Lead Review', + interaction: { + kind: 'approval', prompt: 'Review the fix and approve or reject the PR.', + options: [ + { id: 'approve', label: 'Approve & merge', color: '#10b981' }, + { id: 'changes', label: 'Request changes', color: '#f59e0b' }, + ] + }, + position: { x: 180, y: 1140 } }, + { id: 'b-end', nodeType: 'end', label: 'Fixed', position: { x: 196, y: 1260 } }, + ], + edges: [ + { id: 'f1', source: 'b-start', target: 'b-env', edgeKind: 'default' }, + { id: 'f2', source: 'b-env', target: 'b-validate', edgeKind: 'branch', label: 'any env' }, + { id: 'f3', source: 'b-validate', target: 'b-find', edgeKind: 'pass', label: 'Valid' }, + { id: 'f4', source: 'b-validate', target: 'b-closed', edgeKind: 'fail', label: 'Close', branchOptionId: 'close' }, + { id: 'f4b', source: 'b-validate', target: 'b-find', edgeKind: 'pass', label: 'Assume', branchOptionId: 'assume' }, + { id: 'f5', source: 'b-find', target: 'b-reproduce',edgeKind: 'default' }, + { id: 'f6', source: 'b-reproduce',target: 'b-approach', edgeKind: 'default' }, + // TDD branch + { id: 'f7a', source: 'b-approach', target: 'b-test', edgeKind: 'branch', label: 'TDD', branchOptionId: 'tdd' }, + { id: 'f7b', source: 'b-test', target: 'b-fix', edgeKind: 'default' }, + // Impl-first branch + { id: 'f8', source: 'b-approach', target: 'b-fix', edgeKind: 'branch', label: 'Impl', branchOptionId: 'impl' }, + { id: 'f9', source: 'b-fix', target: 'b-gate-ci', edgeKind: 'default' }, + { id: 'f10', source: 'b-gate-ci', target: 'b-pr', edgeKind: 'pass', label: 'PASS' }, + { id: 'f11', source: 'b-gate-ci', target: 'b-fix', edgeKind: 'retry', label: 'retry' }, + { id: 'f12', source: 'b-pr', target: 'b-review', edgeKind: 'default' }, + { id: 'f13', source: 'b-review', target: 'b-end', edgeKind: 'pass', label: 'Approved', branchOptionId: 'approve' }, + { id: 'f14', source: 'b-review', target: 'b-fix', edgeKind: 'retry', label: 'Changes', branchOptionId: 'changes' }, + ], + }, + + // ─── Flow 3: Release Readiness ────────────────────────────────────────────── + { + id: 'flow-release-readiness', + name: 'Release Readiness', + description: 'Traceability → Security → Approval — with interactive gap resolution', + category: 'ops', + nodes: [ + { id: 'r-start', nodeType: 'start', label: 'Release Candidate', position: { x: 220, y: 20 } }, + { id: 'r-trace', nodeType: 'worker', label: 'Traceability Analysis', sublabel: 'hybrid · traceability', position: { x: 160, y: 110 } }, + { id: 'r-gate-trace', nodeType: 'gate', label: 'Coverage OK?', maxRetries: 2, + interaction: { + kind: 'menu', prompt: 'Traceability coverage is below threshold. How to proceed?', + options: [ + { id: 'fix', label: 'Fix coverage gaps', description: 'Run traceability_analysis with auto-fixes', color: '#818cf8' }, + { id: 'lower', label: 'Lower threshold', description: 'Adjust min-coverage for this release', color: '#f59e0b' }, + { id: 'block', label: 'Block release', description: 'Fail the release until gaps are resolved', color: '#f87171' }, + ] + }, + position: { x: 182, y: 230 } }, + { id: 'r-version', nodeType: 'decision', label: 'Version bump?', + interaction: { + kind: 'menu', prompt: 'What kind of version bump does this release require?', + options: [ + { id: 'patch', label: 'Patch (bug fixes)', description: 'x.x.N — no API changes', color: '#10b981' }, + { id: 'minor', label: 'Minor (new features)', description: 'x.N.0 — backwards compatible',color: '#60a5fa' }, + { id: 'major', label: 'Major (breaking)', description: 'N.0.0 — breaking API change', color: '#f87171' }, + ] + }, + position: { x: 182, y: 350 } }, + { id: 'r-sec', nodeType: 'worker', label: 'Security Analysis', sublabel: 'hybrid · security', position: { x: 160, y: 480 } }, + { id: 'r-gate-sec', nodeType: 'gate', label: 'Security OK?', maxRetries: 1, + interaction: { + kind: 'menu', prompt: 'Security issues found — how to handle?', + options: [ + { id: 'fix', label: 'Fix before release', description: 'Block until security issues resolved', color: '#f87171' }, + { id: 'accept', label: 'Accept with mitigations', description: 'Document and ship with workaround', color: '#f59e0b' }, + ] + }, + position: { x: 182, y: 600 } }, + { id: 'r-escalate', nodeType: 'escalation', label: 'Security Blocked', position: { x: 400, y: 600 } }, + { id: 'r-approval', nodeType: 'human', label: 'Tech Lead Approval', + interaction: { + kind: 'approval', prompt: 'Review the release readiness report and approve or reject.', + options: [ + { id: 'approve', label: 'Approve release', color: '#10b981' }, + { id: 'changes', label: 'Request changes', color: '#f59e0b' }, + { id: 'reject', label: 'Reject release', color: '#f87171' }, + ] + }, + position: { x: 160, y: 720 } }, + { id: 'r-end', nodeType: 'end', label: 'Released', position: { x: 196, y: 840 } }, + { id: 'r-blocked', nodeType: 'escalation', label: 'Release Blocked', position: { x: 400, y: 840 } }, + ], + edges: [ + { id: 'r1', source: 'r-start', target: 'r-trace', edgeKind: 'default' }, + { id: 'r2', source: 'r-trace', target: 'r-gate-trace',edgeKind: 'default' }, + { id: 'r3', source: 'r-gate-trace', target: 'r-version', edgeKind: 'pass', label: 'PASS' }, + { id: 'r4', source: 'r-gate-trace', target: 'r-trace', edgeKind: 'retry', label: 'Fix & retry', branchOptionId: 'fix' }, + { id: 'r5', source: 'r-gate-trace', target: 'r-version', edgeKind: 'pass', label: 'Lower', branchOptionId: 'lower' }, + { id: 'r6', source: 'r-version', target: 'r-sec', edgeKind: 'branch', label: 'any' }, + { id: 'r7', source: 'r-sec', target: 'r-gate-sec', edgeKind: 'default' }, + { id: 'r8', source: 'r-gate-sec', target: 'r-approval', edgeKind: 'pass', label: 'PASS' }, + { id: 'r9', source: 'r-gate-sec', target: 'r-escalate', edgeKind: 'fail', label: 'Block', branchOptionId: 'fix' }, + { id: 'r10',source: 'r-gate-sec', target: 'r-approval', edgeKind: 'pass', label: 'Accept', branchOptionId: 'accept' }, + { id: 'r11',source: 'r-approval', target: 'r-end', edgeKind: 'pass', label: 'Approved', branchOptionId: 'approve' }, + { id: 'r12',source: 'r-approval', target: 'r-trace', edgeKind: 'retry', label: 'Changes', branchOptionId: 'changes' }, + { id: 'r13',source: 'r-approval', target: 'r-blocked', edgeKind: 'fail', label: 'Rejected', branchOptionId: 'reject' }, + ], + }, +] + +// ─── Kit Definitions ───────────────────────────────────────────────────────── + +export const KIT_DEFS: KitDef[] = [ + { + id: 'kit-sdlc', + name: 'SDLC Kit', + description: 'Full software delivery lifecycle — PRD, Design, Decomposition, Feature Spec, Implementation, PR validation', + version: '2.1.0', + status: 'active', + category: 'sdlc', + workerCount: 14, + connectorCount: 0, + author: 'Constructor Fabric', + tags: ['sdlc', 'quality', 'traceability'], + installedAt: '2026-05-01T10:00:00Z', + workers: [ + { id: 'create_prd_worker', label: 'Create PRD', category: 'quality' }, + { id: 'create_design_worker', label: 'Create Design', category: 'quality' }, + { id: 'decompose_feature_worker', label: 'Decompose Feature', category: 'quality' }, + { id: 'create_feature_spec_worker', label: 'Create Feature Spec', category: 'quality' }, + { id: 'implement_code_worker', label: 'Implement Code', category: 'quality' }, + { id: 'create_adr_worker', label: 'Create ADR', category: 'quality' }, + { id: 'gap_analysis_validator', label: 'Gap Analysis', category: 'quality' }, + { id: 'pr_design_validator', label: 'PR Design Validator', category: 'quality' }, + { id: 'traceability_analysis', label: 'Traceability Analysis',category: 'traceability' }, + { id: 'stale_artifact_detection', label: 'Stale Detection', category: 'quality' }, + { id: 'create_pr_worker', label: 'Create Pull Request', category: 'platform' }, + // F-028: replaced reverse_engineer_worker with find_suspected_component (doc-defined) + { id: 'find_suspected_component', label: 'Find Suspected Component', category: 'quality' }, + { id: 'object_graph_retriever', label: 'Object Graph Retriever',category: 'retrieval' }, + // F-035: release_readiness_review is a Flow, not a plain Worker — listed for Kit inventory only + { id: 'release_readiness_review', label: 'Release Readiness', category: 'ops' }, + ], + }, + { + id: 'kit-github', + name: 'GitHub Connector', + description: 'Sync repositories, pull requests, branches, commits, and CI runs from GitHub', + version: '1.3.0', + status: 'active', + category: 'connector', + workerCount: 4, + connectorCount: 1, + author: 'Constructor Fabric', + tags: ['github', 'connector', 'ci'], + installedAt: '2026-05-01T10:30:00Z', + workers: [ + { id: 'github_sync_worker', label: 'GitHub Sync', category: 'platform' }, + { id: 'create_pr_worker', label: 'Create PR', category: 'platform' }, + { id: 'run_ci_worker', label: 'Run CI', category: 'ops' }, + { id: 'pr_status_worker', label: 'PR Status', category: 'ops' }, + ], + }, + { + id: 'kit-jira', + name: 'Jira Connector', + description: 'Sync tasks, epics, and bugs from Jira; write back on task state transitions', + version: '1.1.0', + status: 'active', + category: 'connector', + workerCount: 3, + connectorCount: 1, + author: 'Constructor Fabric', + tags: ['jira', 'connector', 'tasks'], + installedAt: '2026-05-02T09:00:00Z', + workers: [ + { id: 'jira_sync_worker', label: 'Jira Sync', category: 'platform' }, + { id: 'jira_create_task', label: 'Create Jira Task', category: 'platform' }, + { id: 'jira_update_status', label: 'Update Status', category: 'platform' }, + ], + }, + { + id: 'kit-saas', + name: 'SaaS Multitenant Kit', + description: 'Architecture patterns, validators, and workers for multi-tenant SaaS platforms', + version: '1.0.0', + latestVersion: '1.1.0', + status: 'update_available', + category: 'architecture', + workerCount: 8, + connectorCount: 0, + author: 'Constructor Fabric', + tags: ['saas', 'multitenant', 'rbac', 'security'], + installedAt: '2026-05-10T14:00:00Z', + workers: [ + { id: 'tenant_isolation_validator', label: 'Tenant Isolation Check', category: 'security' }, + { id: 'rbac_validator', label: 'RBAC Validator', category: 'security' }, + { id: 'multi_tenancy_analyzer', label: 'Multi-tenancy Analyzer', category: 'security' }, + { id: 'saas_perf_analyzer', label: 'SaaS Perf Analyzer', category: 'ops' }, + { id: 'billing_flow_validator', label: 'Billing Flow Validator', category: 'quality' }, + { id: 'api_gateway_validator', label: 'API Gateway Validator', category: 'quality' }, + { id: 'data_isolation_validator', label: 'Data Isolation Check', category: 'security' }, + { id: 'provisioning_worker', label: 'Provisioning Worker', category: 'ops' }, + ], + }, + { + id: 'kit-security', + name: 'Security Analysis Kit', + description: 'Security impact analysis, vulnerability scanning, dependency checks', + version: '0.9.0', + status: 'active', + category: 'security', + workerCount: 6, + connectorCount: 0, + author: 'Constructor Fabric', + tags: ['security', 'vulnerability', 'compliance'], + installedAt: '2026-05-15T11:00:00Z', + workers: [ + { id: 'security_impact_analysis', label: 'Security Impact Analysis', category: 'security' }, + { id: 'dependency_scan_worker', label: 'Dependency Scanner', category: 'security' }, + { id: 'sast_worker', label: 'SAST Analysis', category: 'security' }, + { id: 'secret_scan_worker', label: 'Secret Scanner', category: 'security' }, + { id: 'compliance_validator', label: 'Compliance Validator', category: 'security' }, + { id: 'pentest_advisor_worker', label: 'Pentest Advisor', category: 'security' }, + ], + }, +] + +// ─── Workspace Definitions ──────────────────────────────────────────────────── + +export const WORKSPACE_DEFS: WorkspaceDef[] = [ + { + id: 'ws-billing', + name: 'Billing Service', + description: 'Multi-tenant billing service with Stripe integration', + status: 'active', + sources: [ + { id: 'src-1', url: 'github.com/acme/billing-service', role: 'main', branch: 'main', lastSyncedAt: '2026-07-08T09:15:00Z' }, + { id: 'src-2', url: 'github.com/acme/billing-docs', role: 'docs', branch: 'main', lastSyncedAt: '2026-07-08T09:10:00Z' }, + ], + installedKitIds: ['kit-sdlc', 'kit-github', 'kit-jira', 'kit-saas', 'kit-security'], + automationLevel: 'approved_automation', + lastSyncedAt: '2026-07-08T09:15:00Z', + objectCount: 47, + }, + { + id: 'ws-auth', + name: 'Auth Platform', + description: 'Identity and access management platform', + status: 'offline', + sources: [ + { id: 'src-3', url: 'github.com/acme/auth-platform', role: 'main', branch: 'main', lastSyncedAt: '2026-07-01T14:00:00Z' }, + ], + installedKitIds: ['kit-sdlc', 'kit-github', 'kit-security'], + automationLevel: 'recommendations', + lastSyncedAt: '2026-07-01T14:00:00Z', + objectCount: 31, + }, + { + id: 'ws-gateway', + name: 'API Gateway', + description: 'Central API gateway and routing layer', + status: 'syncing', + sources: [ + { id: 'src-4', url: 'github.com/acme/api-gateway', role: 'main', branch: 'main', lastSyncedAt: '2026-07-08T08:00:00Z' }, + { id: 'src-5', url: 'github.com/acme/gateway-config', role: 'platform', branch: 'main', lastSyncedAt: '2026-07-08T08:00:00Z' }, + ], + installedKitIds: ['kit-sdlc', 'kit-github'], + automationLevel: 'recommendations', + lastSyncedAt: '2026-07-08T08:00:00Z', + objectCount: 18, + }, +] + +// ─── Mock Worker Run History ────────────────────────────────────────────────── + +import type { WorkerRun } from '../types/domain' + +function h(id: string, workerId: string, workerLabel: string, objectId: string, objectTitle: string, + state: 'done'|'failed', startedAt: string, durationMs: number, + costUsd: number, tokensIn: number, tokensOut: number, model: string, + output?: string, error?: string): WorkerRun { + const endDate = new Date(new Date(startedAt).getTime() + durationMs) + return { + id, workerId, workerLabel, objectId, objectTitle, + state, progress: state === 'done' ? 100 : 0, + startedAt, completedAt: endDate.toISOString(), + costUsd, tokensIn, tokensOut, model, durationMs, + output, error, + } +} + +export const MOCK_WORKER_RUNS: WorkerRun[] = [ + // PRD-001 — Billing Service v2 + h('hr-001','create_prd_worker','Create PRD','prd-001','Billing Service v2','done','2026-06-01T09:12:00Z',5200,0.38,12400,3100,'claude-sonnet-4-6','PRD created: 8 functional requirements, 4 non-functional, 6 use cases, 8 success criteria. Coverage: 100% actors defined.'), + h('hr-002','gap_analysis_validator','Gap Analysis','prd-001','Billing Service v2','done','2026-06-01T09:18:00Z',2800,0.09,3200,820,'claude-haiku-4-5','Validation passed. All fr[] have success_criteria. R-005 has no linked test case — recommendation created.'), + h('hr-003','gap_analysis_validator','Gap Analysis','prd-001','Billing Service v2','failed','2026-06-10T14:30:00Z',1900,0.07,2900,410,'claude-haiku-4-5',undefined,'Validation failed: 1 use-case references fr[] ID that does not exist. Retried manually.'), + h('hr-004','traceability_analysis','Traceability Analysis','prd-001','Billing Service v2','done','2026-06-15T10:05:00Z',3400,0.12,4100,980,'claude-sonnet-4-6','Traceability: PRD → Design coverage 87%. R-003 fully traced to design + 2 tasks. R-005 not covered in any task.'), + + // Design-001 — Billing Service Architecture + h('hr-010','object_graph_retriever','Object Graph Retriever','design-001','Billing Service Architecture','done','2026-06-02T10:00:00Z',1200,0.04,1800,240,'claude-haiku-4-5','Retrieved: 8 relevant Objects — PRD, 2 ADRs, 4 existing components, workspace config.'), + h('hr-011','create_design_worker','Create Design','design-001','Billing Service Architecture','done','2026-06-02T10:02:00Z',8400,0.61,18200,5200,'claude-sonnet-4-6','Design created: 6 components, 12 API interfaces, 3 sequence diagrams. Architecture drivers linked to ADR-001, ADR-002.'), + h('hr-012','gap_analysis_validator','Gap Analysis','design-001','Billing Service Architecture','failed','2026-06-02T10:16:00Z',2100,0.08,2800,380,'claude-haiku-4-5',undefined,'Validation failed: component[invoice_generator] missing input/output schema. Fixed and re-run.'), + h('hr-013','gap_analysis_validator','Gap Analysis','design-001','Billing Service Architecture','done','2026-06-02T10:20:00Z',2400,0.09,3100,720,'claude-haiku-4-5','Validation passed. All 8 prd fr[] referenced in component[]. Event-driven pattern flagged as not yet implemented in code.'), + h('hr-014','traceability_analysis','Traceability Analysis','design-001','Billing Service Architecture','done','2026-06-14T09:00:00Z',3100,0.11,3900,850,'claude-sonnet-4-6','Design → Code traceability: 92%. 5/6 components have merged PRs. billing_events bus — no implementation found.'), + + // ADR-001 + h('hr-020','object_graph_retriever','Object Graph Retriever','adr-001','Event-driven billing architecture','done','2026-05-30T14:00:00Z',900,0.03,1200,180,'claude-haiku-4-5','Retrieved: 3 related ADRs, existing event bus docs, competitor analysis.'), + h('hr-021','create_adr_worker','Create ADR','adr-001','Event-driven billing architecture','done','2026-05-30T14:02:00Z',3800,0.24,7400,2100,'claude-sonnet-4-6','ADR created: 3 options analyzed, event-driven architecture selected. Positive consequences: scalability, loose coupling. Negative: complexity.'), + h('hr-022','gap_analysis_validator','Gap Analysis','adr-001','Event-driven billing architecture','done','2026-05-30T14:08:00Z',1600,0.05,1900,420,'claude-haiku-4-5','Validation passed. >= 2 options present, decision outcome non-empty, consequences complete.'), + + // ADR-002 + h('hr-030','create_adr_worker','Create ADR','adr-002','PostgreSQL for billing ledger','done','2026-05-31T09:00:00Z',3200,0.21,6800,1900,'claude-sonnet-4-6','ADR created: PostgreSQL vs CockroachDB vs Cassandra. PostgreSQL selected for ACID compliance and operational familiarity.'), + h('hr-031','gap_analysis_validator','Gap Analysis','adr-002','PostgreSQL for billing ledger','done','2026-05-31T09:07:00Z',1500,0.05,1800,380,'claude-haiku-4-5','Validation passed. No migration plan documented — info recommendation created.'), + + // Task-001 — Stripe Webhook Handler + h('hr-040','create_feature_spec_worker','Create Feature Spec','task-001','Implement Stripe Webhook Handler','done','2026-06-05T11:00:00Z',6100,0.44,14200,4100,'claude-sonnet-4-6','Feature spec created: 3 GIVEN/WHEN/THEN flows, 2 algo blocks, 4 test scenarios (2 happy path, 2 error cases).'), + h('hr-041','implement_code_worker','Implement Code','task-001','Implement Stripe Webhook Handler','done','2026-06-06T09:00:00Z',9200,0.71,22100,6800,'claude-sonnet-4-6','Implementation: StripeWebhookHandler class, signature validation, event routing. 847 lines. @cpt- markers for all 3 flow IDs.'), + h('hr-042','pr_design_validator','PR Design Validator','task-001','Implement Stripe Webhook Handler','failed','2026-06-06T10:30:00Z',3400,0.14,4200,920,'claude-haiku-4-5',undefined,'Validation failed: handlePaymentFailed missing domain event emission. Fix required.'), + h('hr-043','implement_code_worker','Implement Code','task-001','Implement Stripe Webhook Handler','done','2026-06-06T11:00:00Z',4100,0.32,9800,2900,'claude-sonnet-4-6','Fix applied: added billing.payment_failed event emission. Updated tests.'), + h('hr-044','pr_design_validator','PR Design Validator','task-001','Implement Stripe Webhook Handler','done','2026-06-06T11:45:00Z',2900,0.10,3600,780,'claude-haiku-4-5','Validation passed. Evidence attached. PR ready for review.'), + + // Task-002 — Invoice Generation (draft, less history) + h('hr-050','gap_analysis_validator','Gap Analysis','task-002','Implement Invoice Generation Worker','failed','2026-06-08T14:00:00Z',1800,0.06,2200,290,'claude-haiku-4-5',undefined,'Validation failed: feature_spec not approved. No test scenarios defined. 2 critical gaps found.'), + + // Task-003 — Schema Migration + h('hr-060','implement_code_worker','Implement Code','task-003','Billing Ledger Schema Migration','done','2026-06-03T09:00:00Z',5800,0.42,13200,3900,'claude-sonnet-4-6','Migration created: CREATE TABLE billing_ledger, 3 indices, UNIQUE constraint on (tenant_id, invoice_id). Rollback script included.'), + h('hr-061','gap_analysis_validator','Gap Analysis','task-003','Billing Ledger Schema Migration','done','2026-06-03T10:00:00Z',1400,0.04,1600,340,'claude-haiku-4-5','Validation passed. Migration is idempotent. All constraints verified.'), + h('hr-062','traceability_analysis','Traceability Analysis','task-003','Billing Ledger Schema Migration','done','2026-06-03T10:10:00Z',2200,0.08,2800,560,'claude-haiku-4-5','Traceability: task-003 → design component[billing_ledger]. Coverage: 100%.'), + + // fspec-001 — Stripe Webhook + h('hr-070','create_feature_spec_worker','Create Feature Spec','fspec-001','Stripe Webhook Flow','done','2026-06-04T13:00:00Z',5900,0.43,13800,4000,'claude-sonnet-4-6','Feature spec: 3 flows, 4 algo blocks, 6 test scenarios. All flows have >=1 happy + >=1 error case.'), + h('hr-071','gap_analysis_validator','Gap Analysis','fspec-001','Stripe Webhook Flow','done','2026-06-04T14:02:00Z',2100,0.07,2400,580,'claude-haiku-4-5','Validation passed. 1 error scenario missing repro steps — info recommendation. Evidence attached.'), + + // fspec-002 — Invoice Generation (draft, problems) + h('hr-080','create_feature_spec_worker','Create Feature Spec','fspec-002','Invoice Generation Flow','failed','2026-06-09T10:00:00Z',4200,0.31,9800,1200,'claude-sonnet-4-6',undefined,'Generation failed: insufficient context. No approved design components referenced. Re-run after design approval.'), + h('hr-081','gap_analysis_validator','Gap Analysis','fspec-002','Invoice Generation Flow','failed','2026-06-09T11:00:00Z',1600,0.05,1900,280,'claude-haiku-4-5',undefined,'Validation failed: no test scenarios, missing algo blocks for invoice calculation logic.'), + + // PR-001 — feat/stripe-webhook-handler + h('hr-090','pr_design_validator','PR Design Validator','pr-001','feat/stripe-webhook-handler','failed','2026-06-06T10:30:00Z',3400,0.14,4200,920,'claude-haiku-4-5',undefined,'PR validation failed: handlePaymentFailed missing domain event emission.'), + h('hr-091','pr_design_validator','PR Design Validator','pr-001','feat/stripe-webhook-handler','done','2026-06-06T11:45:00Z',2900,0.10,3600,780,'claude-haiku-4-5','PR validation passed. Conformance to design confirmed. Evidence attached.'), + h('hr-092','security_impact_analysis','Security Impact Analysis','pr-001','feat/stripe-webhook-handler','done','2026-06-07T09:00:00Z',3800,0.14,4600,1100,'claude-haiku-4-5','Security review: HMAC validation present. Webhook secret properly managed. No PII logged. Recommendation: add rate limiting.'), + + // Incident-001 + h('hr-100','gap_analysis_validator','Gap Analysis','incident-001','Billing duplicate charge INC-441','failed','2026-07-06T08:00:00Z',1200,0.04,1400,180,'claude-haiku-4-5',undefined,'Analysis failed: root cause not documented. No postmortem linked. 2 critical gaps.'), +] From 2d346d13ebbc4cec8990a020adb07b96ee98b856 Mon Sep 17 00:00:00 2001 From: ainetx Date: Wed, 8 Jul 2026 14:46:50 +0300 Subject: [PATCH 072/106] fix(v2/poc/ui-1): apply store review findings F-001 F-003 F-005 F-006 F-020 F-021 F-023 - F-001: fix stalenessScore arithmetic to float (subtract 0.10, not 10) - F-003: split dismissWorkerRun into cancelWorkerRun (sets aborted state, keeps run) and dismissRunToast (UI-only dismissed set) - F-005: acceptRecommendation sets 'accepted' first, 500ms Re-check delay before 'executing'; guard returns to 'pending' if missing workerDef or targetObjectId - F-006: stopFlow transitions FlowRun to aborted, preserves in completedFlowRuns - F-020: gate node follows 'fail' edge when retries exhausted - F-021: runFlow enforces entryConstraints (typeId + requiredStates) - F-023: respondToInteraction guards on awaiting_input state Co-authored-by: Constructor Studio <291158726+constructor-studio[bot]@users.noreply.github.com> Studio-Generated-By: Constructor Studio Studio-Source-Repo: https://github.com/constructorfabric/studio Constructor-Fabric: https://github.com/constructorfabric Signed-off-by: ainetx --- v2/poc/ui-1/src/store/app-store.ts | 752 +++++++++++++++++++++++++++++ 1 file changed, 752 insertions(+) create mode 100644 v2/poc/ui-1/src/store/app-store.ts diff --git a/v2/poc/ui-1/src/store/app-store.ts b/v2/poc/ui-1/src/store/app-store.ts new file mode 100644 index 00000000..7754621b --- /dev/null +++ b/v2/poc/ui-1/src/store/app-store.ts @@ -0,0 +1,752 @@ +import { create } from 'zustand' +import type { + StudioObject, + WorkerRun, + WorkerRunState, + FlowRun, + FlowStepStatus, + FlowExecState, + FlowGraphDef, + FlowNodeExecState, + FlowPendingInteraction, + Recommendation, + AppView, +} from '../types/domain' +import { + MOCK_OBJECTS, + MOCK_RECOMMENDATIONS, + MOCK_WORKER_RUNS, + FLOW_DEFS, + FLOW_GRAPH_DEFS, + WORKER_DEFS, + getWorkersForObject, +} from '../data/mock-data' +import { FILE_CONTENTS, FILE_TREE } from '../data/file-mock-data' +import type { FileNode } from '../types/domain' +import type { LineAction } from '../types/domain' + +interface AppState { + // Data + objects: StudioObject[] + workerRuns: WorkerRun[] + activeFlowRun: FlowRun | null + completedFlowRuns: FlowRun[] + flowExecState: FlowExecState | null + recommendations: Recommendation[] + + // UI State + selectedObjectId: string | null + activeView: AppView + activeTab: string + pendingInteractionRunId: string | null + isSimulating: boolean + sidebarCollapsed: boolean + chatOpen: boolean + chatHeight: number + dismissedRunIds: string[] + // File view state + openFileId: string | null + fileContents: Record + modifiedFiles: Set + expandedFolders: Set + lineAction: LineAction + + // Actions + selectObject: (id: string | null) => void + setActiveView: (view: AppView) => void + setActiveTab: (tab: string) => void + setSidebarCollapsed: (collapsed: boolean) => void + toggleChat: () => void + setChatHeight: (h: number) => void + // File view actions + openFile: (fileId: string) => void + closeFile: () => void + updateFileContent: (fileId: string, content: string) => void + saveFile: (fileId: string) => void + toggleFolder: (folderId: string) => void + setLineAction: (action: LineAction) => void + + // Worker actions + runWorker: (workerId: string, objectId: string) => string + runWorkerOnFile: (workerId: string, fileId: string) => string + respondToInteraction: (runId: string, response: string) => void + cancelWorkerRun: (runId: string, cascade?: boolean) => void + dismissRunToast: (runId: string) => void + + // Flow actions + runFlow: (flowId: string) => void + stopFlow: () => void + startFlowGraph: (flowId: string) => void + stopFlowGraph: () => void + respondToFlowInteraction: (optionId: string, textInput?: string) => void + + // Recommendation actions + acceptRecommendation: (recId: string) => void + dismissRecommendation: (recId: string) => void + + // Simulation + simulateFullPipeline: () => void +} + +let runIdCounter = 1000 + +function genId(): string { + return `run-${Date.now()}-${runIdCounter++}` +} + +function nowIso(): string { + return new Date().toISOString() +} + +// Flow interaction resume callback +let flowResumeCallback: ((optionId: string) => void) | null = null + +const FILE_TO_OBJECT: Record = { + 'file-prd': 'prd-001', + 'file-design': 'design-001', + 'file-adr-001': 'adr-001', + 'file-adr-002': 'adr-002', + 'file-feat-stripe': 'fspec-001', + 'file-feat-invoice': 'fspec-002', + 'file-webhook-handler': 'pr-001', + 'file-webhook-spec': 'pr-001', +} + +function findFileInTree(nodes: FileNode[], id: string): FileNode | null { + for (const n of nodes) { + if (n.id === id) return n + if (n.children) { const f = findFileInTree(n.children, id); if (f) return f } + } + return null +} + +export const useAppStore = create((set, get) => ({ + // ─── Initial State ────────────────────────────────────────────────────────── + objects: MOCK_OBJECTS, + workerRuns: MOCK_WORKER_RUNS, + activeFlowRun: null, + completedFlowRuns: [], + flowExecState: null, + recommendations: MOCK_RECOMMENDATIONS, + selectedObjectId: null, + activeView: 'graph', + activeTab: 'overview', + pendingInteractionRunId: null, + isSimulating: false, + sidebarCollapsed: false, + chatOpen: false, + chatHeight: 320, + dismissedRunIds: [], + openFileId: null, + fileContents: {}, + modifiedFiles: new Set(), + expandedFolders: new Set(['folder-docs', 'folder-src', 'folder-billing']), + lineAction: { visible: false }, + + // ─── UI Actions ───────────────────────────────────────────────────────────── + selectObject: (id) => set({ selectedObjectId: id, activeTab: 'overview' }), + setActiveView: (view) => set({ activeView: view }), + setActiveTab: (tab) => set({ activeTab: tab }), + setSidebarCollapsed: (collapsed) => set({ sidebarCollapsed: collapsed }), + toggleChat: () => set(s => ({ chatOpen: !s.chatOpen })), + setChatHeight: (h) => set({ chatHeight: h }), + + // ─── File View Actions ─────────────────────────────────────────────────────── + openFile: (fileId) => { + const file = findFileInTree(FILE_TREE, fileId) + const linkedObjectId = FILE_TO_OBJECT[fileId] ?? null + set(state => ({ + openFileId: fileId, + fileContents: fileId in state.fileContents + ? state.fileContents + : { ...state.fileContents, [fileId]: FILE_CONTENTS[fileId] ?? '' }, + selectedObjectId: linkedObjectId ?? state.selectedObjectId, + activeTab: linkedObjectId ? 'overview' : state.activeTab, + })) + }, + closeFile: () => set({ openFileId: null }), + updateFileContent: (fileId, content) => set(state => ({ + fileContents: { ...state.fileContents, [fileId]: content }, + modifiedFiles: new Set([...state.modifiedFiles, fileId]) + })), + saveFile: (fileId) => set(state => { + const next = new Set(state.modifiedFiles) + next.delete(fileId) + return { modifiedFiles: next } + }), + toggleFolder: (folderId) => set(state => { + const next = new Set(state.expandedFolders) + if (next.has(folderId)) next.delete(folderId) + else next.add(folderId) + return { expandedFolders: next } + }), + setLineAction: (action) => set({ lineAction: action }), + + // ─── Worker Run ───────────────────────────────────────────────────────────── + runWorker: (workerId, objectId) => { + const workerDef = WORKER_DEFS.find(w => w.id === workerId) + const obj = get().objects.find(o => o.id === objectId) + if (!workerDef || !obj) return '' + + const runId = genId() + const run: WorkerRun = { + id: runId, + workerId, + workerLabel: workerDef.label, + objectId, + objectTitle: obj.title, + state: 'pending', + progress: 0, + startedAt: nowIso(), + } + + set(state => ({ workerRuns: [run, ...state.workerRuns] })) + + // Simulate pending → running + setTimeout(() => { + set(state => ({ + workerRuns: state.workerRuns.map(r => + r.id === runId ? { ...r, state: 'running' as WorkerRunState, progress: 10 } : r + ), + })) + + // Progress updates + const progressInterval = setInterval(() => { + const current = get().workerRuns.find(r => r.id === runId) + if (!current || current.state !== 'running') { + clearInterval(progressInterval) + return + } + const nextProgress = Math.min(current.progress + Math.random() * 15 + 5, workerDef.interaction ? 70 : 95) + set(state => ({ + workerRuns: state.workerRuns.map(r => + r.id === runId ? { ...r, progress: nextProgress } : r + ), + })) + if (nextProgress >= (workerDef.interaction ? 70 : 95)) { + clearInterval(progressInterval) + } + }, 400) + + if (workerDef.interaction) { + // Pause for interaction after ~2s + setTimeout(() => { + clearInterval(progressInterval) + set(state => ({ + workerRuns: state.workerRuns.map(r => + r.id === runId + ? { ...r, state: 'awaiting_input' as WorkerRunState, progress: 70, interaction: workerDef.interaction } + : r + ), + pendingInteractionRunId: runId, + })) + }, 2200) + } else { + // Complete after ~3s + setTimeout(() => { + clearInterval(progressInterval) + finishRun(runId, objectId, get, set) + }, 3000) + } + }, 600) + + return runId + }, + + runWorkerOnFile: (workerId, fileId) => { + const objectId = FILE_TO_OBJECT[fileId] + if (!objectId) { + // No linked object — still run but with first available matching object + const workerDef = WORKER_DEFS.find(w => w.id === workerId) + if (!workerDef) return '' + const obj = get().objects[0] + if (!obj) return '' + return get().runWorker(workerId, obj.id) + } + return get().runWorker(workerId, objectId) + }, + + respondToInteraction: (runId, response) => { + // F-023: guard — only valid from awaiting_input state + const run = get().workerRuns.find(r => r.id === runId) + if (!run || run.state !== 'awaiting_input') return + + set(state => ({ + workerRuns: state.workerRuns.map(r => + r.id === runId + ? { ...r, state: 'running' as WorkerRunState, progress: 75, interactionResponse: response } + : r + ), + pendingInteractionRunId: null, + })) + + // Continue to completion + const progressInterval2 = setInterval(() => { + const current = get().workerRuns.find(r => r.id === runId) + if (!current || current.state !== 'running') { + clearInterval(progressInterval2) + return + } + const nextProgress = Math.min(current.progress + Math.random() * 10 + 5, 95) + set(state => ({ + workerRuns: state.workerRuns.map(r => + r.id === runId ? { ...r, progress: nextProgress } : r + ), + })) + if (nextProgress >= 95) clearInterval(progressInterval2) + }, 300) + + setTimeout(() => { + clearInterval(progressInterval2) + const current = get().workerRuns.find(r => r.id === runId) + if (current) finishRun(runId, current.objectId, get, set) + }, 2000) + }, + + // F-003: cancelWorkerRun — sets run to aborted state, preserves it in the list + cancelWorkerRun: (runId, cascade) => { + set(state => ({ + workerRuns: state.workerRuns.map(r => { + if (r.id === runId) { + // cancelledBy is not in the WorkerRun type; would need schema extension for production + return { ...r, state: 'aborted' as WorkerRunState, completedAt: nowIso() } + } + // If cascade=true, abort child runs (runs where parentRunId === runId, if tracked) + // WorkerRun does not currently have a parentRunId field; cascade is a no-op for children + return r + }), + pendingInteractionRunId: state.pendingInteractionRunId === runId ? null : state.pendingInteractionRunId, + })) + }, + + // F-003: dismissRunToast — UI-only action to track which run toasts have been dismissed + dismissRunToast: (runId) => { + set(state => ({ + dismissedRunIds: state.dismissedRunIds.includes(runId) + ? state.dismissedRunIds + : [...state.dismissedRunIds, runId], + })) + }, + + // ─── Flow Actions ──────────────────────────────────────────────────────────── + runFlow: (flowId) => { + const flowDef = FLOW_DEFS.find(f => f.id === flowId) + if (!flowDef) return + + // F-021: entryConstraints enforcement + if (flowDef.entryConstraints && flowDef.entryConstraints.length > 0) { + const targetObj = get().objects.find(o => o.id === get().selectedObjectId) + const constraintViolation = flowDef.entryConstraints.find(c => { + if (c.typeId && targetObj?.typeId !== c.typeId) return true + if (c.requiredStates && targetObj && !c.requiredStates.includes(targetObj.state)) return true + return false + }) + if (constraintViolation) { + console.warn(`Flow ${flowId} entryConstraints not met`) + return // Do not start the flow + } + } + + const flowRunId = genId() + const initialStepStatus: Record = {} + flowDef.steps.forEach(s => { initialStepStatus[s.id] = 'pending' }) + + const flowRun: FlowRun = { + id: flowRunId, + flowId, + flowLabel: flowDef.label, + state: 'running', + completedSteps: [], + skippedSteps: [], + activeStepId: flowDef.steps[0]?.id, + stepStatus: initialStepStatus, + startedAt: nowIso(), + } + + set({ activeFlowRun: flowRun, activeView: 'flows' }) + + // Simulate steps + let stepIndex = 0 + const runNextStep = () => { + const currentFlow = get().activeFlowRun + if (!currentFlow || currentFlow.state !== 'running') return + if (stepIndex >= flowDef.steps.length) { + set(state => ({ + activeFlowRun: state.activeFlowRun + ? { ...state.activeFlowRun, state: 'done', completedAt: nowIso(), activeStepId: undefined } + : null, + })) + return + } + + const step = flowDef.steps[stepIndex] + // Set current step running + set(state => ({ + activeFlowRun: state.activeFlowRun + ? { + ...state.activeFlowRun, + activeStepId: step.id, + stepStatus: { ...state.activeFlowRun.stepStatus, [step.id]: 'running' }, + } + : null, + })) + + setTimeout(() => { + // Complete step + set(state => ({ + activeFlowRun: state.activeFlowRun + ? { + ...state.activeFlowRun, + completedSteps: [...state.activeFlowRun.completedSteps, step.id], + stepStatus: { ...state.activeFlowRun.stepStatus, [step.id]: 'done' }, + } + : null, + })) + stepIndex++ + setTimeout(runNextStep, 400) + }, 1800) + } + + setTimeout(runNextStep, 300) + }, + + // F-006: stopFlow — transition FlowRun to aborted instead of nulling it + stopFlow: () => { + const current = get().activeFlowRun + if (current) { + const abortedRun: FlowRun = { ...current, state: 'aborted' as const, completedAt: nowIso() } + set(state => ({ + activeFlowRun: null, + completedFlowRuns: [...state.completedFlowRuns, abortedRun], + })) + } + }, + + stopFlowGraph: () => { + set({ flowExecState: null }) + }, + + respondToFlowInteraction: (optionId: string, textInput?: string) => { + set(state => { + if (!state.flowExecState?.pendingInteraction) return state + const nodeId = state.flowExecState.pendingInteraction.nodeId + return { + flowExecState: { + ...state.flowExecState, + status: 'running', + pendingInteraction: undefined, + takenBranches: { ...state.flowExecState.takenBranches, [nodeId]: optionId }, + inputResponses: textInput ? { ...state.flowExecState.inputResponses, [nodeId]: textInput } : state.flowExecState.inputResponses, + nodeStates: { ...state.flowExecState.nodeStates, [nodeId]: optionId === 'approve' || optionId === 'fix' || optionId === 'author' || optionId === 'import' || optionId === 'staging' || optionId === 'local' || optionId === 'deploy' || optionId === 'dependency' || optionId === 'risk' || optionId === 'value' || optionId === 'tdd' || optionId === 'impl' || optionId === 'patch' || optionId === 'minor' || optionId === 'major' || optionId === 'accept' || optionId === 'lower' ? 'done' : optionId === 'escalate' || optionId === 'close' || optionId === 'block' || optionId === 'reject' ? 'failed' : 'done' }, + } + } + }) + if (flowResumeCallback) { flowResumeCallback(optionId); flowResumeCallback = null } + }, + + startFlowGraph: (flowId: string) => { + const flowMaybe = FLOW_GRAPH_DEFS.find((f: FlowGraphDef) => f.id === flowId) + if (!flowMaybe) return + const flow: FlowGraphDef = flowMaybe + + const nodeStates: Record = {} + flow.nodes.forEach(n => { nodeStates[n.id] = 'idle' }) + + set({ + flowExecState: { + flowId, + status: 'running', + nodeStates, + retryCounters: {}, + currentNodeId: null, + producedArtifacts: [], + startedAt: Date.now(), + takenBranches: {}, + inputResponses: {}, + }, + activeView: 'flows', + }) + + // Async step-by-step execution with pauses for user interactions + const runStep = async (nodeId: string, takenBranches: Record): Promise => { + const node = flow.nodes.find(n => n.id === nodeId) + if (!node) return + + const setNode = (state: FlowNodeExecState) => set(s => ({ + flowExecState: s.flowExecState ? { ...s.flowExecState, nodeStates: { ...s.flowExecState.nodeStates, [nodeId]: state }, currentNodeId: nodeId } : null + })) + + const addArtifact = (label: string, nodeType: string) => set(s => ({ + flowExecState: s.flowExecState ? { ...s.flowExecState, producedArtifacts: [...s.flowExecState.producedArtifacts, { label, nodeType, nodeId }] } : null + })) + + const waitForInteraction = (pending: FlowPendingInteraction): Promise => { + set(s => ({ flowExecState: s.flowExecState ? { ...s.flowExecState, status: 'waiting_input', pendingInteraction: pending } : null })) + return new Promise(resolve => { flowResumeCallback = resolve }) + } + + const sleep = (ms: number) => new Promise(r => setTimeout(r, ms)) + + if (node.nodeType === 'start') { + setNode('done') + await sleep(300) + const next = flow.edges.find(e => e.source === nodeId)?.target + if (next) await runStep(next, takenBranches) + return + } + + if (node.nodeType === 'end') { + setNode('done') + await sleep(400) + set(s => ({ flowExecState: s.flowExecState ? { ...s.flowExecState, status: 'done', currentNodeId: null } : null })) + return + } + + if (node.nodeType === 'escalation') { + setNode('done') + await sleep(500) + set(s => ({ flowExecState: s.flowExecState ? { ...s.flowExecState, status: 'done', currentNodeId: null } : null })) + return + } + + if (node.nodeType === 'decision') { + setNode('running') + await sleep(400) + // Always requires interaction + const chosen = await waitForInteraction({ nodeId, interaction: node.interaction! }) + const updatedBranches = { ...takenBranches, [nodeId]: chosen } + set(s => ({ flowExecState: s.flowExecState ? { ...s.flowExecState, status: 'running', takenBranches: updatedBranches, nodeStates: { ...s.flowExecState.nodeStates, [nodeId]: 'done' } } : null })) + // Follow branch edge + const branchEdge = flow.edges.find(e => e.source === nodeId && (e.branchOptionId === chosen || (!e.branchOptionId && (e.edgeKind === 'branch' || e.edgeKind === 'default')))) + if (branchEdge) await runStep(branchEdge.target, updatedBranches) + return + } + + if (node.nodeType === 'worker' || node.nodeType === 'human') { + setNode('running') + const dur = node.nodeType === 'human' ? 800 : (1200 + Math.random() * 800) + await sleep(dur) + // Mid-run interaction? + let chosen: string | undefined + if (node.interaction) { + chosen = await waitForInteraction({ nodeId, interaction: node.interaction }) + set(s => ({ flowExecState: s.flowExecState ? { ...s.flowExecState, status: 'running', takenBranches: { ...s.flowExecState.takenBranches, [nodeId]: chosen! } } : null })) + await sleep(600) + } + setNode('done') + addArtifact(node.label, node.nodeType) + await sleep(300) + const next = flow.edges.find(e => e.source === nodeId && e.edgeKind === 'default')?.target + if (next) await runStep(next, { ...takenBranches, ...(chosen ? { [nodeId]: chosen } : {}) }) + return + } + + if (node.nodeType === 'gate') { + const maxRetries = node.maxRetries ?? 2 + const retryCount = (get().flowExecState?.retryCounters[nodeId] ?? 0) + setNode('running') + await sleep(900) + + const willFail = Math.random() < 0.45 && retryCount < maxRetries + if (willFail) { + // Ask user how to handle failure via interaction + if (node.interaction) { + const chosen = await waitForInteraction({ nodeId, interaction: node.interaction }) + set(s => ({ + flowExecState: s.flowExecState ? { + ...s.flowExecState, status: 'running', + nodeStates: { ...s.flowExecState.nodeStates, [nodeId]: 'retrying' }, + retryCounters: { ...s.flowExecState.retryCounters, [nodeId]: retryCount + 1 }, + takenBranches: { ...s.flowExecState.takenBranches, [nodeId]: chosen }, + } : null + })) + // Route based on choice + if (chosen === 'escalate' || chosen === 'close' || chosen === 'block' || chosen === 'reject') { + const failEdge = flow.edges.find(e => e.source === nodeId && e.edgeKind === 'fail') + if (failEdge) await runStep(failEdge.target, { ...takenBranches, [nodeId]: chosen }) + return + } + if (chosen === 'risk' || chosen === 'accept' || chosen === 'lower') { + // Accept risk — continue to pass path + set(s => ({ flowExecState: s.flowExecState ? { ...s.flowExecState, nodeStates: { ...s.flowExecState.nodeStates, [nodeId]: 'passed' } } : null })) + await sleep(400) + const passEdge = flow.edges.find(e => e.source === nodeId && e.edgeKind === 'pass' && !e.branchOptionId) + if (passEdge) await runStep(passEdge.target, takenBranches) + return + } + // 'fix' or default: retry + const retryEdge = flow.edges.find(e => e.source === nodeId && e.edgeKind === 'retry') + if (retryEdge) { + await runStep(retryEdge.target, takenBranches) + await sleep(400) + // Re-run this gate (simplified: just pass) + } + } else { + set(s => ({ flowExecState: s.flowExecState ? { ...s.flowExecState, nodeStates: { ...s.flowExecState.nodeStates, [nodeId]: 'retrying' }, retryCounters: { ...s.flowExecState.retryCounters, [nodeId]: retryCount + 1 } } : null })) + const retryEdge = flow.edges.find(e => e.source === nodeId && e.edgeKind === 'retry') + if (retryEdge) { await runStep(retryEdge.target, takenBranches); await sleep(400) } + } + } + + // F-020: when retries are exhausted, follow the 'fail' edge instead of always passing + if (retryCount >= maxRetries) { + const failTarget = flow.edges.find(e => e.source === nodeId && e.edgeKind === 'fail')?.target + if (failTarget) { + set(s => ({ flowExecState: s.flowExecState ? { ...s.flowExecState, nodeStates: { ...s.flowExecState.nodeStates, [nodeId]: 'failed' } } : null })) + await sleep(800) + await runStep(failTarget, takenBranches) + return + } + // Only if no fail edge exists, fall through to pass + } + + set(s => ({ flowExecState: s.flowExecState ? { ...s.flowExecState, nodeStates: { ...s.flowExecState.nodeStates, [nodeId]: 'passed' } } : null })) + await sleep(300) + const passEdge = flow.edges.find(e => e.source === nodeId && e.edgeKind === 'pass' && !e.branchOptionId) + if (passEdge) await runStep(passEdge.target, takenBranches) + } + } + + const startNode = flow.nodes.find(n => n.nodeType === 'start') + if (startNode) runStep(startNode.id, {}).catch(() => {}) + }, + + // ─── Recommendation Actions ────────────────────────────────────────────────── + acceptRecommendation: (recId) => { + const rec = get().recommendations.find(r => r.id === recId) + if (!rec) return + + // F-005: guard — do not proceed if workerDef or targetObjectId is missing + const workerDef = WORKER_DEFS.find(w => w.id === rec.suggestedWorkerId) + const targetObjectId = rec.relatedObjectIds[0] + if (!workerDef || !targetObjectId) { + console.error(`acceptRecommendation: workerDef or targetObjectId missing for rec ${recId}`) + set(state => ({ + recommendations: state.recommendations.map(r => + r.id === recId ? { ...r, state: 'pending' } : r + ), + })) + return + } + + // F-005: first set state to 'accepted' (not 'executing') + set(state => ({ + recommendations: state.recommendations.map(r => + r.id === recId ? { ...r, state: 'accepted' } : r + ), + })) + + // F-005: PoC: simulates Re-check delay; production should run validationWorker first + setTimeout(() => { + set(state => ({ + recommendations: state.recommendations.map(r => + r.id === recId ? { ...r, state: 'executing' } : r + ), + })) + + const runId = get().runWorker(rec.suggestedWorkerId, targetObjectId) + // Mark done when run completes + const checkDone = setInterval(() => { + const run = get().workerRuns.find(r => r.id === runId) + if (run?.state === 'done' || run?.state === 'failed') { + clearInterval(checkDone) + set(state => ({ + recommendations: state.recommendations.map(r => + r.id === recId ? { ...r, state: 'done' } : r + ), + })) + } + }, 500) + }, 500) + }, + + dismissRecommendation: (recId) => { + set(state => ({ + recommendations: state.recommendations.map(r => + r.id === recId ? { ...r, state: 'dismissed' } : r + ), + })) + }, + + // ─── Simulate Full Pipeline ────────────────────────────────────────────────── + simulateFullPipeline: () => { + const { isSimulating } = get() + if (isSimulating) return + + set({ isSimulating: true, activeView: 'flows' }) + get().runFlow('sdlc_pipeline_flow') + + // Reset after flow completes + setTimeout(() => { + set({ isSimulating: false }) + }, FLOW_DEFS[0].steps.length * 2500 + 2000) + }, +})) + +// ─── Helper: finish a worker run ────────────────────────────────────────────── +function finishRun( + runId: string, + objectId: string, + get: () => AppState, + set: (fn: (state: AppState) => Partial) => void +) { + const run = get().workerRuns.find(r => r.id === runId) + if (!run) return + + const workerDef = WORKER_DEFS.find(w => w.id === run.workerId) + const outputMessages: Record = { + create_design_worker: 'Design document created: Billing Service Architecture v1.3. 5 components identified, 12 API contracts defined.', + decompose_feature_worker: 'Decomposed into 8 tasks across 3 sprints. Critical path identified: Schema → Webhook → Invoice → PR.', + gap_analysis_validator: 'Gap analysis complete. Found 2 missing test scenarios, 1 uncovered requirement (FR-07). Coverage: 87%.', + pr_design_validator: 'PR validated against design. 3 findings: 1 critical (missing dedup guard), 2 warnings. Action required.', + traceability_analysis: 'Traceability: PRD→Design 100%, Design→Tasks 94%, Tasks→Code 78%. 3 gaps identified.', + stale_artifact_detection: 'Staleness scan complete. 2 artifacts marked stale. task-003 missing @cpt markers in source.', + security_impact_analysis: 'Security review complete. 1 HIGH finding: Webhook signature not validated before event dispatch. Fix required.', + implement_code_worker: 'Implementation complete. 847 lines across 6 files. Unit tests: 34 passing. Coverage: 92%.', + create_pr_worker: 'PR #248 created: feat/invoice-generation-worker. 12 commits, +1,240/-45 lines.', + reverse_engineer_worker: 'Reverse engineering complete. Reconstructed 4 SDLC artifacts. 2 gaps in original design identified.', + } + + const output = outputMessages[run.workerId] || `${workerDef?.label ?? 'Worker'} completed successfully.` + + set(state => ({ + workerRuns: state.workerRuns.map(r => + r.id === runId + ? { ...r, state: 'done' as WorkerRunState, progress: 100, completedAt: nowIso(), output } + : r + ), + })) + + // Update object state based on worker + const objectUpdates: Partial = {} + if (run.workerId === 'gap_analysis_validator') { + objectUpdates.validationStatus = 'pass' + // F-001: stalenessScore is 0.0–1.0 float; subtract 0.10 instead of integer 10 + objectUpdates.stalenessScore = Math.max(0, (get().objects.find(o => o.id === objectId)?.stalenessScore ?? 0) - 0.10) + } else if (run.workerId === 'traceability_analysis') { + objectUpdates.validationStatus = 'pass' + } else if (run.workerId === 'stale_artifact_detection') { + objectUpdates.stalenessScore = 0 + } + + if (Object.keys(objectUpdates).length > 0) { + set(state => ({ + objects: state.objects.map(o => + o.id === objectId ? { ...o, ...objectUpdates } : o + ), + })) + } +} + +// ─── Selectors ──────────────────────────────────────────────────────────────── +export const selectObject = (state: AppState) => + state.selectedObjectId ? state.objects.find(o => o.id === state.selectedObjectId) ?? null : null + +export const selectActiveWorkerRuns = (state: AppState) => + state.workerRuns.filter(r => r.state === 'running' || r.state === 'awaiting_input' || r.state === 'pending') + +export const selectPendingRecommendations = (state: AppState) => + state.recommendations.filter(r => r.state === 'pending' || r.state === 'accepted' || r.state === 'executing') + +export const selectWorkersForObject = (typeId: string) => () => + getWorkersForObject(typeId) From 55aedb3d88a037e3f8916bac900cbe78bc9bf14f Mon Sep 17 00:00:00 2001 From: ainetx Date: Wed, 8 Jul 2026 14:49:48 +0300 Subject: [PATCH 073/106] fix(ui-1): resolve TypeScript errors from domain.ts type changes - ObjectGraph.tsx: remove invalid 'triggers'/'related_to'/'blocks' from EDGE_KIND_COLORS; replace LinkKind comparison `=== 'triggers'` with `false` (no core kind triggers animation) - ObjectDetail.tsx: add 'aborted' and 'escalated' entries to RunCard stateConfig to cover all WorkerRunState values - ActivityFeed.tsx: replace non-existent dismissWorkerRun with dismissRunToast; add 'aborted'/'escalated' to stateConfig - WorkerInteractionModal.tsx: replace dismissWorkerRun with cancelWorkerRun (modal cancels an active awaiting_input run) - WorkerRunSimulator.tsx: replace dismissWorkerRun with dismissRunToast; add 'aborted'/'escalated' to stateConfig - mock-data.ts: replace kind: 'related_to' with 'references' on inc-001 links; fix find_suspected_component profile from invalid 'analyzer' to 'on_demand'; add missing actionLabel field Co-authored-by: Constructor Studio <291158726+constructor-studio[bot]@users.noreply.github.com> Studio-Generated-By: Constructor Studio Studio-Source-Repo: https://github.com/constructorfabric/studio Constructor-Fabric: https://github.com/constructorfabric Signed-off-by: ainetx --- .../ui-1/src/components/graph/ObjectGraph.tsx | 166 +++++ .../src/components/objects/ObjectDetail.tsx | 693 ++++++++++++++++++ .../src/components/workers/ActivityFeed.tsx | 210 ++++++ .../workers/WorkerInteractionModal.tsx | 167 +++++ .../components/workers/WorkerRunSimulator.tsx | 171 +++++ v2/poc/ui-1/src/data/mock-data.ts | 7 +- 6 files changed, 1411 insertions(+), 3 deletions(-) create mode 100644 v2/poc/ui-1/src/components/graph/ObjectGraph.tsx create mode 100644 v2/poc/ui-1/src/components/objects/ObjectDetail.tsx create mode 100644 v2/poc/ui-1/src/components/workers/ActivityFeed.tsx create mode 100644 v2/poc/ui-1/src/components/workers/WorkerInteractionModal.tsx create mode 100644 v2/poc/ui-1/src/components/workers/WorkerRunSimulator.tsx diff --git a/v2/poc/ui-1/src/components/graph/ObjectGraph.tsx b/v2/poc/ui-1/src/components/graph/ObjectGraph.tsx new file mode 100644 index 00000000..6938351d --- /dev/null +++ b/v2/poc/ui-1/src/components/graph/ObjectGraph.tsx @@ -0,0 +1,166 @@ +import { useCallback, useMemo } from 'react' +import type React from 'react' +import { + ReactFlow, + Background, + Controls, + MiniMap, + BackgroundVariant, + type Node, + type Edge, + type NodeTypes, +} from '@xyflow/react' +import { useAppStore } from '../../store/app-store' +import { CustomNode } from './CustomNode' +import { MOCK_OBJECTS, NODE_POSITIONS } from '../../data/mock-data' +import type { StudioObject } from '../../types/domain' + +const nodeTypes: NodeTypes = { + customNode: CustomNode, +} + +const EDGE_KIND_COLORS: Record = { + derived_from: '#6366f1', + decomposes_into: '#06b6d4', + implements: '#10b981', + validates: '#f59e0b', + references: '#8b5cf6', + incorporates: '#ec4899', + supersedes: '#ef4444', + informs: '#71717a', +} + +export function ObjectGraph() { + const objects = useAppStore(s => s.objects) + const selectedObjectId = useAppStore(s => s.selectedObjectId) + const selectObject = useAppStore(s => s.selectObject) + + // When a node is selected, find its direct neighbors (connected via links) + const connectedIds = useMemo(() => { + if (!selectedObjectId) return new Set() + const ids = new Set([selectedObjectId]) + objects.forEach(obj => { + if (obj.id === selectedObjectId) { + obj.links.forEach(l => ids.add(l.targetId)) + } + obj.links.forEach(l => { + if (l.targetId === selectedObjectId) ids.add(obj.id) + }) + }) + return ids + }, [objects, selectedObjectId]) + + const nodes: Node[] = useMemo(() => + objects.map(obj => { + const dimmed = selectedObjectId !== null && !connectedIds.has(obj.id) + return { + id: obj.id, + type: 'customNode', + position: NODE_POSITIONS[obj.id] ?? { x: 0, y: 0 }, + data: { object: obj, dimmed }, + selected: obj.id === selectedObjectId, + } + }), + [objects, selectedObjectId, connectedIds] + ) + + const edges: Edge[] = useMemo(() => { + const result: Edge[] = [] + const seen = new Set() + objects.forEach((obj: StudioObject) => { + obj.links.forEach(link => { + const edgeId = `${obj.id}-${link.targetId}-${link.kind}` + if (seen.has(edgeId)) return + seen.add(edgeId) + + const isConnected = selectedObjectId !== null && + (obj.id === selectedObjectId || link.targetId === selectedObjectId) + + // When nothing selected: hide all edges + // When something selected: show connected edges fully, dim others + const opacity = selectedObjectId === null ? 0 : isConnected ? 1 : 0.08 + const color = isConnected + ? (EDGE_KIND_COLORS[link.kind] ?? '#52525b') + : '#52525b' + + result.push({ + id: edgeId, + source: obj.id, + target: link.targetId, + label: isConnected ? link.kind.replace(/_/g, ' ') : undefined, + labelStyle: { fontSize: 9, fill: '#a1a1aa', fontFamily: 'Inter, sans-serif' }, + labelBgStyle: { fill: '#09090b', fillOpacity: 0.9 }, + labelBgPadding: [3, 4] as [number, number], + style: { + stroke: color, + strokeWidth: isConnected ? 2 : 1, + opacity, + transition: 'opacity 0.2s ease, stroke-width 0.2s ease', + }, + markerEnd: { + type: 'arrowclosed' as const, + color, + width: 16, + height: 16, + }, + animated: false, + }) + }) + }) + return result + }, [objects, selectedObjectId]) + + const onNodeClick = useCallback((_evt: React.MouseEvent, node: Node) => { + selectObject(node.id === selectedObjectId ? null : node.id) + }, [selectObject, selectedObjectId]) + + const onPaneClick = useCallback(() => { + selectObject(null) + }, [selectObject]) + + return ( +
+ + + + { + const obj = (node.data as { object: StudioObject }).object + const stateColors: Record = { + approved: '#10b981', + done: '#10b981', + in_progress: '#f59e0b', + running: '#f59e0b', + review: '#f59e0b', + failed: '#ef4444', + open: '#ef4444', + draft: '#52525b', + planned: '#3b82f6', + } + return stateColors[obj?.state] ?? '#52525b' + }} + maskColor="rgba(9,9,11,0.7)" + /> + +
+ ) +} diff --git a/v2/poc/ui-1/src/components/objects/ObjectDetail.tsx b/v2/poc/ui-1/src/components/objects/ObjectDetail.tsx new file mode 100644 index 00000000..70bbc369 --- /dev/null +++ b/v2/poc/ui-1/src/components/objects/ObjectDetail.tsx @@ -0,0 +1,693 @@ +import { useState } from 'react' +import { Play, ExternalLink, Clock, CheckCircle, XCircle, AlertCircle, Loader, Lock, AlertTriangle, ShieldCheck, TrendingUp, TrendingDown, Minus, FileCheck, GitMerge } from 'lucide-react' +import { useAppStore } from '../../store/app-store' +import { getWorkersForObject, MOCK_OBJECTS, MOCK_RECOMMENDATIONS } from '../../data/mock-data' +import type { StudioObject, WorkerRun, ObjectTypeId } from '../../types/domain' +import { StateBadge, ValidationBadge } from '../layout/RightPanel' + +interface Props { + object: StudioObject + activeTab: string +} + +export function ObjectDetail({ object, activeTab }: Props) { + switch (activeTab) { + case 'overview': return + case 'actions': return + case 'history': return + case 'links': return + case 'score': return + default: return + } +} + +// ─── Mock per-object score data ─────────────────────────────────────────────── + +interface ObjectScore { + qualityScore: number // 0-100 + traceability: number // 0-100 % coverage + reqsCovered: number + reqsTotal: number + validationHistory: ('pass' | 'fail' | 'skip')[] + staleness: number // 0-100 + findings: Array<{ severity: 'critical' | 'warning' | 'info'; label: string }> + aiCostUsd: number + lastRunMs: number +} + +function getObjectScore(obj: StudioObject): ObjectScore { + const base: Record = { + 'prd-001': { qualityScore: 82, traceability: 87, reqsCovered: 7, reqsTotal: 8, validationHistory: ['pass','pass','fail','pass','pass'], staleness: 5, findings: [{ severity: 'info', label: 'R-005 has no linked test case' }, { severity: 'warning', label: '1 use-case missing acceptance criteria' }], aiCostUsd: 0.12, lastRunMs: 3200 }, + 'design-001': { qualityScore: 78, traceability: 92, reqsCovered: 8, reqsTotal: 8, validationHistory: ['pass','fail','pass','pass'], staleness: 15, findings: [{ severity: 'warning', label: 'Event bus pattern not implemented in code' }, { severity: 'info', label: '2 interfaces lack error schemas' }], aiCostUsd: 0.34, lastRunMs: 5100 }, + 'adr-001': { qualityScore: 91, traceability: 100, reqsCovered: 3, reqsTotal: 3, validationHistory: ['pass','pass','pass'], staleness: 8, findings: [], aiCostUsd: 0.08, lastRunMs: 1800 }, + 'adr-002': { qualityScore: 88, traceability: 100, reqsCovered: 2, reqsTotal: 2, validationHistory: ['pass','pass'], staleness: 12, findings: [{ severity: 'info', label: 'No migration plan documented' }], aiCostUsd: 0.07, lastRunMs: 1600 }, + 'decomp-001': { qualityScore: 74, traceability: 78, reqsCovered: 6, reqsTotal: 8, validationHistory: ['fail','pass','pass'], staleness: 10, findings: [{ severity: 'warning', label: '2 tasks have no Definition of Done' }, { severity: 'critical', label: 'Tasks missing prd fr[] coverage' }], aiCostUsd: 0.29, lastRunMs: 4800 }, + 'task-001': { qualityScore: 70, traceability: 65, reqsCovered: 1, reqsTotal: 1, validationHistory: ['pass','fail','pass'], staleness: 5, findings: [{ severity: 'warning', label: 'No traceability markers in source code' }], aiCostUsd: 0.18, lastRunMs: 2900 }, + 'task-002': { qualityScore: 60, traceability: 0, reqsCovered: 0, reqsTotal: 1, validationHistory: ['fail'], staleness: 20, findings: [{ severity: 'critical', label: 'Feature spec not approved yet' }, { severity: 'warning', label: 'No implementation started' }], aiCostUsd: 0, lastRunMs: 0 }, + 'task-003': { qualityScore: 95, traceability: 100, reqsCovered: 1, reqsTotal: 1, validationHistory: ['pass','pass','pass'], staleness: 0, findings: [], aiCostUsd: 0.22, lastRunMs: 3400 }, + 'fspec-001': { qualityScore: 88, traceability: 94, reqsCovered: 3, reqsTotal: 3, validationHistory: ['pass','pass'], staleness: 5, findings: [{ severity: 'info', label: '1 error scenario missing repro steps' }], aiCostUsd: 0.41, lastRunMs: 6200 }, + 'fspec-002': { qualityScore: 45, traceability: 30, reqsCovered: 0, reqsTotal: 2, validationHistory: ['fail'], staleness: 25, findings: [{ severity: 'critical', label: 'No test scenarios defined' }, { severity: 'critical', label: 'Missing algo blocks for invoice calc' }, { severity: 'warning', label: 'Definition of Done incomplete' }], aiCostUsd: 0, lastRunMs: 0 }, + 'pr-001': { qualityScore: 72, traceability: 80, reqsCovered: 2, reqsTotal: 3, validationHistory: ['fail','pass'], staleness: 5, findings: [{ severity: 'warning', label: 'No security review completed' }, { severity: 'info', label: 'CI run pending' }], aiCostUsd: 0.15, lastRunMs: 2100 }, + 'build-001': { qualityScore: 100, traceability: 100, reqsCovered: 0, reqsTotal: 0, validationHistory: ['pass'], staleness: 0, findings: [], aiCostUsd: 0.02, lastRunMs: 800 }, + 'incident-001':{ qualityScore: 40, traceability: 20, reqsCovered: 0, reqsTotal: 0, validationHistory: ['fail'], staleness: 30, findings: [{ severity: 'critical', label: 'No postmortem created' }, { severity: 'critical', label: 'Root cause not identified' }], aiCostUsd: 0, lastRunMs: 0 }, + } + return base[obj.id] ?? { qualityScore: 60, traceability: 50, reqsCovered: 0, reqsTotal: 0, validationHistory: ['pass'], staleness: obj.stalenessScore, findings: [], aiCostUsd: 0.05, lastRunMs: 1000 } +} + +// ─── SVG Charts ─────────────────────────────────────────────────────────────── + +function DonutChart({ value, total, color, size = 80, label }: { + value: number; total: number; color: string; size?: number; label?: string +}) { + const pct = total === 0 ? 0 : Math.round((value / total) * 100) + const r = size / 2 - 8 + const circ = 2 * Math.PI * r + const dash = (pct / 100) * circ + return ( +
+ + + + +
+ {pct}% + {label && {label}} +
+
+ ) +} + +function RadialGauge({ value, color, size = 80, label }: { value: number; color: string; size?: number; label?: string }) { + const r = size / 2 - 8 + const circ = Math.PI * r // half circle + const dash = (value / 100) * circ + return ( +
+ + + + +
+ {value} + {label &&
{label}
} +
+
+ ) +} + +function Sparkline({ values, color, width = 120, height = 32 }: { values: number[]; color: string; width?: number; height?: number }) { + if (values.length < 2) return null + const max = Math.max(...values, 1) + const min = Math.min(...values) + const range = max - min || 1 + const step = width / (values.length - 1) + const points = values.map((v, i) => `${i * step},${height - ((v - min) / range) * (height - 4) - 2}`).join(' ') + return ( + + + {values.map((v, i) => ( + + ))} + + ) +} + +function ValidationDots({ history }: { history: ('pass' | 'fail' | 'skip')[] }) { + const colors = { pass: '#10b981', fail: '#ef4444', skip: '#71717a' } + return ( +
+ {history.map((h, i) => ( +
+ ))} + + {history.filter(h => h === 'pass').length}/{history.length} passed + +
+ ) +} + +function FindingItem({ severity, label }: { severity: 'critical' | 'warning' | 'info'; label: string }) { + const colors = { critical: '#f87171', warning: '#fbbf24', info: '#60a5fa' } + const bg = { critical: 'rgba(239,68,68,0.08)', warning: 'rgba(245,158,11,0.08)', info: 'rgba(59,130,246,0.08)' } + const border = { critical: 'rgba(239,68,68,0.25)', warning: 'rgba(245,158,11,0.25)', info: 'rgba(59,130,246,0.2)' } + return ( +
+ + {label} +
+ ) +} + +// ─── Score Tab ──────────────────────────────────────────────────────────────── + +function ScoreTab({ object }: { object: StudioObject }) { + const score = getObjectScore(object) + const qColor = score.qualityScore >= 80 ? '#10b981' : score.qualityScore >= 60 ? '#f59e0b' : '#ef4444' + const tColor = score.traceability >= 80 ? '#10b981' : score.traceability >= 50 ? '#f59e0b' : '#ef4444' + const sColor = score.staleness <= 20 ? '#10b981' : score.staleness <= 50 ? '#f59e0b' : '#ef4444' + + // Sparkline mock data (7-day trend) + const qualityTrend = [65, 70, 68, 74, 78, score.qualityScore - 3, score.qualityScore] + const stalenessTrend = [10, 12, 15, 18, score.staleness + 5, score.staleness + 2, score.staleness] + + return ( +
+ + {/* Top gauges row */} +
+ {/* Quality score */} +
+ + Quality +
+ + {/* Traceability donut */} +
+ + Traceability +
+ + {/* Staleness */} +
+ + Freshness +
+
+ + {/* Requirement coverage bar */} + {score.reqsTotal > 0 && ( +
+
+ + Requirement Coverage + + + {score.reqsCovered}/{score.reqsTotal} + +
+
+
+
+
+ {Array.from({ length: score.reqsTotal }).map((_, i) => ( +
+ ))} +
+
+ )} + + {/* Trends */} +
+
+
+ + Quality Trend +
+ +
+ 7d ago + now +
+
+
+
+ + Staleness Trend +
+ 30 ? '#ef4444' : '#f59e0b'} width={108} height={30} /> +
+ 7d ago + now +
+
+
+ + {/* Validation history */} +
+
+ + Validation History +
+ +
+ + {/* AI Cost */} + {score.aiCostUsd > 0 && ( +
+
+ AI Attribution +
+
+
+

${score.aiCostUsd.toFixed(2)}

+

total cost

+
+
+

{(score.lastRunMs / 1000).toFixed(1)}s

+

last run

+
+
+
+ )} +
+ ) +} + +// ─── Overview Tab (findings + status focused) ───────────────────────────────── + +function OverviewTab({ object }: { object: StudioObject }) { + const score = getObjectScore(object) + const allObjects = MOCK_OBJECTS + const recs = MOCK_RECOMMENDATIONS.filter(r => r.relatedObjectIds.includes(object.id) && r.state === 'pending') + const incomingCount = allObjects.filter(o => o.links.some(l => l.targetId === object.id)).length + + return ( +
+ + {/* Description */} + {object.description && ( +
+

{object.description}

+
+ )} + + {/* Findings */} + {score.findings.length > 0 && ( +
+

+ Findings ({score.findings.length}) +

+
+ {score.findings.map((f, i) => )} +
+
+ )} + + {/* Recommendations */} + {recs.length > 0 && ( +
+

+ Recommendations ({recs.length}) +

+
+ {recs.map(rec => { + const sc = rec.severity === 'critical' ? { color: '#f87171', bg: 'rgba(239,68,68,0.08)', border: 'rgba(239,68,68,0.2)', left: '#ef4444' } + : rec.severity === 'warning' ? { color: '#fbbf24', bg: 'rgba(245,158,11,0.08)', border: 'rgba(245,158,11,0.2)', left: '#f59e0b' } + : { color: '#60a5fa', bg: 'rgba(59,130,246,0.08)', border: 'rgba(59,130,246,0.2)', left: '#3b82f6' } + return ( +
+

{rec.title}

+

{rec.description}

+
+ ) + })} +
+
+ )} + + {/* Status properties */} +
+

Properties

+
+ {[ + { label: 'State', value: }, + { label: 'Validation', value: }, + { label: 'Staleness', value: 50 ? '#f87171' : object.stalenessScore > 20 ? '#fbbf24' : '#10b981' }}>{object.stalenessScore}% }, + { label: 'ID', value: {object.id} }, + { label: 'Updated', value: {new Date(object.updatedAt).toLocaleDateString()} }, + { label: 'Linked by', value: {incomingCount} object{incomingCount !== 1 ? 's' : ''} }, + ].map(({ label, value }) => ( +
+ {label} +
{value}
+
+ ))} +
+
+ + {/* Metadata */} + {object.metadata && Object.keys(object.metadata).length > 0 && ( +
+

Metadata

+
+ {Object.entries(object.metadata).map(([k, v]) => ( +
+ {k} + {String(v)} +
+ ))} +
+
+ )} + + {/* No findings success */} + {score.findings.length === 0 && recs.length === 0 && ( +
+ + No findings — object is healthy +
+ )} +
+ ) +} + +// ─── Actions Tab ────────────────────────────────────────────────────────────── + +function ActionsTab({ object }: { object: StudioObject }) { + const runWorker = useAppStore(s => s.runWorker) + const workerRuns = useAppStore(s => s.workerRuns) + const workers = getWorkersForObject(object.typeId) + + const isRunning = (workerId: string) => + workerRuns.some(r => r.objectId === object.id && r.workerId === workerId && + (r.state === 'running' || r.state === 'pending' || r.state === 'awaiting_input')) + + const categoryColors: Record = { + quality: 'text-emerald-400', security: 'text-red-400', ops: 'text-amber-400', + traceability: 'text-blue-400', retrieval: 'text-purple-400', platform: 'text-indigo-400', + } + const categoryBg: Record = { + quality: 'bg-emerald-900/20 border-emerald-800/30', security: 'bg-red-900/20 border-red-800/30', + ops: 'bg-amber-900/20 border-amber-800/30', traceability: 'bg-blue-900/20 border-blue-800/30', + retrieval: 'bg-purple-900/20 border-purple-800/30', platform: 'bg-indigo-900/20 border-indigo-800/30', + } + + if (workers.length === 0) { + return
No workers available for this object type.
+ } + + return ( +
+

Available workers for {object.typeId}:

+ {workers.map(worker => { + const running = isRunning(worker.id) + return ( +
+
+
+
+ {worker.category} + {worker.requiresAutomationGate && gated} + • {worker.profile} +
+

{worker.label}

+

{worker.description}

+
+ +
+
+ ) + })} +
+ ) +} + +// ─── History Tab ────────────────────────────────────────────────────────────── + +function fmtDur(ms?: number): string { + if (!ms) return '—' + if (ms < 1000) return `${ms}ms` + return `${(ms / 1000).toFixed(1)}s` +} + +function fmtTokens(n?: number): string { + if (!n) return '—' + return n >= 1000 ? `${(n / 1000).toFixed(1)}k` : String(n) +} + +function HistoryTab({ object }: { object: StudioObject }) { + const workerRuns = useAppStore(s => s.workerRuns) + const objectRuns = [...workerRuns.filter(r => r.objectId === object.id)] + .sort((a, b) => new Date(b.startedAt).getTime() - new Date(a.startedAt).getTime()) + + if (objectRuns.length === 0) { + return ( +
+

No worker runs yet.

+

Go to Actions tab to run a worker.

+
+ ) + } + + const totalCost = objectRuns.reduce((s, r) => s + (r.costUsd ?? 0), 0) + const totalTokensIn = objectRuns.reduce((s, r) => s + (r.tokensIn ?? 0), 0) + const totalTokensOut = objectRuns.reduce((s, r) => s + (r.tokensOut ?? 0), 0) + const passCount = objectRuns.filter(r => r.state === 'done').length + const failCount = objectRuns.filter(r => r.state === 'failed').length + + // Cost per worker (aggregated) + const costByWorker: Record = {} + objectRuns.forEach(r => { + if (!costByWorker[r.workerId]) costByWorker[r.workerId] = { label: r.workerLabel, cost: 0, runs: 0 } + costByWorker[r.workerId].cost += r.costUsd ?? 0 + costByWorker[r.workerId].runs++ + }) + const workerBreakdown = Object.values(costByWorker).sort((a, b) => b.cost - a.cost) + const maxCost = workerBreakdown[0]?.cost ?? 1 + + return ( +
+ {/* ── Cost Summary ── */} +
+

+ Total AI Spend +

+ + {/* Big number */} +
+ + ${totalCost.toFixed(2)} + + {objectRuns.length} runs +
+ + {/* Stats row */} +
+ {[ + { label: 'In tokens', value: fmtTokens(totalTokensIn), color: '#818cf8' }, + { label: 'Out tokens', value: fmtTokens(totalTokensOut), color: '#a78bfa' }, + { label: 'Passed', value: String(passCount), color: '#10b981' }, + { label: 'Failed', value: String(failCount), color: failCount > 0 ? '#f87171' : '#71717a' }, + ].map(s => ( +
+

{s.value}

+

{s.label}

+
+ ))} +
+ + {/* Cost by worker breakdown */} + {workerBreakdown.length > 0 && ( +
+

By worker

+
+ {workerBreakdown.map(w => ( +
+
+ {w.label} +
+ {w.runs}× + ${w.cost.toFixed(2)} +
+
+
+
+
+
+ ))} +
+
+ )} +
+ + {/* ── Run list ── */} +
+

+ Run History ({objectRuns.length}) +

+ {objectRuns.map(run => )} +
+
+ ) +} + +function RunCard({ run }: { run: WorkerRun }) { + const [expanded, setExpanded] = useState(false) + const isLive = run.state === 'running' || run.state === 'pending' || run.state === 'awaiting_input' + + const stateConfig = { + done: { icon: , color: '#10b981', label: 'Passed' }, + failed: { icon: , color: '#f87171', label: 'Failed' }, + running: { icon: , color: '#6366f1', label: 'Running' }, + pending: { icon: , color: '#71717a', label: 'Pending' }, + awaiting_input: { icon: , color: '#f59e0b', label: 'Waiting' }, + paused: { icon: , color: '#f59e0b', label: 'Paused' }, + aborted: { icon: , color: '#71717a', label: 'Aborted' }, + escalated: { icon: , color: '#f97316', label: 'Escalated' }, + }[run.state] ?? { icon: , color: '#71717a', label: run.state } + + const ts = new Date(run.startedAt) + const dateStr = ts.toLocaleDateString(undefined, { month: 'short', day: 'numeric' }) + const timeStr = ts.toLocaleTimeString(undefined, { hour: '2-digit', minute: '2-digit' }) + + return ( +
+ {/* Header row */} + + + {/* Live progress */} + {isLive && ( +
+
+
+
+ {Math.round(run.progress)}% — {run.workerLabel} +
+ )} + + {/* Expanded details */} + {expanded && !isLive && ( +
+ {/* Metrics */} +
+ {[ + { label: 'Duration', value: fmtDur(run.durationMs) }, + { label: 'In', value: fmtTokens(run.tokensIn) }, + { label: 'Out', value: fmtTokens(run.tokensOut) }, + { label: 'Model', value: run.model ?? '—' }, + ].map(m => ( + + {m.label}: {m.value} + + ))} +
+ {/* Output / Error */} + {run.output && ( +

+ {run.output} +

+ )} + {run.error && ( +

+ ✗ {run.error} +

+ )} +
+ )} +
+ ) +} + +// ─── Links Tab ──────────────────────────────────────────────────────────────── + +function LinksTab({ object }: { object: StudioObject }) { + const allObjects = MOCK_OBJECTS + const selectObject = useAppStore(s => s.selectObject) + const linkKindColors: Record = { + derived_from: 'text-indigo-400 border-indigo-800/50 bg-indigo-900/20', + decomposes_into: 'text-cyan-400 border-cyan-800/50 bg-cyan-900/20', + implements: 'text-emerald-400 border-emerald-800/50 bg-emerald-900/20', + validates: 'text-amber-400 border-amber-800/50 bg-amber-900/20', + references: 'text-purple-400 border-purple-800/50 bg-purple-900/20', + triggers: 'text-pink-400 border-pink-800/50 bg-pink-900/20', + blocks: 'text-red-400 border-red-800/50 bg-red-900/20', + related_to: 'text-zinc-400 border-zinc-700 bg-zinc-900', + } + const outgoing = object.links.map(link => ({ ...link, target: allObjects.find(o => o.id === link.targetId), direction: 'out' as const })) + const incoming = allObjects.flatMap(obj => obj.links.filter(l => l.targetId === object.id).map(l => ({ ...l, targetId: obj.id, target: obj, direction: 'in' as const }))) + return ( +
+ {outgoing.length > 0 && ( +
+

Outgoing ({outgoing.length})

+
+ {outgoing.map((link, i) => ( + + ))} +
+
+ )} + {incoming.length > 0 && ( +
+

Incoming ({incoming.length})

+
+ {incoming.map((link, i) => ( + + ))} +
+
+ )} + {outgoing.length === 0 && incoming.length === 0 &&

No links defined.

} +
+ ) +} + +function PropertyRow({ label, value, mono = false }: { label: string; value: string; mono?: boolean }) { + return ( +
+ {label} + {value} +
+ ) +} diff --git a/v2/poc/ui-1/src/components/workers/ActivityFeed.tsx b/v2/poc/ui-1/src/components/workers/ActivityFeed.tsx new file mode 100644 index 00000000..6f7ce22f --- /dev/null +++ b/v2/poc/ui-1/src/components/workers/ActivityFeed.tsx @@ -0,0 +1,210 @@ +import { CheckCircle, XCircle, Loader, AlertCircle, Clock, ChevronDown, ChevronUp, Trash2 } from 'lucide-react' +import { useState } from 'react' +import { useAppStore } from '../../store/app-store' +import type { WorkerRun } from '../../types/domain' + +export function ActivityFeed() { + const workerRuns = useAppStore(s => s.workerRuns) + const dismissRunToast = useAppStore(s => s.dismissRunToast) + const [expanded, setExpanded] = useState>(new Set()) + + const toggleExpand = (id: string) => { + setExpanded(prev => { + const next = new Set(prev) + next.has(id) ? next.delete(id) : next.add(id) + return next + }) + } + + if (workerRuns.length === 0) { + return ( +
+
+
+ +
+

No Activity Yet

+

Worker runs will appear here

+
+
+ ) + } + + const grouped = { + active: workerRuns.filter(r => r.state === 'running' || r.state === 'pending' || r.state === 'awaiting_input'), + done: workerRuns.filter(r => r.state === 'done'), + failed: workerRuns.filter(r => r.state === 'failed'), + } + + return ( +
+ {grouped.active.length > 0 && ( +
+

+ + Active ({grouped.active.length}) +

+
+ {grouped.active.map(run => ( + toggleExpand(run.id)} + onDismiss={() => dismissRunToast(run.id)} + /> + ))} +
+
+ )} + + {grouped.failed.length > 0 && ( +
+

+ + Failed ({grouped.failed.length}) +

+
+ {grouped.failed.map(run => ( + toggleExpand(run.id)} + onDismiss={() => dismissRunToast(run.id)} + /> + ))} +
+
+ )} + + {grouped.done.length > 0 && ( +
+

+ + Completed ({grouped.done.length}) +

+
+ {grouped.done.map(run => ( + toggleExpand(run.id)} + onDismiss={() => dismissRunToast(run.id)} + /> + ))} +
+
+ )} +
+ ) +} + +function RunCard({ + run, + expanded, + onToggle, + onDismiss, +}: { + run: WorkerRun + expanded: boolean + onToggle: () => void + onDismiss: () => void +}) { + const stateConfig = { + pending: { icon: , border: 'border-zinc-700', headerBg: 'bg-zinc-900' }, + running: { icon: , border: 'border-blue-800/40', headerBg: 'bg-zinc-900' }, + awaiting_input: { icon: , border: 'border-amber-700/50', headerBg: 'bg-amber-950/20' }, + done: { icon: , border: 'border-emerald-800/30', headerBg: 'bg-zinc-900' }, + failed: { icon: , border: 'border-red-800/40', headerBg: 'bg-red-950/20' }, + paused: { icon: , border: 'border-amber-700/50', headerBg: 'bg-zinc-900' }, + aborted: { icon: , border: 'border-zinc-700', headerBg: 'bg-zinc-900' }, + escalated: { icon: , border: 'border-orange-700/50', headerBg: 'bg-orange-950/20' }, + }[run.state] ?? { icon: , border: 'border-zinc-700', headerBg: 'bg-zinc-900' } + + const duration = run.completedAt + ? Math.round((new Date(run.completedAt).getTime() - new Date(run.startedAt).getTime()) / 1000) + : null + + return ( +
+
+ {stateConfig.icon} +
+
+

{run.workerLabel}

+
+ {duration !== null && ( + {duration}s + )} + + +
+
+

on: {run.objectTitle}

+
+
+ + {/* Progress bar for active runs */} + {(run.state === 'running' || run.state === 'pending') && ( +
+
+
+
+
+ {Math.round(run.progress)}% complete + + {new Date(run.startedAt).toLocaleTimeString()} + +
+
+ )} + + {/* Awaiting input state */} + {run.state === 'awaiting_input' && ( +
+

Waiting for your input to continue…

+
+ )} + + {/* Expanded details */} + {expanded && ( +
+
+ Started: {new Date(run.startedAt).toLocaleTimeString()} + {run.completedAt && Ended: {new Date(run.completedAt).toLocaleTimeString()}} +
+ {run.interactionResponse && ( +
+

User Response

+

{run.interactionResponse}

+
+ )} + {run.output && ( +
+

Output

+

{run.output}

+
+ )} + {run.error && ( +
+

Error

+

{run.error}

+
+ )} +
+ )} +
+ ) +} diff --git a/v2/poc/ui-1/src/components/workers/WorkerInteractionModal.tsx b/v2/poc/ui-1/src/components/workers/WorkerInteractionModal.tsx new file mode 100644 index 00000000..80bddc2f --- /dev/null +++ b/v2/poc/ui-1/src/components/workers/WorkerInteractionModal.tsx @@ -0,0 +1,167 @@ +import { AnimatePresence, motion } from 'framer-motion' +import { AlertCircle, Send, X } from 'lucide-react' +import { useState } from 'react' +import { useAppStore } from '../../store/app-store' + +export function WorkerInteractionModal() { + const pendingId = useAppStore(s => s.pendingInteractionRunId) + const workerRuns = useAppStore(s => s.workerRuns) + const respondToInteraction = useAppStore(s => s.respondToInteraction) + const cancelWorkerRun = useAppStore(s => s.cancelWorkerRun) + + const [inputValue, setInputValue] = useState('') + const [selectedOption, setSelectedOption] = useState(null) + + const run = pendingId ? workerRuns.find(r => r.id === pendingId) : null + + const handleSubmit = () => { + if (!run || !pendingId) return + const response = run.interaction?.kind === 'menu' ? (selectedOption ?? '') : inputValue.trim() + if (!response) return + respondToInteraction(pendingId, response) + setInputValue('') + setSelectedOption(null) + } + + const handleDismiss = () => { + if (!pendingId) return + cancelWorkerRun(pendingId) + setInputValue('') + setSelectedOption(null) + } + + return ( + + {run && run.interaction && ( + <> + {/* Backdrop */} + + + {/* Modal */} + +
e.stopPropagation()} + > + {/* Header */} +
+
+
+ +
+
+

Worker Needs Input

+

{run.workerLabel} • {run.objectTitle}

+
+
+ +
+ + {/* Body */} +
+ {/* Interaction prompt */} +
+

{run.interaction.prompt}

+
+ + {/* Menu options */} + {run.interaction.kind === 'menu' && run.interaction.options && ( +
+

Choose an option:

+ {run.interaction.options.map(option => ( + + ))} +
+ )} + + {/* Text input */} + {(run.interaction.kind === 'input_request' || run.interaction.kind === 'free_form_intent') && ( +
+

Your response:

+