open-source-cloud · gustavobertoi · Jul 1, 2026 · Jul 1, 2026
diff --git a/docs/DECISIONS.md b/docs/DECISIONS.md
@@ -112,6 +112,20 @@ Project-wide constraints that gate everything:
 ## D17. Plugin system — **deferred to v2**
 **Decision:** v1 ships built-in providers compiled in-process behind Go interfaces; **no `go-plugin`/gRPC**. Reserve `/pkg/pluginsdk`. Add `hashicorp/go-plugin` (MPL-2.0; local-subprocess; TCP-loopback transport on Windows) only when third parties want out-of-tree secrets/tunnel providers. Go's native `plugin` package is rejected (Linux/macOS-only, version-brittle, panics crash the host).
 
+## D18. Active context & shell integration
+**Decision:** Introduce an **active-context** model (a "current workspace/project", kubectl-style) resolved in precedence `--project` → `DEVSTACK_PROJECT`/`DEVSTACK_WORKSPACE` env → a **persisted default** → the existing single/first-project fallback. The persisted default is a single-row `active(ctx, workspace_root, project)` table in the SQLite ledger, **keyed by Docker context** (DECISIONS D6) and written under the flock via an **append-only, forward-only** migration (spec 08). Switching (`devstack use`) is delivered as an **opt-in shell `eval` hook** — `eval "$(devstack shell-init zsh|fish|bash)"` installs a `devstack()` wrapper that `eval`s `use`'s emitted `cd`/`export`, plus completions and a prompt segment — because **a child process cannot mutate its parent shell**. Authoring TUIs (`project`, `env`) that edit *hand-written* user YAML use a goccy **AST round-trip** editor (preserve comments/order), never the generate-side `writeIfChanged`. The ASCII logo is injected via cobra `SetHelpFunc`/`SetUsageTemplate`, gated under `--json`/`--quiet`. Detail: [spec 30](specs/30-interactive-dx-and-shell.md).
+
+**Why:** The tool was context-blind and print-only; a persisted default gives cross-terminal continuity while the per-shell env override keeps multiple terminals independent. The `eval` hook is the *only* correct way to make `use` change the live shell (the "execute, don't print" requirement) — and, being opt-in, it does **not** reintroduce the mandatory direnv that D14/spec 07 deliberately dropped for `argv[0]` symlinks.
+
+**⚠️ Verified corrections:** **fang v2.0.1 has no banner/logo option** (only `WithVersion`/`WithCommit`/`WithTheme`/`WithColorSchemeFunc`/`WithErrorHandler`/`WithNotifySignal`/`WithoutCompletions`/`WithoutManpage`/`WithoutVersion` — verified in the module cache), so the logo must go through cobra's help hook, not fang. Completions are *generatable* today via fang's `completion` subcommand but **installed nowhere** — the installer only prints a PATH hint (`install.sh`), so `shell-init` + `.goreleaser.yaml` packaging must add the missing wiring. Editing user `devstack.yaml` with the struct-marshal path would reflow the file and drop comments — the AST round-trip is mandatory.
+
+## D19. Task graph — a non-container "task" kind, not a service
+**Decision:** Monorepo/Turborepo-style "run commands across packages" is a **new, orthogonal execution kind**: an optional `tasks:` block (`command`, `run: host|exec`, `deps: []`, `watch`) driven by `devstack run <task>`, executed as a topological DAG over the **existing `internal/hooks` command executor** (host/exec, timeout/retries/onFailure) with the **`ws` errgroup bounded-parallel** pattern. Tasks are **not containers, not shared services, and take no flock** — they touch no ledger/infra state, so nothing about the deterministic compose pipeline, ref-counting, or the never-recreate-a-stateful guard is involved. Turborepo default is `turbo run` **passthrough** (Turbo owns its own cache/graph); mapping `turbo.json` into `tasks:` so devstack owns scheduling is opt-in. Detail: [spec 31](specs/31-js-monorepo-templates-and-run.md).
+
+**Why:** devstack orchestrates containers + shared infra and had no task graph; modeling tasks as containers would be wrong (short-lived, host-toolchain, dependency-ordered). Reusing the hooks executor avoids a second command runner, and keeping tasks lock-free and infra-free keeps the concurrency and determinism guarantees intact. Passthrough-by-default avoids re-implementing (and fighting) Turbo's caching.
+
+**⚠️ Verified corrections:** The `internal/hooks` `Hook` shape (`run` host|exec, `command` never shell-split, `workdir`/`env`/`timeout`/`retries`/`onFailure`) already is the task shape — a `Task` is that plus `deps`/`watch`; do **not** fork a parallel executor. Hot-reload templates must bind-mount source **and** mask `node_modules` with an anonymous volume, and set polling env (`CHOKIDAR_USEPOLLING`/`WATCHPACK_POLLING`) on WSL2/9p where inotify is unreliable (the same reason `internal/xdg` refuses `/mnt`).
+
 ---
 
 ## Dependency-risk register (pin everything; wrap risky ones)

