@jterrats/open-orchestra 1.0.4 → 1.0.6
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/autonomous-phase-lifecycle.js +19 -0
- package/dist/autonomous-phase-lifecycle.js.map +1 -1
- package/dist/autonomous-run-store.d.ts +2 -1
- package/dist/autonomous-run-store.js +4 -0
- package/dist/autonomous-run-store.js.map +1 -1
- package/dist/autonomous-workflow-constants.d.ts +1 -6
- package/dist/autonomous-workflow-constants.js +1 -33
- package/dist/autonomous-workflow-constants.js.map +1 -1
- package/dist/cli.js +7 -1
- package/dist/cli.js.map +1 -1
- package/dist/command-manifest.js +3 -1
- package/dist/command-manifest.js.map +1 -1
- package/dist/commands.d.ts +1 -1
- package/dist/commands.js +1 -1
- package/dist/commands.js.map +1 -1
- package/dist/constants.d.ts +2 -4
- package/dist/constants.js +7 -21
- package/dist/constants.js.map +1 -1
- package/dist/defaults.d.ts +1 -0
- package/dist/defaults.js +1 -0
- package/dist/defaults.js.map +1 -1
- package/dist/delegation-decision.js +4 -5
- package/dist/delegation-decision.js.map +1 -1
- package/dist/delivery-dashboard.js +2 -1
- package/dist/delivery-dashboard.js.map +1 -1
- package/dist/phase-playbooks.js +10 -32
- package/dist/phase-playbooks.js.map +1 -1
- package/dist/qa-readiness.js +2 -2
- package/dist/qa-readiness.js.map +1 -1
- package/dist/release-readiness.js +3 -6
- package/dist/release-readiness.js.map +1 -1
- package/dist/runtime-bootstrap.js +9 -1
- package/dist/runtime-bootstrap.js.map +1 -1
- package/dist/runtime-commands.d.ts +2 -0
- package/dist/runtime-commands.js +44 -1
- package/dist/runtime-commands.js.map +1 -1
- package/dist/runtime-execution-adapters.js +44 -4
- package/dist/runtime-execution-adapters.js.map +1 -1
- package/dist/runtime-execution-renderer.d.ts +7 -1
- package/dist/runtime-execution-renderer.js +63 -0
- package/dist/runtime-execution-renderer.js.map +1 -1
- package/dist/runtime-execution.d.ts +20 -1
- package/dist/runtime-execution.js +174 -0
- package/dist/runtime-execution.js.map +1 -1
- package/dist/runtime-guardrails.js +3 -0
- package/dist/runtime-guardrails.js.map +1 -1
- package/dist/runtime-spawn-bridge.d.ts +25 -0
- package/dist/runtime-spawn-bridge.js +172 -0
- package/dist/runtime-spawn-bridge.js.map +1 -0
- package/dist/runtime-spawn-guidance.d.ts +3 -0
- package/dist/runtime-spawn-guidance.js +52 -0
- package/dist/runtime-spawn-guidance.js.map +1 -0
- package/dist/skills-catalog.js +66 -0
- package/dist/skills-catalog.js.map +1 -1
- package/dist/skills-planning.js +6 -20
- package/dist/skills-planning.js.map +1 -1
- package/dist/subagent-protocol.js +6 -1
- package/dist/subagent-protocol.js.map +1 -1
- package/dist/task-graph-commands.js +3 -12
- package/dist/task-graph-commands.js.map +1 -1
- package/dist/task-split-assessment.d.ts +19 -0
- package/dist/task-split-assessment.js +190 -0
- package/dist/task-split-assessment.js.map +1 -0
- package/dist/task-status.d.ts +22 -0
- package/dist/task-status.js +83 -0
- package/dist/task-status.js.map +1 -0
- package/dist/telemetry-export.js +19 -24
- package/dist/telemetry-export.js.map +1 -1
- package/dist/telemetry-records.js +2 -1
- package/dist/telemetry-records.js.map +1 -1
- package/dist/tracker-commands.js +2 -2
- package/dist/tracker-commands.js.map +1 -1
- package/dist/types/model-config.d.ts +2 -0
- package/dist/types/runtime.d.ts +33 -1
- package/dist/types/tasks.d.ts +1 -0
- package/dist/types/workflow-run.d.ts +16 -0
- package/dist/types.d.ts +2 -2
- package/dist/types.js.map +1 -1
- package/dist/web-api.js +24 -2
- package/dist/web-api.js.map +1 -1
- package/dist/web-roles.js +2 -1
- package/dist/web-roles.js.map +1 -1
- package/dist/web-runtime-actions.d.ts +4 -0
- package/dist/web-runtime-actions.js +53 -0
- package/dist/web-runtime-actions.js.map +1 -0
- package/dist/workflow-approval-service.js +14 -18
- package/dist/workflow-approval-service.js.map +1 -1
- package/dist/workflow-background-subagents.d.ts +13 -0
- package/dist/workflow-background-subagents.js +80 -0
- package/dist/workflow-background-subagents.js.map +1 -0
- package/dist/workflow-phase-planner.d.ts +4 -2
- package/dist/workflow-phase-planner.js +31 -43
- package/dist/workflow-phase-planner.js.map +1 -1
- package/dist/workflow-phases.d.ts +15 -0
- package/dist/workflow-phases.js +86 -0
- package/dist/workflow-phases.js.map +1 -0
- package/dist/workflow-run-commands.js +127 -2
- package/dist/workflow-run-commands.js.map +1 -1
- package/dist/workflow-services.js +4 -2
- package/dist/workflow-services.js.map +1 -1
- package/dist/workflow-task-service.js +15 -20
- package/dist/workflow-task-service.js.map +1 -1
- package/docs/autonomous-workflow.md +34 -0
- package/docs/duplicate-code-enforcement.md +60 -0
- package/docs/release-test-matrix.md +14 -0
- package/docs/reports/duplicate-code-baseline-20260518.md +41 -0
- package/docs/runtime-adapters.md +96 -4
- package/docs/runtime-llm-flow.md +4 -2
- package/docs/secret-scanning-gitleaks.md +53 -0
- package/docs/site-manifest.json +5 -0
- package/docs/sonar-architecture-model.md +178 -0
- package/docs/sonar-quality-gates.md +178 -0
- package/docs/task-split-assessment.md +34 -0
- package/package.json +5 -1
- package/skills/oclif-plugin-development/SKILL.md +118 -0
- package/skills/oclif-plugin-development/manifest.json +58 -0
package/docs/runtime-adapters.md
CHANGED
|
@@ -26,6 +26,13 @@ packet:
|
|
|
26
26
|
|
|
27
27
|
- `codex-cli`: use the current Codex CLI/session. Tool permissions and shell
|
|
28
28
|
approvals stay inside Codex; Orchestra renders briefs and packets only.
|
|
29
|
+
- `claude-cli`: use the current Claude Code session. Orchestra renders the
|
|
30
|
+
packet and the Claude parent launches it with the native Agent/Subagent tool
|
|
31
|
+
when available; `Task` is treated as a legacy alias if that is what the
|
|
32
|
+
runtime exposes.
|
|
33
|
+
- `cursor-cli`: use the current Cursor runtime. Orchestra renders the packet
|
|
34
|
+
and the Cursor parent launches it as a Background Agent so the current chat
|
|
35
|
+
remains usable while the child works.
|
|
29
36
|
- `opencode-cli`: use an authenticated OpenCode CLI with its own provider
|
|
30
37
|
config. Orchestra uses the generic instruction target and never copies
|
|
31
38
|
provider keys into workflow artifacts.
|
|
@@ -144,12 +151,95 @@ orchestra runtime sessions --task STORY-001 --json
|
|
|
144
151
|
orchestra runtime session --session STORY-001:claude-cli --action suspend --json
|
|
145
152
|
orchestra runtime session --session STORY-001:claude-cli --action resume --json
|
|
146
153
|
orchestra runtime session --session STORY-001:claude-cli --action cancel --json
|
|
154
|
+
orchestra runtime spawn-request --task STORY-001 --role developer --runtime codex-cli --json
|
|
155
|
+
orchestra runtime spawn-lifecycle --session STORY-001:manual:developer:codex-cli --status spawned --agent-id <runtime-agent-id> --json
|
|
147
156
|
```
|
|
148
157
|
|
|
149
|
-
The matching
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
158
|
+
The matching local APIs are `GET /api/runtime/sessions`,
|
|
159
|
+
`POST /api/runtime/spawn-request`, and `POST /api/runtime/spawn-lifecycle`.
|
|
160
|
+
Session operations do not kill external provider processes directly; they
|
|
161
|
+
record auditable suspend, resume, cancel, close, spawned, active, completed,
|
|
162
|
+
failed, or timed-out events so the parent runtime can reconcile claimed work,
|
|
163
|
+
spawned agent ids, stale sessions, and handoff state without inventing a second
|
|
164
|
+
source of truth.
|
|
165
|
+
|
|
166
|
+
## Native Background Agent Notes
|
|
167
|
+
|
|
168
|
+
Claude Code and Cursor do not need Orchestra to call vendor APIs directly.
|
|
169
|
+
They need a precise packet and lifecycle hooks:
|
|
170
|
+
|
|
171
|
+
- Claude Code: render `runtime spawn-request`, then launch the packet from the
|
|
172
|
+
parent Claude session with the native Agent/Subagent tool. If the local
|
|
173
|
+
Claude runtime exposes `Task` as the tool name, treat it as the compatible
|
|
174
|
+
legacy alias. Record the returned child id or role label through
|
|
175
|
+
`runtime spawn-lifecycle`.
|
|
176
|
+
- Cursor: render `runtime spawn-request`, then launch it as a Cursor Background
|
|
177
|
+
Agent. Background work should stay detached from the current chat and report
|
|
178
|
+
lifecycle state back to Orchestra before the workflow is resumed.
|
|
179
|
+
- All runtimes: keep `directProviderApiAllowed=false`, keep child prompts
|
|
180
|
+
scoped to the request artifact, avoid full transcript transfer, and record a
|
|
181
|
+
terminal lifecycle event before marking the phase complete.
|
|
182
|
+
|
|
183
|
+
The current vendor behavior this maps to is:
|
|
184
|
+
|
|
185
|
+
- Claude Code supports custom subagents with separate context and allows direct
|
|
186
|
+
subagent invocation from the parent session.
|
|
187
|
+
- Cursor Background Agents run isolated remote agents in parallel and can be
|
|
188
|
+
launched while the user continues working.
|
|
189
|
+
|
|
190
|
+
## Workflow Phase Executors
|
|
191
|
+
|
|
192
|
+
`workflow run` can plan how each phase should be executed without confusing the
|
|
193
|
+
role/profile with the runtime executor:
|
|
194
|
+
|
|
195
|
+
- **Role/profile**: PM, PO, Architect, Developer, QA, Release, or another phase
|
|
196
|
+
owner. This controls responsibilities, playbooks, expected evidence, and gate
|
|
197
|
+
authority.
|
|
198
|
+
- **Runtime executor**: `codex-cli`, `claude-cli`, `cursor-cli`,
|
|
199
|
+
`opencode-cli`, `vscode-agent`, `windsurf-agent`, or `generic-runtime`.
|
|
200
|
+
This controls where the brief or delegation packet is intended to run.
|
|
201
|
+
- **Subagent**: a runtime-native role-scoped execution unit, only available
|
|
202
|
+
when the selected runtime adapter declares `subagents.runtimeNative: true`
|
|
203
|
+
and a supported `subagents.spawn.mode`.
|
|
204
|
+
- **Spawn bridge**: the runtime-specific mechanism for creating that child
|
|
205
|
+
execution. Modes are `unsupported`, `request-only`, `parent-tool`, and
|
|
206
|
+
`local-process`. `codex-cli` is the first `parent-tool` bridge and renders a
|
|
207
|
+
`spawn_agent` request for the active Codex parent session; other runtimes can
|
|
208
|
+
consume the same request artifact without allowing Orchestra to call vendor
|
|
209
|
+
APIs directly.
|
|
210
|
+
- **Provider**: a direct model/provider route used by provider-backed phase
|
|
211
|
+
prompts. Provider APIs are separate from runtime-native subagents and are
|
|
212
|
+
never used as a silent fallback for runtime delegation.
|
|
213
|
+
|
|
214
|
+
The workflow phase execution mode can be selected per run:
|
|
215
|
+
|
|
216
|
+
```bash
|
|
217
|
+
orchestra workflow run --task STORY-001 --phase-execution auto
|
|
218
|
+
orchestra workflow run --task STORY-001 --phase-execution subagents
|
|
219
|
+
orchestra workflow run --task STORY-001 --phase-execution single-agent
|
|
220
|
+
```
|
|
221
|
+
|
|
222
|
+
`auto` uses runtime spawn request artifacts when the selected runtime supports
|
|
223
|
+
them and delegation guardrails allow the spawn; otherwise it records a
|
|
224
|
+
parent-agent fallback reason. `subagents` requires runtime-native support and
|
|
225
|
+
fails fast if the runtime cannot satisfy it. `single-agent` forces the parent
|
|
226
|
+
agent path and records that choice in phase provenance.
|
|
227
|
+
|
|
228
|
+
Subagent spawning is bounded by `runtimePolicy.delegation.guardrails`.
|
|
229
|
+
`maxConcurrentDelegates` is the threshold for simultaneously running delegated
|
|
230
|
+
sessions, `maxSpawnsPerTask` limits fan-out for one task, and `limitAction`
|
|
231
|
+
controls whether pressure should `queue` or `reject`. With the default `queue`
|
|
232
|
+
policy, a phase that cannot acquire capacity is paused as a queued runtime
|
|
233
|
+
subagent instead of silently falling back to the parent agent. Resume the
|
|
234
|
+
workflow after capacity is released.
|
|
235
|
+
|
|
236
|
+
Each phase stores executor provenance in the workflow run and handoff:
|
|
237
|
+
execution mode, executor type, phase, role, runtime id, delegation packet path
|
|
238
|
+
or spawn request path when one was rendered, session id when available,
|
|
239
|
+
fallback reason, and `directProviderApiAllowed=false`. Spawn request artifacts
|
|
240
|
+
include the phase, role, session id, parent tool name when applicable, prompt
|
|
241
|
+
artifact, expected result artifact, ownership paths, queue status, and the
|
|
242
|
+
guardrail evaluation so the parent runtime can prove what was delegated.
|
|
153
243
|
|
|
154
244
|
Cursor canvas sync is intentionally runtime-specific:
|
|
155
245
|
|
|
@@ -200,5 +290,7 @@ The stable inspection commands are:
|
|
|
200
290
|
orchestra runtime adapters --json
|
|
201
291
|
orchestra runtime brief --task <id> --runtime codex-cli --json
|
|
202
292
|
orchestra runtime delegate-plan --task <id> --runtime opencode-cli --roles qa --json
|
|
293
|
+
orchestra runtime spawn-request --task <id> --role developer --runtime codex-cli --json
|
|
294
|
+
orchestra runtime spawn-lifecycle --session <id> --status completed --agent-id <id> --json
|
|
203
295
|
orchestra model providers --json
|
|
204
296
|
```
|
package/docs/runtime-llm-flow.md
CHANGED
|
@@ -223,8 +223,10 @@ budget fallback.
|
|
|
223
223
|
approval.
|
|
224
224
|
- Runtime execution adapters render briefs and delegation packets, but they do
|
|
225
225
|
not yet launch external CLI/IDE processes non-interactively.
|
|
226
|
-
-
|
|
227
|
-
|
|
226
|
+
- `workflow run --phase-execution auto|subagents|single-agent` records phase
|
|
227
|
+
executor provenance and can render role-scoped runtime-native delegation
|
|
228
|
+
packets, but the parent runtime still owns any real spawn/interaction with
|
|
229
|
+
external CLI or IDE subagents.
|
|
228
230
|
- Parallel independent CLI commands are expected to work, but dependent commands
|
|
229
231
|
still need parent-agent ordering or future DAG semantics.
|
|
230
232
|
- Workflow files are local state. Promote durable lessons into docs, skills, or
|
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
# Secret Scanning With Gitleaks
|
|
2
|
+
|
|
3
|
+
Open Orchestra uses Gitleaks as the primary repository secret-scanning gate.
|
|
4
|
+
The lightweight Node scanner remains as a local fallback when the `gitleaks`
|
|
5
|
+
binary is not installed.
|
|
6
|
+
|
|
7
|
+
## Local Use
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
npm run secret-scan
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
When `gitleaks` is available on `PATH`, the command runs:
|
|
14
|
+
|
|
15
|
+
```bash
|
|
16
|
+
gitleaks dir . --config .gitleaks.toml --redact --no-banner
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
When the binary is unavailable, the fallback scanner checks common private key,
|
|
20
|
+
cloud key, token, password, and API key patterns so offline development still
|
|
21
|
+
has a minimum guardrail.
|
|
22
|
+
|
|
23
|
+
## CI
|
|
24
|
+
|
|
25
|
+
The CI quality job installs the pinned Gitleaks binary and runs it before the
|
|
26
|
+
precommit gate. The precommit gate then calls `npm run secret-scan`, which uses
|
|
27
|
+
the same Gitleaks configuration in CI because the binary is already installed.
|
|
28
|
+
|
|
29
|
+
## Configuration
|
|
30
|
+
|
|
31
|
+
Rules live in `.gitleaks.toml` and extend the default Gitleaks ruleset.
|
|
32
|
+
Allowlists are limited to generated/dependency paths and explicit placeholder
|
|
33
|
+
values such as `<secret>` or GitHub Actions `${{ secrets.NAME }}` references.
|
|
34
|
+
|
|
35
|
+
Do not allowlist real secrets. Rotate and purge the secret instead.
|
|
36
|
+
|
|
37
|
+
## Operational SaaS Boundary
|
|
38
|
+
|
|
39
|
+
Repository scanning is not enough for a SaaS/runtime deployment. Runtime inputs
|
|
40
|
+
also need secret and prompt-injection guardrails before agents or providers can
|
|
41
|
+
read them:
|
|
42
|
+
|
|
43
|
+
- prompts
|
|
44
|
+
- lessons learned
|
|
45
|
+
- evidence
|
|
46
|
+
- logs
|
|
47
|
+
- uploaded artifacts
|
|
48
|
+
- model outputs
|
|
49
|
+
- GitHub issue bodies and comments
|
|
50
|
+
- tenant integrations
|
|
51
|
+
|
|
52
|
+
Operational scans must redact or quarantine findings, record provenance, and
|
|
53
|
+
apply tenant-specific retention and regulatory policies.
|
package/docs/site-manifest.json
CHANGED
|
@@ -112,6 +112,9 @@
|
|
|
112
112
|
"links": [
|
|
113
113
|
{ "title": "Adoption guide", "source": "docs/adoption-guide.md", "heading": "Open Orchestra 1.0.0 Adoption Guide" },
|
|
114
114
|
{ "title": "Core command surface", "source": "docs/core-command-surface.md", "heading": "Core Command Surface" },
|
|
115
|
+
{ "title": "Duplicate-code enforcement", "source": "docs/duplicate-code-enforcement.md", "heading": "Duplicate-Code Enforcement" },
|
|
116
|
+
{ "title": "Sonar quality gates", "source": "docs/sonar-quality-gates.md", "heading": "Sonar Quality Gates" },
|
|
117
|
+
{ "title": "Sonar architecture model", "source": "docs/sonar-architecture-model.md", "heading": "Sonar Architecture Model" },
|
|
115
118
|
{ "title": "Runtime adapters", "source": "docs/runtime-adapters.md", "heading": "Runtime Adapters" },
|
|
116
119
|
{ "title": "Site content workflow", "source": "docs/site-content-workflow.md", "heading": "Public Site Content Workflow" }
|
|
117
120
|
]
|
|
@@ -119,6 +122,8 @@
|
|
|
119
122
|
"releaseDocs": {
|
|
120
123
|
"links": [
|
|
121
124
|
{ "title": "Release test matrix", "source": "docs/release-test-matrix.md", "heading": "1.0.0 Release Test Matrix" },
|
|
125
|
+
{ "title": "Sonar quality gates", "source": "docs/sonar-quality-gates.md", "heading": "Sonar Quality Gates" },
|
|
126
|
+
{ "title": "Sonar architecture model", "source": "docs/sonar-architecture-model.md", "heading": "Sonar Architecture Model" },
|
|
122
127
|
{ "title": "QA evidence", "source": "docs/site-content-workflow.md", "heading": "QA Evidence" },
|
|
123
128
|
{ "title": "Package naming", "source": "docs/package-naming.md", "heading": "Package Naming Decision" },
|
|
124
129
|
{ "title": "Upgrade dogfooding", "source": "README.md", "heading": "Quick Start" }
|
|
@@ -0,0 +1,178 @@
|
|
|
1
|
+
# Sonar Architecture Model
|
|
2
|
+
|
|
3
|
+
This document defines the intended module boundaries that Sonar architecture
|
|
4
|
+
analysis should eventually enforce for Open Orchestra. Until Sonar-specific
|
|
5
|
+
directives are configured, this is the portable source of truth for architecture
|
|
6
|
+
review, code review, and workflow gate evidence.
|
|
7
|
+
|
|
8
|
+
## Domains
|
|
9
|
+
|
|
10
|
+
### CLI and Command Surface
|
|
11
|
+
|
|
12
|
+
Files:
|
|
13
|
+
|
|
14
|
+
- `bin/`
|
|
15
|
+
- `src/*-commands.ts`
|
|
16
|
+
- `src/commands.ts`
|
|
17
|
+
|
|
18
|
+
Responsibilities:
|
|
19
|
+
|
|
20
|
+
- parse command input;
|
|
21
|
+
- call domain services;
|
|
22
|
+
- format CLI output;
|
|
23
|
+
- avoid business logic beyond validation and dispatch.
|
|
24
|
+
|
|
25
|
+
Expected dependencies:
|
|
26
|
+
|
|
27
|
+
- may depend on domain services, workflow services, config loaders, and typed
|
|
28
|
+
output helpers;
|
|
29
|
+
- must not own persistence rules, workflow state transitions, provider routing,
|
|
30
|
+
or web UI behavior.
|
|
31
|
+
|
|
32
|
+
### Workflow and Delivery Domain
|
|
33
|
+
|
|
34
|
+
Files:
|
|
35
|
+
|
|
36
|
+
- `src/workflow*.ts`
|
|
37
|
+
- `src/task*.ts`
|
|
38
|
+
- `src/release*.ts`
|
|
39
|
+
- `src/review*.ts`
|
|
40
|
+
- `src/evidence*.ts`
|
|
41
|
+
- `src/qa*.ts`
|
|
42
|
+
|
|
43
|
+
Responsibilities:
|
|
44
|
+
|
|
45
|
+
- task lifecycle;
|
|
46
|
+
- workflow phases and gates;
|
|
47
|
+
- handoffs, reviews, evidence, acceptance coverage, release readiness.
|
|
48
|
+
|
|
49
|
+
Expected dependencies:
|
|
50
|
+
|
|
51
|
+
- may depend on persistence helpers, domain types, policy checks, and prompt
|
|
52
|
+
registry services;
|
|
53
|
+
- should expose narrow service APIs for command and web entry points.
|
|
54
|
+
|
|
55
|
+
### Runtime, Model, Budget, and Telemetry
|
|
56
|
+
|
|
57
|
+
Files:
|
|
58
|
+
|
|
59
|
+
- `src/model*.ts`
|
|
60
|
+
- `src/runtime*.ts`
|
|
61
|
+
- `src/budget*.ts`
|
|
62
|
+
- `src/telemetry*.ts`
|
|
63
|
+
|
|
64
|
+
Responsibilities:
|
|
65
|
+
|
|
66
|
+
- provider routing;
|
|
67
|
+
- model provenance;
|
|
68
|
+
- cost, token, runtime, and budget controls;
|
|
69
|
+
- telemetry consent, export, and submission audit.
|
|
70
|
+
|
|
71
|
+
Expected dependencies:
|
|
72
|
+
|
|
73
|
+
- may depend on workflow identifiers and policy/config types;
|
|
74
|
+
- must not depend on UI code or generated site assets.
|
|
75
|
+
|
|
76
|
+
### Profiles, Roles, Skills, and Guidance
|
|
77
|
+
|
|
78
|
+
Files:
|
|
79
|
+
|
|
80
|
+
- `src/profiles/`
|
|
81
|
+
- `src/roles/`
|
|
82
|
+
- `src/skills*.ts`
|
|
83
|
+
- `src/generators/`
|
|
84
|
+
- `src/prompt*.ts`
|
|
85
|
+
- `skills/`
|
|
86
|
+
- `rules/`
|
|
87
|
+
|
|
88
|
+
Responsibilities:
|
|
89
|
+
|
|
90
|
+
- role metadata;
|
|
91
|
+
- runtime capability selection;
|
|
92
|
+
- skill rendering;
|
|
93
|
+
- generated guidance and prompt registry validation.
|
|
94
|
+
|
|
95
|
+
Expected dependencies:
|
|
96
|
+
|
|
97
|
+
- may depend on shared domain types and generation utilities;
|
|
98
|
+
- must keep role/capability data centralized instead of hardcoding lists across
|
|
99
|
+
commands or UI surfaces.
|
|
100
|
+
|
|
101
|
+
### Web API and Web Console
|
|
102
|
+
|
|
103
|
+
Files:
|
|
104
|
+
|
|
105
|
+
- `src/web-api*.ts`
|
|
106
|
+
- `src/web-console-client.js`
|
|
107
|
+
- `web-console/src/`
|
|
108
|
+
|
|
109
|
+
Responsibilities:
|
|
110
|
+
|
|
111
|
+
- expose local read/write APIs;
|
|
112
|
+
- render task, workflow, evidence, recovery, provider, and settings views;
|
|
113
|
+
- keep user-facing flows responsive, accessible, and evidence-oriented.
|
|
114
|
+
|
|
115
|
+
Expected dependencies:
|
|
116
|
+
|
|
117
|
+
- web API may depend on domain services;
|
|
118
|
+
- React/client code should not import Node-only modules or mutate workflow files
|
|
119
|
+
directly.
|
|
120
|
+
|
|
121
|
+
### Site and Documentation Publishing
|
|
122
|
+
|
|
123
|
+
Files:
|
|
124
|
+
|
|
125
|
+
- `site/`
|
|
126
|
+
- `scripts/generate-site-content.js`
|
|
127
|
+
- `docs/site-manifest.json`
|
|
128
|
+
- public documentation under `docs/`
|
|
129
|
+
|
|
130
|
+
Responsibilities:
|
|
131
|
+
|
|
132
|
+
- generate and publish public documentation content;
|
|
133
|
+
- render docs-driven site pages;
|
|
134
|
+
- keep public docs separate from internal workflow evidence.
|
|
135
|
+
|
|
136
|
+
Expected dependencies:
|
|
137
|
+
|
|
138
|
+
- may read approved docs manifests and public content;
|
|
139
|
+
- must not depend on local workflow state, secrets, or private evidence.
|
|
140
|
+
|
|
141
|
+
### Extensions
|
|
142
|
+
|
|
143
|
+
Files:
|
|
144
|
+
|
|
145
|
+
- `extensions/`
|
|
146
|
+
|
|
147
|
+
Responsibilities:
|
|
148
|
+
|
|
149
|
+
- editor integration;
|
|
150
|
+
- command invocation adapters;
|
|
151
|
+
- local service bridge behavior.
|
|
152
|
+
|
|
153
|
+
Expected dependencies:
|
|
154
|
+
|
|
155
|
+
- may call public CLI/API contracts;
|
|
156
|
+
- should not duplicate workflow business rules already owned by `src/`.
|
|
157
|
+
|
|
158
|
+
## Boundary Rules
|
|
159
|
+
|
|
160
|
+
- Commands stay logic-light and delegate to services.
|
|
161
|
+
- Domain services do not import from web console, site, or extension code.
|
|
162
|
+
- Generated assets and docs do not become runtime sources of truth.
|
|
163
|
+
- Capability, role, provider, command, and workflow phase lists use centralized
|
|
164
|
+
domain helpers instead of repeated hardcoded arrays.
|
|
165
|
+
- Security-sensitive code paths keep auth, secrets, file paths, shell execution,
|
|
166
|
+
network calls, and provider credentials behind explicit services and tests.
|
|
167
|
+
- Architecture changes that cross these boundaries need an Orchestra decision or
|
|
168
|
+
ADR-style note before implementation.
|
|
169
|
+
|
|
170
|
+
## Sonar Directive Adoption
|
|
171
|
+
|
|
172
|
+
When Sonar directive files are introduced, they should encode the domains above
|
|
173
|
+
as enforceable layers or dependency rules. The implementation task must include:
|
|
174
|
+
|
|
175
|
+
- the directive format supported by the connected Sonar edition;
|
|
176
|
+
- a failing/passing validation example;
|
|
177
|
+
- a Sonar run showing directives consumed by the architecture sensor;
|
|
178
|
+
- a review that maps any initial violations to GitHub issues or accepted risks.
|
|
@@ -0,0 +1,178 @@
|
|
|
1
|
+
# Sonar Quality Gates
|
|
2
|
+
|
|
3
|
+
Open Orchestra uses Sonar as a repository and SaaS project-quality signal. It
|
|
4
|
+
does not replace secret scanning or runtime policy enforcement.
|
|
5
|
+
|
|
6
|
+
## Repo Audit
|
|
7
|
+
|
|
8
|
+
The repository includes `sonar-project.properties` and a dedicated GitHub
|
|
9
|
+
Actions workflow at `.github/workflows/sonar.yml`.
|
|
10
|
+
|
|
11
|
+
Required GitHub secret:
|
|
12
|
+
|
|
13
|
+
- `SONAR_TOKEN`: token for SonarQube Cloud or SonarQube Server.
|
|
14
|
+
|
|
15
|
+
Optional GitHub secret:
|
|
16
|
+
|
|
17
|
+
- `SONAR_HOST_URL`: required only for self-hosted SonarQube Server. Leave unset
|
|
18
|
+
for SonarQube Cloud.
|
|
19
|
+
|
|
20
|
+
The workflow skips analysis when `SONAR_TOKEN` is not configured. This keeps
|
|
21
|
+
forks and offline development usable while making Sonar a CI quality gate for
|
|
22
|
+
configured environments.
|
|
23
|
+
|
|
24
|
+
The workflow supports remote quality gate enforcement when the repository
|
|
25
|
+
variable `SONAR_QUALITY_GATE_WAIT=true` is configured. In that mode the scanner
|
|
26
|
+
runs with `sonar.qualitygate.wait=true` and `sonar.qualitygate.timeout=300`. A
|
|
27
|
+
failed quality gate fails the GitHub Actions job instead of reporting only a
|
|
28
|
+
successful scanner upload.
|
|
29
|
+
|
|
30
|
+
The token used for this mode must be able to read the Sonar project and quality
|
|
31
|
+
gate status. If the scanner can upload analysis but the wait step fails with
|
|
32
|
+
`Project not found`, update the `SONAR_TOKEN` permissions or keep
|
|
33
|
+
`SONAR_QUALITY_GATE_WAIT` unset until the token can read the project.
|
|
34
|
+
|
|
35
|
+
Recommended minimum quality gate for new code:
|
|
36
|
+
|
|
37
|
+
- 0 new blocker or critical issues.
|
|
38
|
+
- 0 new vulnerabilities.
|
|
39
|
+
- Security hotspots reviewed before release.
|
|
40
|
+
- Duplicated lines on new code below 3%.
|
|
41
|
+
- Maintainability rating A on new code.
|
|
42
|
+
- Reliability rating A on new code.
|
|
43
|
+
- Coverage reported from `coverage/lcov.info` for source files on every Sonar
|
|
44
|
+
run.
|
|
45
|
+
|
|
46
|
+
## Coverage Publishing
|
|
47
|
+
|
|
48
|
+
The Sonar workflow runs `npm run test:coverage` before analysis. That command
|
|
49
|
+
builds the TypeScript sources, runs the Node test suite through `c8`, and writes
|
|
50
|
+
LCOV to `coverage/lcov.info`.
|
|
51
|
+
|
|
52
|
+
`sonar.javascript.lcov.reportPaths=coverage/lcov.info` publishes the LCOV file
|
|
53
|
+
to Sonar. The report is generated from source maps, so coverage entries map back
|
|
54
|
+
to `src/*.ts` files instead of generated `dist/*.js` files.
|
|
55
|
+
|
|
56
|
+
Coverage is intentionally split by surface:
|
|
57
|
+
|
|
58
|
+
- Core TypeScript modules: included in LCOV.
|
|
59
|
+
- CLI entry points under `bin/`: included in LCOV when exercised by tests.
|
|
60
|
+
- VS Code extension runtime files under `extensions/`: included in LCOV when
|
|
61
|
+
exercised by tests.
|
|
62
|
+
- Site and web console: excluded from LCOV until browser coverage is wired in;
|
|
63
|
+
they require Playwright screenshots, traces, videos, or E2E reports as release
|
|
64
|
+
evidence.
|
|
65
|
+
- Tests and E2E files: excluded from coverage accounting.
|
|
66
|
+
- Scripts: excluded from product coverage, but validated through CI commands
|
|
67
|
+
and targeted script tests where they enforce delivery gates.
|
|
68
|
+
|
|
69
|
+
`coverage/` is ignored locally and should not be committed.
|
|
70
|
+
|
|
71
|
+
## New Code Baseline
|
|
72
|
+
|
|
73
|
+
The project uses `main` as the new-code reference branch through
|
|
74
|
+
`sonar.newCode.referenceBranch=main`. This aligns Sonar's changed-lines and
|
|
75
|
+
new-code behavior with the repository default branch and avoids falling back to a
|
|
76
|
+
legacy `master` reference.
|
|
77
|
+
|
|
78
|
+
The Sonar workflow also creates local `master` compatibility refs that point to
|
|
79
|
+
`origin/main` inside the temporary GitHub Actions checkout. This does not create
|
|
80
|
+
or push a real `master` branch; it only gives Sonar's SCM changed-lines analysis
|
|
81
|
+
a legacy fallback ref when the remote Sonar project still asks for `master`.
|
|
82
|
+
|
|
83
|
+
## Architecture Analysis
|
|
84
|
+
|
|
85
|
+
The intended architecture model is documented in
|
|
86
|
+
[`sonar-architecture-model.md`](sonar-architecture-model.md). Sonar's scanner can
|
|
87
|
+
discover JavaScript and TypeScript dependency graphs today, but Open Orchestra
|
|
88
|
+
does not yet commit Sonar-specific architecture directive files because the
|
|
89
|
+
portable architecture source of truth is still the repository documentation,
|
|
90
|
+
rules, and Orchestra review gates.
|
|
91
|
+
|
|
92
|
+
Until Sonar directives are adopted, architecture violations are enforced through:
|
|
93
|
+
|
|
94
|
+
- repo standards in `AGENTS.md` and `rules/*.mdc`;
|
|
95
|
+
- architecture gate decisions and ADR-style records;
|
|
96
|
+
- code review against domain boundaries;
|
|
97
|
+
- tests that protect command contracts, workflow behavior, and generated
|
|
98
|
+
guidance.
|
|
99
|
+
|
|
100
|
+
When Sonar directive support is configured for this project, it should use the
|
|
101
|
+
same domains from `sonar-architecture-model.md`; the two models must not diverge.
|
|
102
|
+
|
|
103
|
+
## Dependency Analysis
|
|
104
|
+
|
|
105
|
+
## Tool Boundaries
|
|
106
|
+
|
|
107
|
+
Use the tools together instead of treating one as a replacement for another:
|
|
108
|
+
|
|
109
|
+
- Sonar: bugs, code smells, maintainability, duplication, coverage, and security
|
|
110
|
+
hotspots.
|
|
111
|
+
- Sonar dependency analysis/SCA: enabled when the connected Sonar plan supports
|
|
112
|
+
it. Dependency manifests such as `package-lock.json` must remain visible to
|
|
113
|
+
the scanner.
|
|
114
|
+
- Gitleaks: secrets in code, history, issues, prompts, lessons, evidence, logs,
|
|
115
|
+
artifacts, and model output.
|
|
116
|
+
- `npm audit`: local and CI dependency vulnerability control for this package.
|
|
117
|
+
- jscpd: local duplicate-code detection and fast copy-paste feedback.
|
|
118
|
+
- `collection-standards`: semantic duplication of domain lists, command
|
|
119
|
+
matrices, role/status lists, providers, fixtures, selectors, and validators.
|
|
120
|
+
|
|
121
|
+
If a Sonar run still reports `Dependency analysis skipped`, treat that as an
|
|
122
|
+
environment or plan-level SCA limitation, not as proof that dependency risk is
|
|
123
|
+
covered. Release evidence must then include `npm audit` and secret scanning
|
|
124
|
+
results, plus Dependabot or equivalent repository alerts when available.
|
|
125
|
+
|
|
126
|
+
When Sonar reports duplicated code that represents a repeated domain collection,
|
|
127
|
+
the remediation should load `collection-standards` and extract a typed source of
|
|
128
|
+
truth rather than only reshaping the copied block.
|
|
129
|
+
|
|
130
|
+
## SaaS Findings Architecture
|
|
131
|
+
|
|
132
|
+
Future SaaS integration should import or correlate Sonar findings as project
|
|
133
|
+
quality evidence without moving tenant source code through Open Orchestra unless
|
|
134
|
+
the tenant explicitly enables that mode.
|
|
135
|
+
|
|
136
|
+
Minimum SaaS controls:
|
|
137
|
+
|
|
138
|
+
- Bind each Sonar project to one tenant and one Open Orchestra project.
|
|
139
|
+
- Store Sonar tokens per tenant/project with least privilege and rotation
|
|
140
|
+
metadata.
|
|
141
|
+
- Keep tenant findings isolated by tenant id, project id, provider, branch, and
|
|
142
|
+
scan id.
|
|
143
|
+
- Persist finding provenance: detector, rule id, severity, component, branch,
|
|
144
|
+
commit, quality gate status, imported timestamp, actor, and review state.
|
|
145
|
+
- Convert findings into Orchestra evidence, reviews, or GitHub issues with
|
|
146
|
+
explicit owner and severity mapping.
|
|
147
|
+
- Apply retention policies per tenant and regulation profile.
|
|
148
|
+
- Never expose another tenant's findings, source paths, or scan metadata.
|
|
149
|
+
- Do not use Sonar as a prompt/log/secret scanner; route those surfaces through
|
|
150
|
+
Gitleaks/redaction/quarantine policy before they reach agents or providers.
|
|
151
|
+
- Use `.gitleaks.toml` and `npm run secret-scan` for repository scanning.
|
|
152
|
+
Runtime/SaaS secret scanning needs additional tenant-aware redaction,
|
|
153
|
+
quarantine, provenance, and retention controls.
|
|
154
|
+
|
|
155
|
+
Suggested SaaS flow:
|
|
156
|
+
|
|
157
|
+
1. Tenant connects Sonar project with scoped token.
|
|
158
|
+
2. Open Orchestra stores provider binding and quality gate expectations.
|
|
159
|
+
3. CI or webhook publishes scan metadata to the SaaS.
|
|
160
|
+
4. SaaS imports quality gate status and selected findings.
|
|
161
|
+
5. Findings are deduplicated against existing Orchestra evidence/issues.
|
|
162
|
+
6. Security, Tech Lead, QA, or Release Manager reviews findings based on
|
|
163
|
+
severity and release impact.
|
|
164
|
+
7. Approved mappings become task evidence, review blockers, or GitHub issues.
|
|
165
|
+
|
|
166
|
+
## Release Readiness
|
|
167
|
+
|
|
168
|
+
For this repository, Sonar should be treated as:
|
|
169
|
+
|
|
170
|
+
- Required when `SONAR_TOKEN` is configured in CI.
|
|
171
|
+
- Blocking at the remote quality gate level when `SONAR_QUALITY_GATE_WAIT=true`
|
|
172
|
+
and the token has read permission for the Sonar project.
|
|
173
|
+
- Advisory for local/offline development.
|
|
174
|
+
- Blocker for release when the configured quality gate fails on new code.
|
|
175
|
+
|
|
176
|
+
For SaaS tenants, whether Sonar is required or advisory is a tenant policy
|
|
177
|
+
decision. Regulated tenants may require quality gate pass evidence before
|
|
178
|
+
release approval.
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
# Task Split Assessment
|
|
2
|
+
|
|
3
|
+
Open Orchestra treats oversized work as an advisory delivery risk before
|
|
4
|
+
implementation starts. The goal is not to block small tasks; it is to make PO/BA
|
|
5
|
+
and Architect reviews explicit when one backlog item is trying to carry multiple
|
|
6
|
+
stories or too much technical coupling.
|
|
7
|
+
|
|
8
|
+
## Ownership
|
|
9
|
+
|
|
10
|
+
- Product Owner / BA review functional oversize: multiple journeys, unrelated
|
|
11
|
+
outcomes, too many acceptance criteria, hidden support/release scope, or UX
|
|
12
|
+
discovery that expands the story.
|
|
13
|
+
- Architect reviews technical complexity: too many modules, boundaries,
|
|
14
|
+
integrations, data changes, runtime changes, UI changes, infra changes, or
|
|
15
|
+
release surfaces in one task.
|
|
16
|
+
|
|
17
|
+
## Expected Output
|
|
18
|
+
|
|
19
|
+
When split risk is found, the reviewer records a recommendation with:
|
|
20
|
+
|
|
21
|
+
- rationale
|
|
22
|
+
- proposed child stories or technical slices
|
|
23
|
+
- dependency order
|
|
24
|
+
- risks
|
|
25
|
+
- owner roles
|
|
26
|
+
|
|
27
|
+
Routine small fixes stay as one task when they do not exceed the advisory
|
|
28
|
+
thresholds.
|
|
29
|
+
|
|
30
|
+
## CLI Surface
|
|
31
|
+
|
|
32
|
+
`orchestra workflow phase-plan --task <id> --json` includes
|
|
33
|
+
`splitAssessment`. The field is advisory and can be attached to a review,
|
|
34
|
+
clarification, decision, or follow-up task.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@jterrats/open-orchestra",
|
|
3
|
-
"version": "1.0.
|
|
3
|
+
"version": "1.0.6",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"workspaces": [
|
|
6
6
|
"extensions/vscode-open-orchestra",
|
|
@@ -14,12 +14,14 @@
|
|
|
14
14
|
"build": "tsc && npm run build:web",
|
|
15
15
|
"typecheck": "tsc --noEmit",
|
|
16
16
|
"test": "npm run build && node --test test/**/*.js extensions/**/*.test.cjs",
|
|
17
|
+
"test:coverage": "npm run build && c8 --reporter=lcov --reports-dir coverage --exclude \"test/**\" --exclude \"e2e/**\" --exclude \"extensions/**/test/**\" --exclude \"dist/assets/**\" --exclude \"dist/web-console/**\" node --test test/**/*.js extensions/**/*.test.cjs",
|
|
17
18
|
"test:e2e": "npm run build && npm run site:build && playwright test",
|
|
18
19
|
"test:e2e:init": "node --test e2e/init-onboarding.test.js",
|
|
19
20
|
"lint": "eslint . && prettier --check \"{bin,e2e,scripts,test,src}/**/*.js\" \"{site,web-console}/src/**/*.{css,js,jsx}\" \"{site,web-console}/*.{html,js,json}\" \"extensions/**/*.{cjs,json,md}\" \"src/**/*.ts\" \"*.{js,json}\"",
|
|
20
21
|
"format": "prettier --write \"{bin,e2e,scripts,test,src}/**/*.js\" \"{site,web-console}/src/**/*.{css,js,jsx}\" \"{site,web-console}/*.{html,js,json}\" \"extensions/**/*.{cjs,json,md}\" \"src/**/*.ts\" \"*.{js,json}\"",
|
|
21
22
|
"secret-scan": "node scripts/secret-scan.js",
|
|
22
23
|
"security:audit": "node scripts/security-audit.js",
|
|
24
|
+
"duplicates": "jscpd --config .jscpd.json",
|
|
23
25
|
"validate:workflow": "node scripts/validate-workflow.js",
|
|
24
26
|
"release:matrix": "node scripts/release-test-matrix.js",
|
|
25
27
|
"performance:bench": "npm run build && node scripts/performance-benchmark.js",
|
|
@@ -40,9 +42,11 @@
|
|
|
40
42
|
"@eslint/js": "^10.0.1",
|
|
41
43
|
"@playwright/test": "^1.59.1",
|
|
42
44
|
"@types/node": "^25.6.0",
|
|
45
|
+
"c8": "^11.0.0",
|
|
43
46
|
"chart.js": "^4.5.1",
|
|
44
47
|
"esbuild": "^0.28.0",
|
|
45
48
|
"eslint": "^10.2.1",
|
|
49
|
+
"jscpd": "^4.2.3",
|
|
46
50
|
"prettier": "^3.8.3",
|
|
47
51
|
"typescript": "^6.0.3",
|
|
48
52
|
"typescript-eslint": "^8.59.0"
|