speexor 0.1.0

package/docs/PRD05.md

@@ -0,0 +1,312 @@
+# PRD v5: Speexor — Gap Analysis & Hardening Pass
+
+**Product Name (official, final):** **Speexor** (Speex Orchestrator)
+**Version:** 5.0 — Gap Analysis & Correction Layer on top of v1–v4
+**Author:** Aditya (drafted with Claude)
+**Date:** June 30, 2026
+**Status:** Draft — this PRD does not add new product surface area; it **audits, corrects, and disambiguates** v1–v4 before further build-out.
+
+> This document is different in kind from v1–v4. It does not introduce new features. It performs a structured audit of the previous four PRDs — looking for contradictions, undefined behavior, naming collisions, technically incorrect assumptions, and unresolved ambiguity — and converts each finding into a concrete fix, owned requirement, or explicit decision. **All references to "Konduktor" across v1–v4 are retroactively renamed to Speexor as of this version.**
+
+---
+
+## 1. Rebrand: Konduktor → Speexor
+
+This is the first and most concrete gap: the product had no final name through four PRDs. From v5 onward, the following naming convention is canonical and supersedes every prior document:
+
+| Item                        | Old (v1–v4)                                      | New (v5, canonical)                                                              |
+| --------------------------- | ------------------------------------------------ | -------------------------------------------------------------------------------- |
+| Product name                | Konduktor                                        | **Speexor**                                                                      |
+| Tagline                     | "The Orchestration Layer for Parallel AI Agents" | **"Speexor — The Autonomous Agent Orchestrator"**                                |
+| CLI binary                  | `konduktor` (implied)                            | `speexor` (full) / `sx` (short alias)                                            |
+| Config file                 | `konduktor.config.yaml`                          | `speexor.config.yaml`                                                            |
+| Env var prefix              | unspecified                                      | `SPEEXOR_*` (e.g., `SPEEXOR_LOG_LEVEL`)                                          |
+| npm scope                   | `@konduktor/*`                                   | `@speexor/*` (e.g., `@speexor/sdk`, `@speexor/core`)                             |
+| Local data directory        | unspecified                                      | `~/.speexor/{hash}-{projectId}/` (mirrors AO's pattern, made explicit per FR-83) |
+| Glossary file               | `GLOSSARY.md`                                    | unchanged, now references Speexor terms                                          |
+| Extension manifest filename | `konduktor.extension.json`                       | `speexor.extension.json`                                                         |
+| Marketplace command         | `konduktor ext ...`                              | `speexor ext ...` (alias `sx ext ...`)                                           |
+
+- **FR-83 (new):** All local state (Task Graph Store, Checkpoint data, Decision Journal, Extension cache, Secrets Vault references) lives under `~/.speexor/`, with one subdirectory per project hash, exactly as previously implied but never formally specified in v1–v4 (this was itself a gap — see §3.6).
+- **FR-84 (new):** A one-time migration script (`speexor migrate-from-konduktor`) is provided **only if** any pre-v5 prototype code/config already exists locally (relevant since Aditya may have scaffolded early code under the old name) — renames config keys, directories, and npm package references automatically.
+
+---
+
+## 2. Methodology of This Gap Analysis
+
+Each of the four prior PRDs was reviewed against four lenses:
+
+1. **Internal contradiction** — does a later PRD silently conflict with an earlier one without acknowledging the change?
+2. **Undefined behavior** — does a requirement reference a mechanism (e.g., "checkpoint," "rollback," "skip") without specifying _exactly_ what happens, step by step?
+3. **Technical correctness** — does a stated architecture choice actually work the way the document implies (e.g., Node.js concurrency primitives, git worktree semantics, SQLite concurrency)?
+4. **Terminology/UX duplication** — do multiple PRDs introduce near-identical concepts (e.g., multiple "approval inbox" panels) under different names, creating redundant or confusing surface area?
+
+Findings are grouped below by severity: **Critical** (must fix before any further implementation), **Major** (must fix before public/Marketplace launch), and **Minor** (should fix, low risk if deferred).
+
+---
+
+## 3. Critical Findings
+
+### 3.1 Sandboxing extensions via `worker_threads` is not actually secure (Technical Error)
+
+**Where:** v4 §7.3, FR-72 — "Extensions run in a sandboxed child process (Node.js `worker_threads`/`child_process` with restricted `fs`/`net` access via a permission-enforcing wrapper)."
+**Problem:** `worker_threads` share the same process memory space and the same OS-level permissions as the main Node.js process. They do **not** provide a security boundary — a malicious extension running in a `worker_thread` can still access anything the host Node process can access unless additional isolation (Node's experimental Permission Model, a true V8 isolate sandbox like `isolated-vm`, or OS-level isolation such as a container/VM) is used. Citing `worker_threads` as a security mechanism in the same breath as `child_process` (which _can_ be meaningfully restricted via OS user/permissions) conflates a **performance** primitive with a **security** primitive.
+**Fix (FR-85, new):** Redefine extension execution model explicitly:
+
+- Extensions with `shell: none` and `network: none` declared → run in `isolated-vm` (true V8 isolate, no access to Node built-ins unless explicitly bridged) for skill-type extensions that are pure prompt/logic bundles.
+- Extensions requiring `fileSystem`/`shell`/`network` access → run as a separate OS **process** (`child_process`, not `worker_threads`) launched with the minimum OS-level privileges possible, with a permission-enforcing proxy layer intercepting `fs`/`net`/`child_process` calls via a controlled require/import shim.
+- `worker_threads` is reclassified in v5 as a **performance-only** primitive (§8 of v4, orchestrator-internal CPU-bound work), explicitly never used as a security boundary for third-party extension code.
+
+### 3.2 Two unreconciled approval/governance systems (Internal Contradiction)
+
+**Where:** v2 §5.3 (Governance Engine: `pending_approval` for proposed tasks) vs. v3 §4.4 (Risk Tier approval for high-stakes actions).
+**Problem:** v2 introduced an approval gate for _new tasks created by agents_ (task-proposal governance). v3 introduced a _separate_ approval gate for _high-stakes actions within a task's execution_ (risk-tier governance). Neither PRD states how these two systems relate: is a newly proposed task that is also classified as high-stakes subject to **one** approval or **two sequential** approvals? Is "approve a proposed task" the same UI action as "approve a high-stakes action," or are they genuinely different decisions a user must make at different times for the same piece of work?
+**Fix (FR-86, new):** Unify into a single **Approval Model** with two independent axes, both surfaced in one inbox (see §3.3 below for the related UX duplication fix):
+
+- **Axis 1 — Task Origin Gate** (from v2): applies once, when a task is first created by an agent (not the user). Governed by `governance.autoApproveProposedTasks`/`autoApproveCategories`.
+- **Axis 2 — Action Risk Gate** (from v3): applies every time _any_ task (user-given or agent-proposed) is about to execute a high-stakes action. Governed by `riskPolicy`.
+- A task can require zero, one, or both gates. Both gates' pending items render in the **same** unified inbox view (§3.3), tagged by which axis triggered them, so the user never has to reconcile two mental models.
+
+### 3.3 Three differently-named "approval inbox" UI panels (Terminology/UX Duplication)
+
+**Where:** v2 FR-39 "Pending Approval Inbox," v3 §4.4/§7.2 "Approval Inbox" + "Review Queue," v4 §10.2 "Decision Journal / Review Queue" and "Approval Inbox" listed as two separate dashboard panels.
+**Problem:** Across three PRDs, at least three distinct names are used for what is functionally 1–2 panels, with inconsistent scope (is "Review Queue" for low-confidence decisions only, or also for proposed tasks?).
+**Fix (FR-87, new):** Canonical dashboard panel names, final:
+
+- **"Approvals"** — single panel, surfaces both Axis 1 (proposed tasks) and Axis 2 (high-stakes actions) per the unified model in §3.2, each item tagged with its gate type, countdown timer (if Axis 2), and default action.
+- **"Decision Log"** — renamed from "Decision Journal"/"Review Queue," a read-only, searchable history of _all_ autonomous decisions (both auto-executed and approved/rejected ones), including the confidence score and reasoning. This panel never blocks anything — it is purely observational, distinct from the actionable "Approvals" panel.
+- All prior references to "Review Queue," "Pending Approval Inbox," and "Decision Journal" as separate UI elements are deprecated in favor of these two.
+
+### 3.4 Subagent worktree/branch model is underspecified and may not work as described (Technical Gap)
+
+**Where:** v2 §4.2 — "subagent dari agent yang sama berbagi branch parent... commit ke sub-branch yang nanti di-merge ke branch agent induk."
+**Problem:** Git worktrees require a linked working directory checked out from a specific commit/branch in the _same_ repository. The PRD never specifies: (a) at what point in time the subagent's sub-branch is forked from the parent agent's branch — if the parent agent continues committing after the subagent's worktree is created, the subagent's base goes stale, and the PRD has no defined re-sync/rebase protocol; (b) how concurrent writes to the parent's branch ref are serialized when the parent agent merges multiple subagent sub-branches sequentially; (c) what happens if a subagent's sub-branch and the parent's own concurrent work touch the same file.
+**Fix (FR-88, new):** Formal **Worktree Hierarchy Protocol**:
+
+1. A subagent's worktree is always forked from the parent agent's branch **at the exact commit hash** the parent had at spawn time (pinned, not floating to `HEAD`).
+2. The parent agent **pauses its own commits** (but not its reasoning/file-editing in its own worktree) while a merge of a subagent's sub-branch is in progress — merges are serialized, never concurrent, even if multiple subagents finish around the same time (queued merge, not parallel merge).
+3. If a merge conflict occurs, the parent agent attempts an automated resolution using the same Never-Ask Decision Ladder (v3 §4.1); if confidence is below threshold, the conflict is escalated as an Axis-2 high-stakes approval item (since an incorrect automated merge resolution is effectively irreversible once the parent agent proceeds).
+4. This protocol is implemented in the new `worktree-hierarchy` module (added to the v2 architecture table) rather than left implicit in the Workspace plugin.
+
+### 3.5 "maxDepth" is ambiguous between two different depth concepts (Internal Ambiguity)
+
+**Where:** v2 §4.2 defines **Agent hierarchy depth** (Orchestrator → Agent → Subagent → Sub-subagent); v2 §4.1/Task Node schema defines **Task Graph depth** (`depth` field on a Task Node, 0 = root). v2 `decomposition.maxDepth` config key (§7) is used without specifying which of the two it constrains.
+**Problem:** A Task Node's depth in the graph and the depth of the _agent_ assigned to execute it are related but not identical — a single agent could, in principle, be assigned to execute a task node while still being at "Agent" level (depth 1 in the agent hierarchy) even if that task node is deep in the graph (depth 4), if no further subagent spawning occurred for it. Conflating the two leads to incorrect enforcement of the safety limit the config key is supposed to provide.
+**Fix (FR-89, new):** Split into two explicit, independently configured limits:
+
+- `decomposition.maxTaskGraphDepth` — limits how deep the _Task Graph_ itself can be decomposed (Task Node depth field).
+- `decomposition.maxAgentSpawnDepth` — limits how many levels of Subagent-spawns-Subagent are permitted (Agent hierarchy depth), independent of how deep the underlying task graph is.
+- Both default to 3, but are tracked, logged, and enforced as separate counters in the Scheduler.
+
+### 3.6 No formal local data directory/storage layout was ever specified (Gap)
+
+**Where:** Implied throughout v1–v4 ("Task Graph Store," "Checkpoint data," "Decision Journal," "Secrets Vault") but never given an explicit on-disk layout.
+**Fix:** Resolved by FR-83 (§1) — `~/.speexor/{hash}-{projectId}/` as the canonical root, with documented subpaths (`task-graph.sqlite`, `checkpoints/`, `decision-log.sqlite`, `extensions/`, `vault-refs.json` — the latter holding only _references_ into the OS keychain, never actual secret values).
+
+---
+
+## 4. Major Findings
+
+### 4.1 No config schema migration strategy across v1→v4 `$schema` versions
+
+**Where:** Every PRD introduces a new `$schema` URL (`config.schema.json`, `.v2.json`, `.v3.json`, `.v4.json`) without any migration tooling.
+**Problem:** A user with a working `speexor.config.yaml` written against an earlier schema will silently break (or silently ignore new fields) when they upgrade the package — no validation error path was defined for "this config is for an older schema version."
+**Fix (FR-90, new):** `speexor config validate` command detects schema version mismatch and runs an automatic, reversible migration (writes a `.bak` file first) with a diff preview before applying. CI for the core package includes a schema-migration test for every released schema version going forward.
+
+### 4.2 Decision quality itself is never evaluated — only execution performance is benchmarked
+
+**Where:** v4 §8.3 benchmarks latency/throughput; v3's Never-Ask Engine introduces confidence scoring and the Decision Ladder, but no PRD defines how we know the _confidence scores are actually well-calibrated_ (i.e., does a 0.8-confidence decision turn out correct ~80% of the time?).
+**Problem:** Without this, "Never-Ask, Always-Decide" is a leap of faith — a miscalibrated agent could be highly confident and frequently wrong, which is worse than asking, not better.
+**Fix (FR-91, new):** Add a **Decision Quality Eval Harness** (`speexor eval decisions`): periodically samples completed Decision Log entries, surfaces them to the user (or, optionally, a stronger "judge" LLM call) for a lightweight correct/incorrect/partial label, and computes a **calibration report** (confidence bucket vs. actual-correctness rate) surfaced in the dashboard's Decision Log view. This does not block execution (preserving the never-ask guarantee) — it is a continuous feedback loop for _tuning_ `confidenceThreshold` per project over time.
+
+### 4.3 `rollback()` is defined in the `ActionPlugin` interface but never invoked by any defined flow
+
+**Where:** v3 §4.3/§6.1 — `ActionPlugin` interface includes `rollback()`, but no FR in v1–v4 specifies _when_ the orchestrator actually calls it.
+**Fix (FR-92, new):** Define explicit rollback triggers: (a) a high-stakes action's approval is later _rejected retroactively_ within a configurable grace window before an irreversible side effect actually lands (e.g., approved-but-not-yet-merged PR gets a last-second "actually no" — rollback closes/reverts it); (b) a Decision Quality Eval (§4.2) retroactively labels a low-confidence auto-executed decision as incorrect _and_ the action is still reversible — rollback is offered as a one-click dashboard action, never automatic.
+
+### 4.4 Budget/cost guard is mentioned as an NFR but has no defined enforcement mechanism
+
+**Where:** v2 §8 NFR table — "Cost Guard... agar runaway recursive decomposition tidak membengkakkan biaya API" — no FR anywhere defines what happens when a budget limit is hit.
+**Fix (FR-93, new):** `riskPolicy.budgetLimitUSD` (per task graph, optional) — when projected/actual spend crosses 80% of the limit, new agent/subagent spawning is paused (in-flight agents finish their current atomic unit of work, per the Graceful Handoff pattern from v3 §5.2) and an Axis-1-style approval item appears asking the user to raise the limit, let it stop, or convert remaining queued nodes to manual/no-LLM-cost handling.
+
+### 4.5 Extension permission defaults vs. action risk-tier defaults are two separate "default to safe" systems
+
+**Where:** v4 `permissionsMode: strict` (extension capability gating) vs. v3 `defaultRiskTierForUnknownActions: high-stakes` (action-level gating). Both exist to "default to safe when unsure," but a developer reading only one PRD would not realize there are two independent safety defaults operating at different layers (install-time capability vs. runtime action).
+**Fix (FR-94, new):** Document explicitly, in one consolidated **Security & Safety Defaults** reference table (new `SECURITY-DEFAULTS.md`), that these are intentionally two different layers — _Extension Permissions_ gate what an extension _can ever do_ (set once, at install), while _Action Risk Tiers_ gate what _any_ action (from any already-permitted extension or core agent) _does right now_ (evaluated every time). No config or behavior change required — this finding is a **documentation gap**, not a logic bug, but it was never written down anywhere in v1–v4 and would confuse contributors.
+
+### 4.6 Retry/backoff behavior for LLM provider failures (rate limits, downtime) is entirely unspecified
+
+**Where:** Multi-provider routing is described as a feature (v2 §5.1 FR-22, config example in v2 §7) but no PRD defines what happens when, e.g., OpenCode Go returns a rate-limit error mid-task.
+**Fix (FR-95, new):** Agent Backend adapters implement a standard `onProviderError(error)` contract with exponential backoff and automatic fallback to the next configured provider in `agentDefaults` (e.g., Zen → DeepSeek → GLM, matching Aditya's actual existing fallback strategy) — this failure is logged to the Decision Log as a non-blocking, low-confidence-irrelevant system event (distinct from an autonomous _reasoning_ decision).
+
+### 4.7 `maxAfkDurationHours` safety-valve behavior is vague
+
+**Where:** v3 §9 config + risk table — "sesi otomatis pause & lapor" without specifying scope of the pause.
+**Fix (FR-96, new):** Clarify precisely: at the `maxAfkDurationHours` boundary, the Scheduler **stops spawning new Agents/Subagents** (queued nodes wait) but does **not** kill already-running agents (they finish their current atomic unit of work and checkpoint normally, per Graceful Handoff). A digest notification is sent immediately (not waiting for the next scheduled daily digest). The session resumes spawning automatically once the user acknowledges the notification (a single tap/click, not a full review requirement) — preserving AFK-friendliness while still guaranteeing a human checkpoint exists.
+
+---
+
+## 5. Minor Findings
+
+| #   | Finding                                                                                                                                                                                                         | Fix                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 5.1 | No defined CLI binary alias (`speexor` vs. short form) — repeated typing burden for a CLI-heavy tool                                                                                                            | `sx` adopted as the canonical short alias alongside full `speexor` (FR per §1 table)                                                                                                                                                                                                                                                                                                                                |
+| 5.2 | v4 Marketplace index format ("simple Git-based index") never specifies a concrete schema                                                                                                                        | Define `registry-index.schema.json` (flat JSON array of manifest pointers + checksums) as part of M25, not left to implementation time                                                                                                                                                                                                                                                                              |
+| 5.3 | No defined behavior for what the dashboard shows when **zero** agents are running (empty state)                                                                                                                 | Add explicit "Empty State" requirement to Mission Control view: show a one-line call to action (submit a task) rather than a blank screen                                                                                                                                                                                                                                                                           |
+| 5.4 | "Simple Mode" (v3/v4) toggles UI complexity, but no FR defines whether Simple Mode users can still install/manage Extensions (a Power-Mode-coded concept)                                                       | Clarify: Simple Mode hides the Extension Manager's permission-matrix detail but still allows install/enable via a simplified one-line description per extension                                                                                                                                                                                                                                                     |
+| 5.5 | No explicit log level / debug verbosity convention defined despite `SPEEXOR_LOG_LEVEL` env var now existing (§1)                                                                                                | Standard levels: `error`, `warn`, `info`, `debug`, `trace` — `info` default, documented in `SETUP.md`                                                                                                                                                                                                                                                                                                               |
+| 5.6 | The relationship between Aditya's existing CEO Orchestrator skill system (261+ skills, ECC/affaan-m repo pattern) and the v4 Skill extension format was left as an open question (v4 §17 Q5) without a decision | **Resolved here:** the v5 Skill manifest format (`speexor.extension.json`, `type: "skill"`) is designed as a **superset-compatible wrapper** — an existing ECC/affaan-m-style skill folder can be referenced via a thin manifest that points to the existing folder structure unchanged, rather than requiring Aditya to rewrite 261+ skills. This becomes an explicit FR-97 for the Extension Manager build phase. |
+
+---
+
+## 6. Updated Glossary Additions (v5)
+
+The v4 glossary (§4 of v4) remains canonical; v5 adds the following terms that were used implicitly but never defined:
+
+| Term                                    | Definition                                                                                                                                                                                                                                                                                  |
+| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Approvals** (capitalized, panel name) | The single unified dashboard panel per FR-87, covering both Task Origin Gate and Action Risk Gate items                                                                                                                                                                                     |
+| **Decision Log**                        | The read-only observational history of all autonomous decisions, replacing "Decision Journal"/"Review Queue" naming                                                                                                                                                                         |
+| **Atomic Unit of Work**                 | The smallest in-progress chunk of an agent's current action (e.g., finishing one function, one file edit, one paragraph) that must complete before a Graceful Handoff (pause/redirect/interrupt) takes effect — referenced repeatedly since v3 but never formally named as a term until now |
+| **Worktree Hierarchy Protocol**         | The formal merge/sync protocol for subagent sub-branches into a parent agent's branch (FR-88)                                                                                                                                                                                               |
+| **Task Origin Gate / Action Risk Gate** | The two independent axes of the unified Approval Model (FR-86)                                                                                                                                                                                                                              |
+
+---
+
+## 7. Updated Configuration Example (`speexor.config.yaml`, v5, fully renamed and reconciled)
+
+```yaml
+$schema: https://registry.speexor.dev/schema/config.schema.v5.json
+
+language:
+  default: en
+  ui: en
+
+license: MIT
+telemetry:
+  enabled: false
+
+dataDir: "~/.speexor" # FR-83
+
+decomposition:
+  maxTaskGraphDepth: 3 # FR-89 — was ambiguous "maxDepth" in v2
+  maxAgentSpawnDepth: 3 # FR-89 — split from the above
+  maxNodesPerGraph: 50
+  plannerProvider: opencode
+  plannerModel: deepseek-reasoner
+
+scheduler:
+  maxConcurrentAgents: "auto"
+  retryOnFailure: 2
+  providerFallbackChain: ["opencode-zen", "deepseek-direct", "glm"] # FR-95
+
+worktreeHierarchy: # FR-88, new module
+  pinToCommitHash: true
+  serializeMerges: true
+  conflictEscalatesToApproval: true
+
+governance: # Axis 1 — Task Origin Gate (FR-86)
+  autoApproveProposedTasks: false
+  autoApproveCategories: ["lint-fix", "test-only"]
+  duplicateSimilarityThreshold: 0.85
+
+riskPolicy: # Axis 2 — Action Risk Gate (FR-86)
+  autoApprove: ["reversible-low", "reversible-medium"]
+  requireApproval: ["irreversible-high-stakes"]
+  approvalTimeout: 4h
+  approvalDefaultAction: "skip"
+  budgetLimitUSD: 25 # FR-93, new
+  defaultRiskTierForUnknownActions: "high-stakes"
+
+session:
+  mode: "background-daemon"
+  autoRestartOnCrash: true
+  maxAfkDurationHours: 12 # behavior clarified per FR-96
+
+extensions:
+  marketplaceIndex: "https://registry.speexor.dev/index.json"
+  enabled: ["speexor-agent-opencode", "speexor-skill-test-writer"]
+  permissionsMode: "strict" # FR-94 — distinct layer from riskPolicy above
+
+security:
+  secretsBackend: "os-keychain"
+  encryptAtRest: true
+  sandboxModel: "isolated-vm-or-process" # FR-85, replaces incorrect worker_threads claim
+
+performance:
+  maxConcurrentAgents: "auto"
+  workerThreadPoolSize: 4 # explicitly performance-only, never security (FR-85)
+
+ui:
+  defaultMode: "power"
+  panels:
+    approvals: "Approvals" # FR-87
+    decisionLog: "Decision Log" # FR-87
+  locales: ["en", "id"]
+
+logging:
+  level: "info" # FR §5.5
+```
+
+---
+
+## 8. New/Revised Requirements Summary (Consolidated)
+
+| FR    | Title                                                                                  | Severity addressed |
+| ----- | -------------------------------------------------------------------------------------- | ------------------ |
+| FR-83 | Canonical local data directory (`~/.speexor/`)                                         | Critical (3.6)     |
+| FR-84 | Migration script from any pre-rebrand prototype                                        | Critical (rebrand) |
+| FR-85 | Correct sandboxing model (`isolated-vm`/restricted process, not `worker_threads`)      | Critical (3.1)     |
+| FR-86 | Unified two-axis Approval Model                                                        | Critical (3.2)     |
+| FR-87 | Canonical dashboard panel names (Approvals, Decision Log)                              | Critical (3.3)     |
+| FR-88 | Worktree Hierarchy Protocol (pinning, serialized merges, conflict escalation)          | Critical (3.4)     |
+| FR-89 | Split `maxTaskGraphDepth` / `maxAgentSpawnDepth`                                       | Critical (3.5)     |
+| FR-90 | Config schema migration tooling                                                        | Major (4.1)        |
+| FR-91 | Decision Quality Eval Harness & calibration reporting                                  | Major (4.2)        |
+| FR-92 | Explicit rollback trigger conditions                                                   | Major (4.3)        |
+| FR-93 | Budget guard enforcement mechanism                                                     | Major (4.4)        |
+| FR-94 | Documented Security & Safety Defaults reference (no logic change)                      | Major (4.5)        |
+| FR-95 | Provider error retry/backoff/fallback contract                                         | Major (4.6)        |
+| FR-96 | Clarified `maxAfkDurationHours` pause semantics                                        | Major (4.7)        |
+| FR-97 | Skill manifest as superset-compatible wrapper over existing ECC/affaan-m skill folders | Minor (5.6)        |
+
+---
+
+## 9. Risks of _Not_ Fixing These Before Further Build
+
+| If unfixed                     | Consequence                                                                                                                                    |
+| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| 3.1 (sandboxing)               | False sense of security — a "sandboxed" extension could still read secrets/files, defeating the entire Security Model promise of v4            |
+| 3.2/3.3 (approval duplication) | Confusing UX ships at launch, eroding trust ("why are there three different approval screens?") and requiring a breaking UI rework post-launch |
+| 3.4 (worktree protocol)        | Silent data loss or corrupted merges under real parallel load — the exact opposite of the "autonomous and reliable" promise                    |
+| 3.5 (depth ambiguity)          | Safety limit (`maxDepth`) is enforced incorrectly, potentially allowing runaway agent spawning despite the config appearing to cap it          |
+| 4.2 (no decision eval)         | "Never-Ask" autonomy is unverifiable — no way to know if confidence scores are trustworthy until something goes visibly wrong in production    |
+| 4.4 (no budget enforcement)    | Real financial risk — exactly the "biaya membludak" scenario already flagged as a risk in v2/v3 but never actually mitigated with a mechanism  |
+
+---
+
+## 10. Roadmap Impact
+
+These fixes are **inserted before** the M22+ roadmap items from v4, as a new phase:
+
+| Phase                                  | Scope                                                                                                   | Estimate |
+| -------------------------------------- | ------------------------------------------------------------------------------------------------------- | -------- |
+| **M0.5 — Rebrand Pass**                | Rename all code/docs/config from Konduktor → Speexor, ship `speexor migrate-from-konduktor`             | 2-3 days |
+| **M22a — Critical Fixes**              | FR-85, FR-86, FR-87, FR-88, FR-89 implemented and tested before any Marketplace/Extension work proceeds | 2 weeks  |
+| **M22b — Major Fixes**                 | FR-90 through FR-96                                                                                     | 2 weeks  |
+| **M22c — Documentation Consolidation** | `SECURITY-DEFAULTS.md`, glossary additions (§6), `GLOSSARY.md` update                                   | 3-4 days |
+
+This adds roughly **4-5 weeks** ahead of the previously planned M22 (v4 roadmap), but is treated as non-negotiable: building the Extension Marketplace (M23+) on top of an insecure sandboxing model (3.1) or an unreconciled approval system (3.2/3.3) would require a breaking rework later, at far higher cost than fixing it now.
+
+---
+
+## 11. Remaining Open Questions (after this audit)
+
+1. Should `isolated-vm` (native dependency, can complicate cross-platform installs) be the default sandbox, or should v5 ship a process-isolation-only model first (simpler, fully JS-native) and add `isolated-vm` as an opt-in "stricter sandbox" mode later?
+2. For the Decision Quality Eval Harness (FR-91), is it acceptable to occasionally use a paid LLM call as the "judge" for calibration sampling, given the project's free/local-first goal — or should judging always default to the user's own manual labeling to avoid any implied cost?
+3. Should the Worktree Hierarchy Protocol's "serialize merges" rule (FR-88) become a throughput bottleneck for very wide graphs (many subagents finishing simultaneously) — is a smarter conflict-free merge strategy (e.g., per-file ownership assignment at decomposition time, preventing overlapping file edits in the first place) worth exploring as a v6 follow-up?
+4. Is the rebrand (`Konduktor` → `Speexor`) purely cosmetic, or does "Speex" carry an intended meaning/brand story (e.g., relation to "speech," "speed," or something domain-specific) that should be reflected in the tagline, logo direction, or even product positioning beyond a name swap?
+
+---
+
+_PRD v5 is a correction layer, not a feature layer. No implementation work on v1–v4's planned features (M0–M30) should proceed past M22a until the Critical findings in §3 are resolved — they affect the integrity of the security model, the data layer, and the core execution protocol that every later feature depends on._

package/docs/SETUP.md

@@ -0,0 +1,94 @@
+# Speexor Setup Guide
+
+## Prerequisites
+
+- **Node.js** >= 18.0.0
+- **pnpm** (recommended) or npm
+- **Git** >= 2.30 (for `git worktree` support)
+- **GitHub CLI** (`gh`) — for tracker & SCM plugins (optional for local-only mode)
+- **tmux** >= 3.0 — for tmux runtime (macOS/Linux, optional with process fallback)
+- One or more AI coding agent CLIs:
+  - [OpenCode CLI](https://github.com/superdevids/opencode)
+  - [Claude Code](https://docs.anthropic.com/en/docs/claude-code)
+  - [Aider](https://aider.chat/)
+  - [Codex CLI](https://github.com/openai/codex)
+
+## Installation
+
+```bash
+# Via npm
+npm install -g @speexjs/speexor
+
+# Or via pnpm
+pnpm add -g @speexjs/speexor
+
+# Or run from the monorepo
+cd speexjs
+pnpm install
+pnpm --filter @speexjs/speexor build
+```
+
+## Quick Start
+
+### 1. Initialize a project
+
+```bash
+cd /path/to/your/project
+speexor start https://github.com/username/repo.git
+```
+
+This will:
+- Create `speexor.config.yaml` with default configuration
+- Create `.speexor/` directory for worktrees and logs
+- Start the dashboard at `http://localhost:3000`
+
+### 2. Spawn an agent for a task
+
+```bash
+# Using a GitHub issue ID
+speexor agent spawn --task 42 --agent opencode
+
+# Using a custom task ID
+speexor agent spawn --task "feature-auth" --agent claude-code
+```
+
+### 3. Monitor progress
+
+```bash
+# Open dashboard in browser
+open http://localhost:3000
+
+# List active sessions
+speexor list
+
+# View agent logs
+speexor logs <session-id>
+```
+
+### 4. Stop a session
+
+```bash
+speexor stop <session-id>
+```
+
+## Configuration
+
+See `speexor config-help` for full schema reference, or refer to `examples/basic.yaml` in the package.
+
+## Plugin Architecture
+
+Speexor uses a 7-slot plugin architecture:
+
+| Slot | Purpose | Default Plugin |
+|------|---------|---------------|
+| **Agent** | AI coding agent adapter | OpenCode, Claude Code, Aider, Codex |
+| **Runtime** | Process execution environment | tmux (Unix), Process (Windows) |
+| **Workspace** | Code isolation strategy | Git Worktree |
+| **Tracker** | Task/issue source | GitHub Issues |
+| **SCM** | Git/PR operations | GitHub (gh CLI) |
+| **Notifier** | Alert channel | Desktop notifications |
+| **Terminal** | Live session viewer | Web (dashboard) |
+
+## Troubleshooting
+
+See [TROUBLESHOOTING.md](./TROUBLESHOOTING.md) for common issues.

package/docs/TROUBLESHOOTING.md

@@ -0,0 +1,113 @@
+# Speexor Troubleshooting Guide
+
+## Common Issues
+
+### "speexor.config.yaml not found"
+
+**Cause:** You ran `speexor list` or `speexor agent spawn` without initializing a project first.
+
+**Fix:** Run `speexor start <repo-url>` to create the config file, or manually create `speexor.config.yaml` in your project root.
+
+### "Not a git repository"
+
+**Cause:** You're running `speexor` outside a git repository.
+
+**Fix:** Navigate to a git repository or run `git init` first.
+
+### "tmux not available"
+
+**Cause:** tmux is not installed on your system.
+
+**Fix (macOS):**
+```bash
+brew install tmux
+```
+
+**Fix (Linux):**
+```bash
+sudo apt install tmux  # Debian/Ubuntu
+sudo dnf install tmux  # Fedora
+```
+
+**Fix (Windows):** Speexor will automatically fall back to the Process runtime on Windows.
+
+### "GitHub CLI (gh) not found"
+
+**Cause:** The `gh` CLI is not installed but required for GitHub tracker/SCM plugins.
+
+**Fix:**
+```bash
+# macOS
+brew install gh
+
+# Linux (Debian/Ubuntu)
+sudo apt install gh
+
+# Windows (winget)
+winget install GitHub.cli
+
+# Or manual: https://cli.github.com/
+```
+
+### Agent spawn fails
+
+**Cause:** The specified agent CLI is not installed or not in PATH.
+
+**Fix:** Ensure the agent CLI is installed and accessible:
+```bash
+# Verify
+opencode --version
+claude --version
+aider --version
+codex --version
+```
+
+### "Worktree already exists"
+
+**Cause:** A worktree for the same branch already exists, possibly from a previous interrupted session.
+
+**Fix:**
+```bash
+# List worktrees
+git worktree list
+
+# Remove stale worktree
+speexor stop <session-id>
+# Or manually:
+git worktree remove --force .speexor/worktrees/<task-id>
+```
+
+### Dashboard not showing
+
+**Cause:** Port 3000 might be in use, or the dashboard was not started.
+
+**Fix:**
+```bash
+# Specify a different port
+speexor start --port 4000
+
+# Or start dashboard only (if already initialized)
+speexor start
+```
+
+## Windows-Specific Issues
+
+### ConPTY Fallback
+
+On Windows, tmux is not available. Speexor automatically uses the Process runtime instead. This works for most cases but lacks live terminal streaming.
+
+### Shell Path
+
+If you use PowerShell, the default shell path detection should work. To customize:
+
+```yaml
+# In speexor.config.yaml
+plugins:
+  runtime: process
+```
+
+## Getting Help
+
+- Open an issue: https://github.com/superdevids/speexjs/issues
+- Check the PRD: [PRD01.md](./PRD01.md)
+- Ask in the SpeexJS community

package/examples/basic.yaml

@@ -0,0 +1,61 @@
+# Speexor Configuration — Basic Example
+# Agent Orchestrator for multi-AI coding agent orchestration
+#
+# Usage:
+#   1. Save this file as speexor.config.yaml in your project root
+#   2. Run `speexor start` to initialize and open the dashboard
+#   3. Run `speexor agent spawn --task <issue-id>` to spawn an agent
+
+version: "1"
+
+projects:
+  # --- Single project, single agent ---
+  - name: brainclash
+    repository: https://github.com/superdevids/brainclash
+    provider:
+      primary: opencode
+      fallback:
+        - claude-code
+        - aider
+      concurrentLimit: 3
+
+    # Automated reactions to CI and PR events
+    reactions:
+      ci-failed:
+        auto: true
+        action: fix
+        retries: 3
+        escalateAfter: 30
+      changes-requested:
+        auto: true
+        action: fix
+        retries: 2
+        escalateAfter: 60
+      approved-and-green:
+        auto: false
+        action: notify
+        retries: 0
+        escalateAfter: 0
+
+  # --- Second project with different provider ---
+  - name: kata-netizen
+    repository: https://github.com/superdevids/kata-netizen
+    provider:
+      primary: claude-code
+      concurrentLimit: 2
+    reactions:
+      ci-failed:
+        auto: true
+        action: fix
+        retries: 3
+        escalateAfter: 30
+      changes-requested:
+        auto: true
+        action: fix
+        retries: 2
+        escalateAfter: 45
+      approved-and-green:
+        auto: false
+        action: notify
+        retries: 0
+        escalateAfter: 0