diff --git a/docs/FEATURES.md b/docs/FEATURES.md
@@ -120,3 +120,5 @@ A truth-pass over already-shipped code: fix the stale README (up/down/secrets/tr
 | 19 | Imperative resource commands (db/s3/queue/stream/aws) | ~5w | v0.x — db/s3 now (M9) · [spec 29](specs/29-resource-commands.md) |
 | 20 | Data-plane resource layer (`resources:` + Provisioners) | ~4.5w | v0.x (M9) · [spec 27](specs/27-resource-layer.md) |
 | 21 | CLI completeness & README reconciliation | 2w | v0.3.0 — ships first (M9) · [spec 26](specs/26-cli-completeness.md) |
+| 22 | Interactive DX: active context, shell integration & authoring TUIs | ~6w | proposed (M10 DX) · [spec 30](specs/30-interactive-dx-and-shell.md) · [D18](DECISIONS.md) |
+| 23 | JS/monorepo templates + task-graph runner (`devstack run`) | ~8w | proposed (M10 DX) · [spec 31](specs/31-js-monorepo-templates-and-run.md) · [D19](DECISIONS.md) |
diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md
@@ -127,6 +127,9 @@ Effort is **person-weeks at production OSS quality** (tests + docs + cross-platf
 | **Full v1 (all pillars)** | **54** | **~13–15 months** |
 | Beta DX lane (M8, 0.x — post-GA) | ~8 | +~2.5 months |
 | Local-cloud platform lane (M9, 0.x) | ~14 | +~4 months |
+| Interactive-DX lane (M10, proposed — 0.x) | ~14 | +~4 months |
+
+> **M10 — Interactive-DX lane (proposed).** An active-context model + shell integration (`use`/`context`/`shell-init` eval hook, completions, prompt segment), project + env/secrets authoring TUIs, a console context header, ASCII-logo branding, a JS/TS + monorepo template library with hot reload, and a devstack-native task-graph runner (`devstack run`). Specs: [30](specs/30-interactive-dx-and-shell.md) (interactive DX & shell) · [31](specs/31-js-monorepo-templates-and-run.md) (JS/monorepo templates + `run`). ADRs: [D18](DECISIONS.md) (active context & shell) · [D19](DECISIONS.md) (task graph). Strictly additive; stays 0.x; no change to the deterministic `generate` pipeline or lock-first concurrency.
 
 Calendar applies a 0.6–0.75 throughput factor (context-switching, Docker/WSL2/macOS debugging, dependency churn, docs, CI). Treat as planning ranges, not commitments.
 

diff --git a/docs/guide/whats-next.md b/docs/guide/whats-next.md
@@ -7,6 +7,14 @@ roadmap or still a genuine gap. It's grounded in [ROADMAP.md](../ROADMAP.md) and
 the specs under [`docs/specs/`](../specs/) — where something doesn't exist yet,
 this page says so plainly.
 
+> **Now designed (proposed M10 "Interactive-DX" lane).** The three gaps below —
+> a projects/env TUI, the monorepo task-runner, and framework templates — now have
+> written RFCs: [spec 30](../specs/30-interactive-dx-and-shell.md) (active context,
+> shell integration, project + env/secrets TUIs, console header, logo) and
+> [spec 31](../specs/31-js-monorepo-templates-and-run.md) (JS/monorepo templates +
+> hot reload + `devstack run` task graph), with ADRs
+> [D18](../DECISIONS.md)/[D19](../DECISIONS.md). Still design-stage, not shipped.
+
 ## Shipped today
 
 The core is real and in daily use: