From e601b8fc0922d19b4d7d9def475c522c0572593e Mon Sep 17 00:00:00 2001 From: Victor Wiebe Date: Fri, 7 Aug 2026 11:08:16 -0400 Subject: [PATCH] Reconcile MVP scope governance --- CODEX.md | 1 + MVP_SCOPE.md | 56 ++++++++-------- README.md | 4 +- ROADMAP.md | 14 ++-- TESTING.md | 6 ++ docs/ARCHITECTURE.md | 25 +++++--- docs/MVP_TRACEABILITY.md | 57 ++++++++++++++++ docs/REQUIREMENTS.md | 107 +++++++++++++++---------------- package.json | 1 + scripts/check-mvp-governance.mjs | 60 +++++++++++++++++ 10 files changed, 232 insertions(+), 99 deletions(-) create mode 100644 docs/MVP_TRACEABILITY.md create mode 100644 scripts/check-mvp-governance.mjs diff --git a/CODEX.md b/CODEX.md index 650b9aa..a945beb 100644 --- a/CODEX.md +++ b/CODEX.md @@ -329,3 +329,4 @@ Date: 2026-07-20 - Slice 6a implementation and automation are complete through the manual gate: accessible collapsible sections/cards, compact record summaries, grouped REST editing, explicit secret creation, visible collapsed issue counts, and mounted-state preservation are implemented. Focused coverage passes at 18 tests; full frontend coverage passes at 25 suites / 520 tests; TypeScript and production build pass. `Slice 6a Density Manual` (`#22`) is prepared for `SLICE6a_MANUAL_TEST.md`. - The user reported all Slice 6a manual UX tests pass and that the changes look good. Disposable project `#22` was deleted; backend health, frontend HTTP 200, empty secrets, and empty history pass. - The user granted explicit final Slice 6a sign-off on 2026-08-07 with the exact wording: “I grant explicit final Slice 6a sign-off.” Slice 6a is complete. +- Slice 7 governance reconciliation completed on 2026-08-07. README, approved scope, roadmap, requirements, and architecture now consistently exclude AI and advanced capabilities from v0.1.0, reflect implemented canonical/proxy/secret/auth/history/validation behavior, and contain no material open release questions. `docs/MVP_TRACEABILITY.md` maps R1–R14 and all six accepted workflows to slices/evidence. The new `npm run test:governance` regression check passes. Slice 7 required no new manual gate because its product-owner scope decision was already approved. diff --git a/MVP_SCOPE.md b/MVP_SCOPE.md index c8f0a4b..365915b 100644 --- a/MVP_SCOPE.md +++ b/MVP_SCOPE.md @@ -2,7 +2,7 @@ ## Status -Approved on 2026-07-18. +Approved on 2026-07-18. All six workflows passed Slice 6 release validation and received explicit product-owner sign-off on 2026-08-07. ## AI Decision @@ -26,50 +26,52 @@ These are end-to-end acceptance scenarios. They demonstrate that Conductor can b ### 1. Workflow Launcher -- [ ] Create a project. -- [ ] Add an environment dropdown, hostname input, Submit button, and response display. -- [ ] Define a REST action. -- [ ] Map component values into the request. -- [ ] Bind the button to the action and map the response to the display. -- [ ] Execute the scenario successfully in Preview. -- [ ] Save, reload, and confirm the complete behavior is preserved. +- [x] Create a project. +- [x] Add an environment dropdown, hostname input, Submit button, and response display. +- [x] Define a REST action. +- [x] Map component values into the request. +- [x] Bind the button to the action and map the response to the display. +- [x] Execute the scenario successfully in Preview. +- [x] Save, reload, and confirm the complete behavior is preserved. ### 2. Dependent Data -- [ ] Call an API to populate a dropdown. -- [ ] Use its selected value to populate or update another component. -- [ ] Confirm loading, empty, and failure states are usable. +- [x] Call an API to populate a dropdown. +- [x] Use its selected value to populate or update another component. +- [x] Confirm loading, empty, and failure states are usable. ### 3. Read-Only Dashboard -- [ ] Call an API and populate a table. -- [ ] Select a table row. -- [ ] Display the selected record's details in another component. -- [ ] Confirm refresh and error behavior. +- [x] Call an API and populate a table. +- [x] Select a table row. +- [x] Display the selected record's details in another component. +- [x] Confirm refresh and error behavior. ### 4. Authenticated Request -- [ ] Configure and execute each of the five required authentication modes. -- [ ] Confirm credentials are injected only by the backend. -- [ ] Confirm secrets do not appear in browser-visible data, project JSON, exports, errors, or logs. +- [x] Configure and execute each of the five required authentication modes. +- [x] Confirm credentials are injected only by the backend. +- [x] Confirm secrets do not appear in browser-visible data, project JSON, exports, errors, or logs. ### 5. JSON Editing and Persistence -- [ ] Edit canonical project JSON. -- [ ] Validate and apply it. -- [ ] Confirm the Visual Editor updates to match. -- [ ] Save and reload the project without structural or behavioral loss. +- [x] Edit canonical project JSON. +- [x] Validate and apply it. +- [x] Confirm the Visual Editor updates to match. +- [x] Save and reload the project without structural or behavioral loss. ### 6. Failure Handling -- [ ] Trigger an invalid request. -- [ ] Trigger an invalid or unresolved response mapping. -- [ ] Receive actionable errors in the appropriate UI. -- [ ] Confirm canonical project state is not corrupted. -- [ ] Confirm unsaved work is not lost. +- [x] Trigger an invalid request. +- [x] Trigger an invalid or unresolved response mapping. +- [x] Receive actionable errors in the appropriate UI. +- [x] Confirm canonical project state is not corrupted. +- [x] Confirm unsaved work is not lost. ## Release Boundary The MVP is complete only when all required component, configuration, authentication, security, validation, persistence, and deployment tasks in `ROADMAP.md` are complete and all six workflows above pass the Slice 6 release-validation process. Post-MVP scope includes AI assistance, OAuth 2.0, IBM Cloud IAM, mTLS, advanced orchestration, and the future capabilities listed in `ROADMAP.md`. + +Requirement-to-slice and validation traceability is maintained in `docs/MVP_TRACEABILITY.md`. diff --git a/README.md b/README.md index 7848fe3..b93907e 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,7 @@ Designed for IBM Concert Workflows / Rapid Infrastructure Automation, but backen - **JSON Editor** — direct access to the canonical project definition - **Preview Mode** — run the application as an end user - **REST Proxy** — server-side proxy for API calls; secrets never reach the browser -- **AI Assistance** — IBM Bob / watsonx can generate and refine project configurations +- **Backend-agnostic REST integration** — build and run REST-backed interfaces without an AI dependency --- @@ -82,8 +82,10 @@ docker-compose up --build | Document | Description | |---|---| | [ROADMAP.md](ROADMAP.md) | Unified v0.1.0 work plan grouped by function and slice | +| [MVP_SCOPE.md](MVP_SCOPE.md) | Approved v0.1.0 release boundary and acceptance workflows | | [TESTING.md](TESTING.md) | Detailed manual test workflows and acceptance records | | [docs/REQUIREMENTS.md](docs/REQUIREMENTS.md) | Full product requirements | +| [docs/MVP_TRACEABILITY.md](docs/MVP_TRACEABILITY.md) | v0.1.0 requirements mapped to slices and validation evidence | | [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | Technical architecture | | [docs/NICE-TO-HAVE.md](docs/NICE-TO-HAVE.md) | Future enhancements | | [docs/BUILD_AND_TEST_PLAN.md](docs/BUILD_AND_TEST_PLAN.md) | Incremental build and test plan | diff --git a/ROADMAP.md b/ROADMAP.md index 877f2f2..8445442 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -24,7 +24,7 @@ The slice files remain the detailed implementation plans. When an older list con | [Slice 5](SLICE5.md) | Validation and error handling | Complete | None | | [Slice 6](SLICE6.md) | Testing and release validation | Complete | None | | [Slice 6a](SLICE6a.md) | Editor information density and progressive disclosure | Complete | None | -| [Slice 7](SLICE7.md) | MVP scope decision | Complete | Cross-document reconciliation is carried by Slices 6 and 8 | +| [Slice 7](SLICE7.md) | MVP scope decision and requirement governance | Complete | None | | [Slice 8](SLICE8.md) | Documentation and release packaging | Partial | Unified roadmap complete; broader documentation ownership, reconciliation, guides, and release packaging remain | ## 1. MVP GUI Components @@ -233,12 +233,12 @@ Controlled orchestration is not required in the v0.1.0 demonstration. Execution - [x] Approve the six acceptance workflows in `MVP_SCOPE.md`. - [x] Keep advanced orchestration and future UI capabilities outside the MVP boundary. -### Slices 6 and 8 — Remaining consistency work +### Slices 6–8 — Completed consistency work -- [ ] Make `MVP_SCOPE.md`, requirements, architecture, tasks, roadmap, and slice terminology consistent. -- [ ] Ensure every v0.1.0 requirement maps to a slice and a validation criterion. -- [ ] Clearly label all deferred capabilities post-MVP. -- [ ] Remove or resolve every open question that could materially change the release boundary. +- [x] Make `MVP_SCOPE.md`, requirements, architecture, tasks, roadmap, and slice terminology consistent. +- [x] Ensure every v0.1.0 requirement maps to a slice and a validation criterion. +- [x] Clearly label all deferred capabilities post-MVP. +- [x] Remove or resolve every open question that could materially change the release boundary. - [x] Produce a definitive Slice 6 release checklist and record product-owner approval. ## 8. Documentation, Packaging, and Release @@ -248,7 +248,7 @@ Controlled orchestration is not required in the v0.1.0 demonstration. Execution - [x] Create and link a unified v0.1.0 roadmap grouped by function and slice. - [x] Designate `docs/` as the authoritative specification location. - [x] Remove exact duplicate root requirements, architecture, and future-idea documents after verifying links and replacements. -- [ ] Reconcile requirements and architecture with the approved MVP scope. +- [x] Reconcile requirements and architecture with the approved MVP scope. - [ ] Update schema and response-mapping documentation to match canonical runtime behavior. - [ ] Reconcile `ROADMAP.md`, `CODEX.md`, and all slice handoffs as implementation progresses. diff --git a/TESTING.md b/TESTING.md index 0ef32d3..051fc37 100644 --- a/TESTING.md +++ b/TESTING.md @@ -83,6 +83,12 @@ The user subsequently reported all five manual UX tests pass and that the change The user granted explicit final Slice 6a sign-off on 2026-08-07 with the exact wording: “I grant explicit final Slice 6a sign-off.” Slice 6a is complete. +## Slice 7 MVP Governance Reconciliation — 2026-08-07 + +The already approved Slice 7 product decisions were reconciled across `README.md`, `MVP_SCOPE.md`, `ROADMAP.md`, `docs/REQUIREMENTS.md`, and `docs/ARCHITECTURE.md`. Stale AI-MVP claims and material open questions were removed; implemented proxy, secrets, authentication, observability, canonical-model, timeout, event, binding, and editor decisions now use consistent language. All six `MVP_SCOPE.md` workflow checklists reflect accepted Slice 6 evidence. + +`docs/MVP_TRACEABILITY.md` maps 14 release-critical requirement areas and all six workflows to owning slices and validation evidence, and explicitly classifies deferred capabilities post-MVP. `npm run test:governance` passes, checking authority statements, accepted workflow state, forbidden stale claims, Slice 7 roadmap status, R1–R14 coverage, and relative documentation links. No new product behavior or manual test gate was introduced; the release boundary already has product-owner approval. + ## Slice 4 Manual Gate The five workflows in `SLICE4.md` passed on 2026-08-02 after focused remediation and repetition. Initial testing passed approved destinations, controls/recovery, and execution history; mixed-answer/rebinding DNS checks were initially unavailable, and private destination URLs in backend failure logs failed redaction. The logger was reduced to safe structured metadata. A disposable authoritative DNS fixture then proved mixed public/loopback answers fail closed and rebinding cannot bypass pinned validated addresses. The focused logging retest found zero private literals or raw transport errors. IPv6 literal classification was also corrected and retested. All disposable secrets, history, fixtures, networks, keys, and exceptions were removed. This is manual evidence separate from automation. diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 3f9bb1a..3f2719d 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -48,11 +48,9 @@ This means: ## Backend -* Node.js with Express/Fastify - **or** -* Python with FastAPI - -Either is acceptable. Pick whichever is easiest for the team to support. +* Node.js 20 +* Express 4 +* TypeScript 5 ## Database @@ -174,7 +172,7 @@ Reasons: * Support API keys and bearer tokens safely * Normalize errors * Capture sanitized execution logs -* Prepare for future endpoint allowlisting +* Enforce the default-deny destination policy and explicit internal-origin exceptions ## 5.6 Database Layer @@ -182,8 +180,8 @@ SQLite stores: * Project metadata * Canonical project JSON -* Secret references -* Basic execution history +* Encrypted secret records and metadata; canonical JSON stores only opaque references +* Sanitized bounded execution history * Application settings The backend should use a data access layer so SQLite can later be replaced with PostgreSQL. @@ -337,9 +335,14 @@ GET /api/projects/:id PUT /api/projects/:id DELETE /api/projects/:id -POST /api/projects/:id/validate +POST /api/projects/validate POST /api/proxy/execute -GET /api/projects/:id/executions +GET /api/executions +DELETE /api/executions +GET /api/secrets +POST /api/secrets +PUT /api/secrets/:id +DELETE /api/secrets/:id ``` --- @@ -357,6 +360,8 @@ Initial decisions: * Secrets are never intentionally exposed to the browser. * Production deployments use an external reverse proxy. * AI assistance is not required for MVP. +* Provider-neutral AI assistance is post-MVP. +* Conductor executes REST actions and simple bindings; general workflow orchestration is post-MVP. diff --git a/docs/MVP_TRACEABILITY.md b/docs/MVP_TRACEABILITY.md new file mode 100644 index 0000000..828c20b --- /dev/null +++ b/docs/MVP_TRACEABILITY.md @@ -0,0 +1,57 @@ +# Conductor v0.1.0 Requirements Traceability + +## Purpose + +This matrix maps every release-critical requirement area in `docs/REQUIREMENTS.md` and every approved workflow in `MVP_SCOPE.md` to an owning slice and acceptance evidence. It is the governance bridge between product requirements, implementation plans, and validation. Detailed field-level behavior remains authoritative in the linked schema and topic documents. + +## Release-critical requirements + +| ID | v0.1.0 requirement area | Owning slice | Validation criterion and evidence | Status | +|---|---|---|---|---| +| R1 | Browser-based application, React frontend, backend API, SQLite persistence, and Docker Compose deployment | Slices 1, 6, 8 | Production builds, Compose startup/health/restart/persistence, backup/restore in `docs/RELEASE_VALIDATION.md` and `TESTING.md` | Accepted | +| R2 | Canonical JSON project definition shared by Visual Editor, JSON Editor, Preview, persistence, and validation | Slices 2, 5, 6 | Schema matrix, canonical round trips, cross-view synchronization, save/reload/restart tests | Accepted | +| R3 | Single-page visual canvas with the eleven schema-supported components, selection, movement, resizing, deletion, properties, and basic styling | Slices 1, 2 | Slice 1/2 component tests and accepted canvas/property/Preview manual workflows | Accepted | +| R4 | REST actions with supported methods, URL, headers, query/path parameters, body template, description, and fixed proxy-policy timeout | Slices 2, 4 | Action-editor tests, proxy integration/security suites, `docs/SCHEMA.md`, `docs/PROXY_SECURITY.md` | Accepted | +| R5 | Button `onClick` and page `onLoad` execution; component/variable request templates; Table selection runtime binding | Slices 2, 6 | Frontend event/template/runtime tests and deterministic launcher/dashboard E2E | Accepted | +| R6 | Top-level response/component bindings to supported component properties or typed runtime variables | Slices 2, 5, 6 | Binding diagnostics/runtime tests, compatibility validation, dependent-data/dashboard workflows | Accepted | +| R7 | Anonymous, Basic, Bearer, API-key header, and API-key query authentication with opaque canonical references | Slices 3, 6 | All-mode backend integration and manual authenticated-request acceptance | Accepted | +| R8 | Encrypted server-side secret lifecycle, compatible selection, missing-reference behavior, and no browser/project exposure | Slices 3, 6 | `docs/SECRETS.md`, lifecycle tests, restart checks, manual redaction gate | Accepted | +| R9 | Default-deny server-side proxy with URL/header validation, SSRF/redirect/DNS controls, limits, safe errors, and explicit internal exceptions | Slices 4, 6 | `docs/PROXY_SECURITY.md`, proxy security/integration tests, Docker manual gate | Accepted | +| R10 | Sanitized bounded execution history with filtering, persistence, clear behavior, and no credential leakage | Slices 4, 6 | Backend history/redaction tests, frontend history checks, exact marker scans | Accepted | +| R11 | Central schema/semantic validation, atomic persistence, actionable cross-view diagnostics, and unsaved-edit preservation | Slices 5, 6 | Backend rollback/version/semantic tests and Slice 5 manual failure/recovery acceptance | Accepted | +| R12 | Preview runtime with loading, empty, success, upstream failure, mapping failure, retry/recovery, and ephemeral state | Slices 2, 5, 6 | Preview suites and all six deterministic manual workflows | Accepted | +| R13 | Save/load, portable JSON definition, backend/full-stack restart persistence, runtime reset, and SQLite backup/recovery | Slices 2, 5, 6 | Canonical round-trip tests, E2E save/reload, restart and offline backup/restore evidence | Accepted | +| R14 | Accessible, scannable Actions & Bindings authoring with progressive disclosure and preserved local drafts | Slice 6a | 25 frontend suites / 520 tests and `SLICE6a_MANUAL_TEST.md` acceptance | Accepted | + +## Approved acceptance workflows + +| Workflow | Primary requirements | Owning validation slice | Evidence | +|---|---|---|---| +| Workflow Launcher | R2–R6, R11–R13 | Slice 6 | `SLICE6_MANUAL_TEST.md` Test 1 and deterministic E2E | +| Dependent Data | R5, R6, R11, R12 | Slice 6 | `SLICE6_MANUAL_TEST.md` Test 2 and runtime tests | +| Read-Only Dashboard | R3, R5, R6, R12 | Slice 6 | `SLICE6_MANUAL_TEST.md` Test 3 and deterministic E2E | +| Authenticated Request | R4, R7–R10 | Slice 6 | `SLICE6_MANUAL_TEST.md` Test 5 and backend integration | +| JSON Editing and Persistence | R1, R2, R11, R13 | Slice 6 | `SLICE6_MANUAL_TEST.md` Tests 4 and 6 | +| Failure Handling | R9–R12 | Slice 6 | `SLICE6_MANUAL_TEST.md` Test 4 and Slice 5 recovery evidence | + +## Explicit post-MVP classifications + +The following capabilities are not release requirements. Their presence in future-oriented requirements or architecture text does not block v0.1.0: + +- Provider-neutral AI assistance, including chat, generation, explanation, documentation, and refactoring +- IBM Bob, watsonx, or any provider-specific AI dependency +- Multi-page authoring and advanced page management +- Direct Dropdown-triggered REST execution and general action chaining/orchestration +- Conditions, branches, loops, parallelism, retries, workflow graphs, and long-running task orchestration +- OAuth 2.0, IBM Cloud IAM, mTLS, and custom authentication scripts +- OpenAPI import and generated React/static/deployment-package output +- Per-action timeout and expected-response-format controls +- Binding transforms, expression languages, and configurable per-binding error policies +- Canvas zoom/pan, undo/redo, advanced JSON-editor tooling, themes, and reusable component libraries +- Tabs, modals, date pickers, file uploads, charts, progress indicators, and advanced Table capabilities +- RBAC, team collaboration, approval workflows, enterprise audit retention, and SIEM integration +- PostgreSQL/high-availability/centralized multi-user deployment + +## Governance rule + +`MVP_SCOPE.md` controls the release boundary. A new capability becomes release-blocking only through an explicit product-owner scope decision followed by updates to this matrix, `ROADMAP.md`, the owning slice, and its validation criteria. Aspirational or compatibility-only schema text does not silently expand v0.1.0. diff --git a/docs/REQUIREMENTS.md b/docs/REQUIREMENTS.md index 4689215..f780f33 100644 --- a/docs/REQUIREMENTS.md +++ b/docs/REQUIREMENTS.md @@ -1,6 +1,10 @@ # REQUIREMENTS.md -# Project: AI-Assisted REST UI Builder +# Project: Conductor REST UI Builder + +## Scope Authority + +`MVP_SCOPE.md` is the approved v0.1.0 release boundary. `ROADMAP.md` maps that boundary to implementation slices, and `docs/MVP_TRACEABILITY.md` maps each release-critical requirement area to validation evidence. Statements labeled **Post-MVP** are intentionally excluded from v0.1.0 and do not block release. ## 1. Purpose @@ -8,7 +12,7 @@ Build a lightweight UI builder that allows users to create simple frontend appli The tool should allow users to drag and drop UI elements onto a canvas, configure those elements, connect them to REST API calls, and allow one UI element to update another based on API responses or user interaction. -IBM Bob / watsonx should assist with generating, configuring, documenting, and refining these UI applications. +The v0.1.0 application has no AI dependency. Provider-neutral AI assistance may generate, configure, document, or refine project definitions in a future post-MVP increment. --- @@ -22,7 +26,7 @@ The system should: * Support multiple authentication types, including anonymous access. * Allow API responses to update other UI components. * Make it easier for CSMs, architects, and technical users to build working demos or operational tools without hand-coding every frontend. -* Use AI assistance to speed up configuration, explanation, and generation of UI/API bindings. +* Preserve a canonical project model that future provider-neutral tooling can inspect and modify safely. --- @@ -178,10 +182,10 @@ Each REST API action shall support: * Path parameters * Request body * Authentication type -* Timeout setting -* Expected response format +* JSON request bodies where the selected method sends a body +* JSON and safely represented non-JSON responses through the proxy -The system should support JSON request and response bodies in the MVP. +The backend applies the fixed v0.1.0 proxy-policy timeout. Per-action timeout and expected-response-format controls are post-MVP because schema version `0.1.0` has no such fields. ## 6.5 Authentication Support @@ -209,10 +213,11 @@ The system shall allow a UI component to trigger a REST API action. Examples: * Button click calls an API endpoint. -* Dropdown selection calls an API endpoint. * Page load calls an API endpoint. * Table row selection updates another component. +Dropdown selections may supply values to a later Button-triggered request. Direct Dropdown-triggered REST execution is post-MVP. + The system shall allow component values to be used in API requests. Examples: @@ -243,9 +248,9 @@ Example: } ``` -## 6.8 AI Assistance +## 6.8 AI Assistance — Post-MVP -IBM Bob / watsonx should assist users by: +AI assistance is not a v0.1.0 requirement. Any future integration must be provider-neutral and may assist users by: * Suggesting UI layouts from a natural language prompt. * Generating REST API action definitions. @@ -260,7 +265,7 @@ Example prompt: > Build a form that lets me select an environment, enter a hostname, and call a Rapid Infrastructure Automation workflow to provision monitoring. -The AI assistant should produce a proposed page layout, components, API bindings, and configuration steps. +A future AI assistant should produce a proposed page layout, components, API bindings, and configuration steps without becoming required for normal product operation. ## 6.9 Save and Load @@ -272,11 +277,10 @@ A saved project should include: * Canvas layout * Components * API action definitions -* Component bindings -* Response mappings +* Top-level component and response bindings * Non-secret configuration -Secrets should not be stored directly in exported project files unless encrypted or intentionally allowed by policy. +Secret values shall not be stored in or exported with project definitions. Credential-backed actions contain only opaque server-side references. ## 6.10 Preview Mode @@ -318,9 +322,9 @@ The Visual Editor shall provide: * Property editing * Event configuration * Component binding configuration -* Visual indication of selected components -* Canvas zoom and pan -* Undo and redo operations (future enhancement) +* Clear selected-component indication + +Canvas zoom/pan and undo/redo are post-MVP enhancements. Changes made through the Visual Editor shall immediately update the project's canonical JSON definition. @@ -330,14 +334,13 @@ Conductor shall provide a JSON Editor for advanced users. The JSON Editor shall allow users to directly edit the project's canonical JSON document. -The JSON Editor should provide: +The v0.1.0 JSON Editor provides: -* Syntax highlighting -* Automatic formatting * Schema validation * Error reporting -* Search and replace -* Read-only and editable modes +* Editable canonical JSON with explicit Apply behavior + +Syntax highlighting, automatic formatting, search/replace, and a separate read-only mode are post-MVP editor enhancements. Changes made through the JSON Editor shall immediately update the Visual Editor. @@ -391,7 +394,8 @@ A component contains: * Size * Properties * Events -* Bindings + +Canonical response and component bindings are stored in top-level `project.bindings`, not inside component records. ## 7.4 API Action @@ -405,7 +409,8 @@ An API action contains: * Parameters * Body template * Authentication configuration -* Response mapping + +Canonical response mappings are top-level `project.bindings`. The legacy action-local `responseMapping` field is compatibility-only and is not executed. ## 7.5 Binding @@ -416,8 +421,8 @@ A binding contains: * Source * Target * Trigger event -* Transformation rule -* Error handling behavior + +The schema-retained `transform` field and configurable per-binding error policies are compatibility/future shapes and are not executed in v0.1.0. ## 7.6 Project Definition Document @@ -444,7 +449,7 @@ The backend shall persist this project definition as JSON. The backend may extract selected metadata into relational database fields for indexing, searching, reporting, or performance optimization, but the JSON project definition remains the canonical representation. -A project definition should be portable between Conductor installations and suitable for export, import, version control, and AI-assisted modification. +A project definition should be portable between Conductor installations and suitable for export, import, version control, and future tool-assisted modification. Example capabilities enabled by this approach include: @@ -452,11 +457,11 @@ Example capabilities enabled by this approach include: * Importing existing applications. * Versioning projects in Git. * Comparing changes between revisions. -* AI-assisted editing of complete applications. +* Future provider-neutral assisted editing of complete applications. * Generating documentation from the project definition. * Generating frontend code from the project definition. -Future versions of Conductor may define a published JSON schema describing the project definition format to support validation, tooling, and interoperability. +Conductor publishes the v0.1.0 project schema at `shared/schemas/conductor-project.schema.json` for validation, tooling, and interoperability. --- @@ -499,7 +504,7 @@ Recommended backend capabilities: * Secret handling * Authentication configuration storage * API execution logging for troubleshooting -* AI assistant integration +* Provider-neutral AI assistant integration (post-MVP) ## 9.3 Security @@ -511,7 +516,7 @@ The system must: * Support anonymous API calls where appropriate. * Prevent arbitrary unsafe code execution in user-defined mappings. * Validate URLs and headers before execution. -* Consider allowlists for internal endpoint access. +* Enforce the default-deny destination policy and require explicit exceptions for approved internal origins. ## 9.4 Observability @@ -539,7 +544,8 @@ The MVP should include: * API response-to-component binding. * Preview mode. * Save/load project as JSON. -* IBM Bob/watsonx-assisted generation of project configuration. + +The MVP does not include IBM Bob, watsonx, or any other AI dependency. --- @@ -551,7 +557,7 @@ Potential future enhancements: * Role-based access control. * OAuth support. * IBM Cloud IAM integration. -* Workflow execution history. +* Advanced or enterprise execution-history retention and integrations. * Generated React code export. * Import from OpenAPI specification. * Visual JSON path mapper. @@ -565,18 +571,17 @@ Potential future enhancements: --- -## 12. Open Questions +## 12. Resolved MVP Decisions -* Should this be a standalone internal tool or embedded into another IBM workflow? -* Will API calls execute directly from the browser or through a backend proxy? -* How should secrets be stored and managed? -* Which Concert/RIA authentication methods are required first? -* Should OpenAPI import be part of MVP or future scope? -* Is the primary output a working hosted UI, a generated React app, or a reusable project definition? -* What level of audit logging is required for internal IBM use? -* Should users be allowed to call arbitrary URLs? -* Will the tool need approval before calling production endpoints? -* Should IBM Bob generate only suggestions, or should it directly modify the canvas? +* Conductor v0.1.0 is a standalone web application deployed locally or behind an operator-managed reverse proxy. +* REST calls execute through the backend proxy; credential-backed calls never execute directly from the browser. +* Secrets use encrypted server-side storage and opaque project references as documented in `docs/SECRETS.md`. +* All five modeled authentication modes are required. +* OpenAPI import, generated React output, and provider-neutral AI assistance are post-MVP. +* The primary v0.1.0 output is a working hosted UI backed by a portable canonical project definition. +* Sanitized local execution history is required; enterprise audit retention and SIEM integration are post-MVP. +* Proxy destinations are governed by the default-deny policy and explicit exceptions in `docs/PROXY_SECURITY.md`; arbitrary unsafe URLs are not allowed. +* Production-endpoint approval workflows are an operator policy and post-MVP product capability. --- @@ -589,8 +594,8 @@ The MVP is successful if a user can: * Pass values from UI components into the API request. * Display the API response in another UI component. * Save and reload the project. -* Use IBM Bob/watsonx to generate or improve part of the UI/API configuration. * Demonstrate a working Concert/RIA workflow launcher. +* Complete all six approved workflows in `MVP_SCOPE.md` without an AI dependency. ## Web Application Requirement @@ -639,7 +644,7 @@ Frontend static assets + Backend API service REST API endpoints / Concert / RIA / other systems ``` -The backend service should focus on application logic, project storage, authentication handling, secret management, REST API proxying, and AI integration. +The backend service should focus on application logic, project storage, authentication handling, secret management, REST API proxying, validation, and sanitized execution history. ## Backend Persistence Requirement @@ -650,15 +655,9 @@ For the MVP, SQLite is the preferred database. SQLite should store: * Projects -* Pages -* UI components -* Component layout data -* REST API action definitions -* Component-to-component bindings -* Component-to-API bindings -* Non-secret configuration -* Basic execution history -* Error/debug logs +* Canonical project JSON, which contains pages, components, layout, actions, bindings, variables, settings, and non-secret configuration +* Encrypted secret records and metadata +* Sanitized bounded execution history Secrets should not be stored directly in plain text in SQLite. diff --git a/package.json b/package.json index 1f091b6..ebf8f9c 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,7 @@ { "scripts": { "test:e2e": "playwright test", + "test:governance": "node scripts/check-mvp-governance.mjs", "test:schema": "bash scripts/validate-schema.sh" }, "devDependencies": { diff --git a/scripts/check-mvp-governance.mjs b/scripts/check-mvp-governance.mjs new file mode 100644 index 0000000..1b88c5b --- /dev/null +++ b/scripts/check-mvp-governance.mjs @@ -0,0 +1,60 @@ +import fs from 'node:fs'; +import path from 'node:path'; +import process from 'node:process'; + +const root = process.cwd(); +const read = (file) => fs.readFileSync(path.join(root, file), 'utf8'); +const failures = []; + +const scope = read('MVP_SCOPE.md'); +const requirements = read('docs/REQUIREMENTS.md'); +const readme = read('README.md'); +const roadmap = read('ROADMAP.md'); +const traceability = read('docs/MVP_TRACEABILITY.md'); + +const requireText = (file, text, label) => { + if (!read(file).includes(text)) failures.push(`${file}: missing ${label}`); +}; + +requireText('MVP_SCOPE.md', 'The initial MVP has no AI dependency.', 'approved no-AI boundary'); +requireText('docs/REQUIREMENTS.md', '`MVP_SCOPE.md` is the approved v0.1.0 release boundary.', 'scope authority'); +requireText('docs/REQUIREMENTS.md', '## 12. Resolved MVP Decisions', 'resolved-decision section'); +requireText('docs/MVP_TRACEABILITY.md', '## Release-critical requirements', 'requirements matrix'); +requireText('docs/MVP_TRACEABILITY.md', '## Explicit post-MVP classifications', 'post-MVP classification'); + +for (const [file, text, pattern] of [ + ['README.md', readme, /AI Assistance.*IBM Bob|watsonx can generate/i], + ['docs/REQUIREMENTS.md', requirements, /IBM Bob \/ watsonx should assist|Use IBM Bob\/watsonx to generate/i], + ['docs/REQUIREMENTS.md', requirements, /^## 12\. Open Questions$/m], + ['docs/REQUIREMENTS.md', requirements, /^\* Timeout setting$/m], + ['docs/REQUIREMENTS.md', requirements, /^\* Expected response format$/m], +]) { + if (pattern.test(text)) failures.push(`${file}: forbidden stale MVP claim matches ${pattern}`); +} + +if (/^- \[ \]/m.test(scope)) failures.push('MVP_SCOPE.md: an accepted workflow checkbox is unchecked'); +if (!roadmap.includes('| [Slice 7](SLICE7.md) | MVP scope decision and requirement governance | Complete | None |')) { + failures.push('ROADMAP.md: Slice 7 is not recorded as complete with no remaining gate'); +} + +const linkedFiles = ['README.md', 'MVP_SCOPE.md', 'ROADMAP.md', 'SLICE7.md', 'docs/REQUIREMENTS.md', 'docs/ARCHITECTURE.md', 'docs/MVP_TRACEABILITY.md']; +for (const file of linkedFiles) { + for (const match of read(file).matchAll(/\[[^\]]+\]\(([^)]+)\)/g)) { + const target = match[1].split('#')[0]; + if (!target || /^[a-z]+:/i.test(target)) continue; + if (!fs.existsSync(path.resolve(root, path.dirname(file), target))) { + failures.push(`${file}: unresolved relative link ${target}`); + } + } +} + +for (let id = 1; id <= 14; id += 1) { + if (!traceability.includes(`| R${id} |`)) failures.push(`docs/MVP_TRACEABILITY.md: missing R${id}`); +} + +if (failures.length > 0) { + console.error(failures.join('\n')); + process.exit(1); +} + +console.log('MVP governance check passed: scope, traceability, classifications, and links are consistent.');