# GH-447 Child Stories: Orchestra-Aware Web Code Editor

Parent: [#447](https://github.com/jterratsdev/open-orchestra/issues/447)
Source spike: [web-code-editor-lsp-spike.md](./web-code-editor-lsp-spike.md)

## Grooming Summary

Issue #447 is already supported by an architecture spike. The MVP should use
CodeMirror 6 first because it fits the existing React/Vite web console, mobile
composition, and governed-edit workflow better than Monaco's heavier IDE-like
runtime. The LSP bridge and policy contracts must stay editor-neutral so Monaco
can be revisited later without changing workspace, policy, evidence, or
tenant-isolation boundaries.

## Delivery Order

1. Read-only viewer and task-scoped file open contract.
2. Orchestra task context sidebar.
3. Git diff preview and task-scoped file timeline.
4. TypeScript/JavaScript LSP bridge MVP.
5. Governed edit mode and policy-gated saves.
6. Editor security hardening and negative matrix.
7. SaaS tenant isolation and data residency ADR.

## Child Stories

### GH-447A - Read-Only CodeMirror File Viewer

As a web console user, I want to open workspace-local files in a read-only code
viewer so I can inspect relevant code without granting browser-side file or
write authority.

Acceptance criteria:

- Web API opens files through explicit taskId, workspaceId, relativePath, mode,
  and editorSessionId fields.
- Server rejects absolute paths, traversal, symlink escape, missing task
  association, unknown workspace, oversized files, and unsupported binary files.
- CodeMirror 6 renders syntax-highlighted read-only content with loading,
  empty, error, unsupported file, and syntax-only states.
- Browser never reads arbitrary files directly and never receives stack traces,
  host paths, environment variables, or raw process errors.
- Unit/contract tests cover file-open validation and Playwright covers desktop
  and mobile read-only viewer flow.

Risks: path escape, accidental cwd fallback, large-file performance, and
overpromising IDE behavior.

### GH-447B - Orchestra Task Context Sidebar

As a user editing under Orchestra, I want the editor to show task context,
acceptance criteria, roles, owned paths, gates, evidence gaps, and warnings so
my file inspection stays tied to delivery criteria.

Acceptance criteria:

- Sidebar shows active task, backlog item, acceptance criteria, phase/role
  context, owned paths, related files, context-pack references, selected skills,
  open gates, blocker reviews, and evidence gaps.
- Empty and no-task states make the next action clear without allowing
  unscoped edits.
- Context is loaded through stable JSON APIs and scoped by tenant/workspace/task.
- Warnings include god-file risk, generated-file source-of-truth risk, missing
  tests, security-sensitive path, stale generated guidance, and release blockers
  when available.
- Responsive and keyboard flows work on mobile, tablet, and desktop.

Risks: noisy sidebar, stale context, and scope confusion when multiple tabs use
different workspaces.

### GH-447C - Git Diff Preview and Task-Scoped File Timeline

As a reviewer, I want revision metadata, diff previews, and file timeline
events tied to the active task so edits can be reviewed, evidenced, and rolled
back safely.

Acceptance criteria:

- API returns current revision/hash, working tree status, task-scoped change
  summary, and safe diff preview for allowed workspace-relative paths.
- Timeline records file open, edit intent, diff preview, policy decision, save,
  conflict, rollback guidance, and evidence attachment events.
- Conflict detection blocks stale saves when baseRevision no longer matches.
- Diff preview redacts or blocks secrets and never exposes files outside the
  selected workspace/task scope.
- Tests cover clean/dirty files, stale revision conflict, cross-workspace
  isolation, secret diff rejection, and evidence hook creation.

Risks: expensive git operations, unsafe diff rendering, and destructive rollback
expectations.

### GH-447D - TypeScript/JavaScript LSP Bridge MVP

As a developer, I want diagnostics, hover, completion, and go-to-definition for
TypeScript/JavaScript where available so the web editor gives useful language
feedback without becoming an unmanaged IDE.

Acceptance criteria:

- LSP bridge accepts only validated workspace-relative documents with taskId,
  workspaceId, language, and editorSessionId.
- Language server processes start via array-based APIs, never shell
  interpolation, and are supervised per workspace/language/tenant boundary.
- Bridge enforces startup timeout, idle shutdown, memory/file/document limits,
  bounded concurrency, and crash/unavailable fallback to syntax-only mode.
- Diagnostics, hover text, and navigation payloads are sanitized before browser
  rendering and cannot decide write policy.
- Fake LSP integration tests cover diagnostics, timeout, crash, unavailable
  server, idle shutdown, and no cross-workspace document leakage.

Risks: process execution, untrusted diagnostics, resource leaks, and language
server setup variance.

### GH-447E - Governed Edit Mode and Policy-Gated Saves

As a user with an active task, I want to request edit mode, preview a diff, and
submit policy-gated saves so file writes are traceable, reversible, and tied to
acceptance criteria.

Acceptance criteria:

- Edit mode requires explicit taskId, workspaceId, relativePath, baseRevision,
  userIntent, and policy acknowledgements.
- Save request uses patch/proposedContentHash, not arbitrary browser authority.
- Policy gate checks task existence, backlog item, active/selected task,
  task-owned paths, locks, release-file ownership, generated-file
  source-of-truth, security-sensitive paths, revision freshness, diff preview
  acknowledgement, and secret scan result.
- Response supports allowed, blocked, and needsReview with diffSummary,
  policyFindings, evidenceId, rollbackHint, and nextActions.
- Tests cover allowed save, blocked save, needs-review save, stale revision,
  missing diff acknowledgement, generated-file warning, and evidence link.

Risks: accidental broad write authority, weak lock semantics, and bypassable
policy acknowledgements.

### GH-447F - Editor Security Hardening and Negative Test Matrix

As a security reviewer, I want explicit hardening for paths, process execution,
diagnostics, secrets, CSP, and local/SaaS boundaries before editor writes or
LSP execution are trusted.

Acceptance criteria:

- Negative tests cover traversal, absolute paths, symlink escape, secret file
  paths, generated/managed files, unsafe process arguments, local port binding,
  unsafe diagnostic/hover rendering, raw stack traces, and env var leakage.
- Secret scanning runs on proposed diffs before write and fails closed when
  scanner readiness or audit evidence fails.
- LSP startup and git operations use args arrays and allowlisted executables.
- Browser rendering sanitizes markdown, diagnostics, hover, and diff content.
- CSP, worker, and asset-loading requirements are documented before Monaco or
  remote extension assets can be enabled.

Risks: false negatives in secret detection, unsafe third-party LSP behavior,
and browser injection through diagnostics.

### GH-447G - SaaS Tenant Isolation and Data Residency ADR

As a platform architect, I want a SaaS ADR for editor/LSP isolation so local
editor behavior does not accidentally become a multi-tenant security model.

Acceptance criteria:

- ADR defines tenant/workspace/project isolation for file access, LSP process
  pools, storage prefixes, runtime sandboxes, audit logs, quotas, and data
  residency.
- SaaS mode prevents shared language-server processes across tenants and
  enforces region policy before source text or diagnostics cross boundaries.
- Audit records cover open, preview, edit intent, policy decision, save,
  conflict, rollback guidance, and evidence attachment.
- ADR defines abuse controls for large files, malicious repositories,
  dependency execution, runaway language servers, and data exfiltration through
  diagnostics.
- QA plan includes multi-tenant and multi-tab isolation tests before SaaS
  rollout.

Risks: premature SaaS implementation without sandbox maturity, region policy
gaps, and expensive per-tenant language-server isolation.

## Non-Goals

- Do not build a custom IDE from scratch.
- Do not grant browser-side arbitrary file read/write authority.
- Do not enable write mode before read-only viewer, diff preview, policy gate,
  and security hardening are in place.
- Do not share LSP processes across SaaS tenants.
- Do not expose stack traces, host paths, env vars, credentials, or raw process
  errors to users.