docs(product): align roadmap and workflow docs

Author: eschaar

docs/design/agents.md

@@ -1,7 +1,7 @@
 # vstack — agents
 
 > Maintained by: **designer** role\
-> Last updated: 2026-05-03\
+> Last updated: 2026-05-13\
 > VS Code docs: [custom agents](https://code.visualstudio.com/docs/copilot/customization/custom-agents) · [agents overview](https://code.visualstudio.com/docs/copilot/agents/overview)
 
 ## what are agents?
@@ -24,6 +24,20 @@ Generation is mode-aware via `.vstack/config.yaml` `workflow.mode`:
 In `hybrid`, the UI exposes both progression paths (planner and handoff buttons).
 Use it only when your process explicitly allows both.
 
+Planner orchestration also reads `workflow.stages[*].depends_on` when deciding which
+roles are ready. The generated agents remain VS Code custom agents, but the workflow
+controller can fan out independent stages in parallel when the DAG permits it.
+
+```mermaid
+flowchart LR
+  A[workflow.mode] --> B{mode}
+  B -->|agentic| C[planner generated]
+  B -->|manual| D[planner omitted]
+  B -->|hybrid| E[planner generated + worker handoffs]
+  C --> F[planner reads depends_on]
+  F --> G[ready set / parallel branches]
+```
+
 Canonical names are the source of truth. Historical or compatibility aliases should
 remain exceptional and temporary. See `docs/architecture/adr/002-artifact-naming-and-compatibility-policy.md`.
 

docs/product/requirements.md

@@ -94,7 +94,7 @@ ______________________________________________________________________
 
 - 6 delivery agent roles: `product`, `architect`, `designer`, `engineer`,
   `tester`, `release`, plus a `planner` coordinator agent.
-- 27 backend-oriented skills with canonical names enforced at source-verify time.
+- 42 skills across the role set with canonical names enforced at source-verify time.
 
 ### FR-11 — workflow mode semantics
 
@@ -104,13 +104,20 @@ ______________________________________________________________________
 - In `manual`, planner is not generated and worker handoff buttons are shown.
 - In `hybrid`, planner is generated and worker handoff buttons are shown.
 
+### FR-12 — workflow DAG semantics
+
+- `workflow.stages[*].depends_on` is optional and declares explicit stage prerequisites.
+- When `depends_on` is omitted, the stage falls back to sequential dependency on the previous stage.
+- Invalid dependency references, self-dependencies, duplicate stage roles, and cycles are rejected.
+- In `agentic`, the planner may schedule multiple ready stages in parallel when the DAG permits it.
+
 ______________________________________________________________________
 
 ## non-functional requirements
 
 | ID    | Requirement                                                                                            |
 | ----- | ------------------------------------------------------------------------------------------------------ |
-| NFR-1 | No runtime dependencies beyond the Python standard library.                                            |
+| NFR-1 | One runtime dependency only: PyYAML (`pyyaml>=6.0`) for YAML frontmatter parsing.                      |
 | NFR-2 | Python 3.11–3.14 compatibility.                                                                        |
 | NFR-3 | Manifest writes are atomic: write to a temporary file, then replace atomically.                        |
 | NFR-4 | All public behavior exercised by automated tests (pytest). CI gate enforces test pass.                 |
@@ -129,7 +136,7 @@ ______________________________________________________________________
 1. `vstack verify --target DIR` reports zero errors on a clean install.
 1. `vstack validate` exits 0 when all source templates resolve cleanly.
 1. Locally modified tracked files are preserved on re-install by default (FR-4).
-1. All 27 canonical skill names are present after a full install.
+1. All 42 canonical skill names are present after a full install.
 1. `vstack manifest upgrade` migrates a legacy manifest without data loss.
 
 ______________________________________________________________________

docs/product/roadmap.md

@@ -1,7 +1,7 @@
 # vstack — roadmap
 
 > Maintained by: **product** role\
-> Last updated: 2026-05-12
+> Last updated: 2026-05-13
 
 ______________________________________________________________________
 
@@ -29,7 +29,7 @@ ______________________________________________________________________
 | workflow contract source-of-truth        | v3.1.0  | shipped     | `workflow:` block in `.vstack/config.yaml`; `gate`, `hitl`, `handoffs` schema; `vstack migrate` command (ADR-023, ADR-026)                              |
 | agent hooks support                      | v3.2.0  | shipped     | First-class `hook` artifact type: generate `.github/hooks/<name>.json` from templates and track in manifest                                             |
 | optional orchestrated role pipeline      | v3.2.0  | shipped     | `planner` coordinator agent implemented with mode-aware generation; default mode is `agentic` (`manual` and `hybrid` also supported)                    |
-| parallel workflow via DAG model          | v3.3.0  | shipped     | `depends_on` DAG semantics shipped with validation and backward-compatible sequential defaults                                                          |
+| parallel workflow via DAG model          | t.b.d.  | candidate   | `depends_on` DAG semantics implemented in code; awaiting a release tag before being promoted to shipped                                                 |
 | new skills (next batch)                  | t.b.d.  | candidate   | `spaces`: set up Copilot Spaces; `copilot-admin`: manage Copilot settings via `gh api`                                                                  |
 | team customization layer                 | t.b.d.  | candidate   | Deferred major update after VS Code-first model proves itself; custompacks, overlay merge rules, and install profiles all add major maintenance surface |
 | multi-IDE support (IntelliJ first)       | t.b.d.  | candidate   | Deferred until vstack proves stable in VS Code; likely a major follow-up because it needs separate targets, schemas, and more maintenance               |
@@ -289,7 +289,7 @@ Not yet implemented (deferred to orchestrated pipeline milestone):
 - Generator-level cross-role validation of input/output chains
 - Central read-only contract export for external orchestrator consumption
 
-### parallel workflow via DAG model [shipped — v3.3.0]
+### parallel workflow via DAG model [candidate — t.b.d.]
 
 **What is DAG?** (Directed Acyclic Graph)
 
@@ -350,7 +350,7 @@ product        ████
 
 Potential wall-clock reduction: 6 stages → 3 stages (~50% faster).
 
-**Shipped scope in v3.3.0:**
+**Current scope:**
 
 1. Dependency schema support in `.vstack/config.yaml` via optional `depends_on` per stage.
 1. DAG validation in CLI parsing and workflow graph checks.

docs/product/vision.md

@@ -1,7 +1,7 @@
 # vstack — vision
 
 > Maintained by: **product** role\
-> Last updated: 2026-03-28
+> Last updated: 2026-05-13
 
 ## what is vstack
 
@@ -62,9 +62,9 @@ ______________________________________________________________________
    release) define who produces what. Each role owns a specific set of
    artifacts. Agents communicate through files on disk.
 
-1. **Pipeline-ready.** Today each skill runs in a single model call. If needed later,
-   the system can move to an orchestrated multi-role pipeline by adding a runner,
-   without rewriting skills.
+1. **Pipeline-ready.** The planner/DAG orchestration model now handles multi-role
+   execution inside VS Code. If coordination needs to evolve further, it should extend
+   the existing workflow contract rather than forcing a rewrite of skills.
 
 ______________________________________________________________________
 

docs/reports/test-report.md

@@ -1,16 +1,16 @@
 # Test Report
 
-**Branch:** `feat/workflow_update`\
-**Date:** 2026-05-06\
-**Scope:** Full repository — `.vstack/` project-scope directory (ADR-019); `vstack install`/`vstack init` command semantics (ADR-020); manifest relocation from `.github/` to `.vstack/` (ADR-021); selective install with `exclude:` filter (ADR-022); `artifacts.root` config override; `.vstack/.gitignore` seeding; agent `artifacts:` section generation; ADR terminology update (Option A/B → direct execution/orchestrated pipeline); roadmap cleanup (version column, candidate rationalisation); gh-issues skill MCP-first guidance. CLI refactor, manifest backfill, and test suite structure remain in scope as prior context.
+**Branch:** `feature/workflow-dag-validation`\
+**Date:** 2026-05-13\
+**Scope:** Full repository — workflow DAG semantics (`depends_on` validation, sequential fallback compatibility, planner-ready stage scheduling); agent parallel delegation policy; planner template orchestration; roadmap/version alignment; product/docs consistency updates; runtime version fallback fix; historical validation context retained for continuity.
 
 ______________________________________________________________________
 
 ## Verdict
 
 | Dimension     | Result                                     |
 | ------------- | ------------------------------------------ |
-| Functional    | **PASS** — 428/428 tests green             |
+| Functional    | **PASS** — 635/635 tests green             |
 | Lint / Style  | **PASS** — ruff clean                      |
 | Type checking | **PASS** — mypy clean (51 files, 0 errors) |
 | Coverage      | **PASS** — 100.00% (fail-under=100)        |
@@ -27,7 +27,7 @@ ______________________________________________________________________
 platform: linux, Python 3.13.12-final-0
 runner: pytest 9.0.3 + pytest-cov 7.1.0
 command: pytest -q
-428 passed in 5.90s
+635 passed in 21.03s
 ```
 
 All tests pass. No flaky, skipped, or xfail tests observed.
@@ -36,7 +36,7 @@ ______________________________________________________________________
 
 ## Coverage Summary
 
-Total: 100.00% — 0 missed statements across 2,058 measured
+Total: 100.00% — 0 missed statements across 2,806 measured
 
 `fail-under=100` is configured in `pyproject.toml`. This gate is **passing**.
 
@@ -57,6 +57,8 @@ Blockage coverage findings were resolved by adding targeted unit tests for:
 - install/verify/uninstall error-path behavior
 - `manifest upgrade --backfill` branches: missing file, unreadable file, no VSTACK-META footer, existing checksum, unknown algorithm fallback
 
+Recent additions also covered malformed `depends_on` inputs at parse and validation time so the workflow DAG no longer degrades silently when config types are wrong.
+
 ______________________________________________________________________
 
 ## Lint and Type Checking