vstack 3.0.0__tar.gz → 3.2.0__tar.gz

{vstack-3.0.0 → vstack-3.2.0}/PKG-INFO

@@ -1,11 +1,12 @@
 Metadata-Version: 2.4
 Name: vstack
-Version: 3.0.0
+Version: 3.2.0
 Summary: VS Code-native AI engineering workflow system for microservices, libraries, and backend systems.
 License-Expression: MIT
 License-File: LICENSE
-Keywords: github-copilot,vscode,ai-workflows,developer-tools,devx,engineering-workflow,copilot-agent-mode,backend,microservices,api,workflow-automation,release-engineering
+Keywords: github-copilot,vscode,ai-workflows,developer-tools,devx,engineering-workflow,copilot-agent-mode,backend,microservices,api,workflow-automation,release-engineering,agentic-workflow,agentic-ai,ai-agent,llm,llm-agents,prompt-engineering,code-generation,scaffolding,cli,agents
 Requires-Python: >=3.11,<3.15
+Classifier: Development Status :: 4 - Beta
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.11
@@ -15,7 +16,10 @@ Classifier: Programming Language :: Python :: 3.14
 Classifier: Environment :: Console
 Classifier: Intended Audience :: Developers
 Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: Software Development :: Code Generators
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Utilities
+Requires-Dist: pyyaml (>=6.0)
 Project-URL: Changelog, https://github.com/eschaar/vstack/blob/main/CHANGELOG.md
 Project-URL: Documentation, https://github.com/eschaar/vstack/blob/main/README.md
 Project-URL: Discussions, https://github.com/eschaar/vstack/discussions
@@ -33,7 +37,7 @@ Description-Content-Type: text/markdown
 [![Python version](https://img.shields.io/badge/python-3.11--3.14-0B8A6F)](https://github.com/eschaar/vstack/blob/main/pyproject.toml)
 [![Verify status](https://img.shields.io/github/actions/workflow/status/eschaar/vstack/verify.yml?label=verify&color=1D6FA5)](https://github.com/eschaar/vstack/actions/workflows/verify.yml)
 [![Security checks](https://img.shields.io/github/actions/workflow/status/eschaar/vstack/security.yml?label=security&color=B15E00)](https://github.com/eschaar/vstack/actions/workflows/security.yml)
-[![Runtime: stdlib only](https://img.shields.io/badge/runtime-stdlib%20only-5B6C8F)](https://github.com/eschaar/vstack/blob/main/pyproject.toml)
+[![Runtime: PyYAML](https://img.shields.io/badge/runtime-PyYAML-5B6C8F)](https://github.com/eschaar/vstack/blob/main/pyproject.toml)
 [![License: MIT](https://img.shields.io/github/license/eschaar/vstack?color=5F7A1F)](https://github.com/eschaar/vstack/blob/main/LICENSE)
 [![GitHub Discussions](https://img.shields.io/badge/discussions-ask%20%26%20share-blueviolet?logo=github)](https://github.com/eschaar/vstack/discussions)
 
@@ -41,7 +45,7 @@ The VS Code-native AI workflow system for backend engineering.
 
 vstack installs structured agents, skills, instructions, and prompts into `.github/` so GitHub Copilot Agent Mode can run repeatable backend workflows with clear role boundaries.
 
-It provides a fixed role model for end-to-end software delivery: `product`, `architect`, `designer`, `engineer`, `tester`, and `release`.
+It provides six delivery roles for end-to-end software work: `product`, `architect`, `designer`, `engineer`, `tester`, and `release`, coordinated by `planner`.
 
 ## Best for
 
@@ -51,10 +55,10 @@ It provides a fixed role model for end-to-end software delivery: `product`, `arc
 
 ## What you get
 
-- Fixed role model: `product`, `architect`, `designer`, `engineer`, `tester`, `release`
+- Fixed role model: six delivery roles plus a planner coordinator
 - Template-driven install model from `src/vstack/_templates/`
 - Backend-first verification, security, and release discipline
-- Standard-library-only runtime dependencies
+- One runtime dependency: PyYAML
 
 ## Building blocks
 
@@ -80,16 +84,23 @@ VS Code command palette (`Chat: Run Prompt File`) or the Copilot Chat attach but
 | `migration-safety`  | Review DB migration safety, rollback, and zero-downtime   |
 | `release-readiness` | Evaluate release readiness from reports and open blockers |
 
-## Quick start
+## Quickstart — fresh install
 
 Install with `pipx`, then install vstack artifacts into your repository:
 
 ```bash
+# Install the CLI once, globally
 pipx install vstack
-vstack install --target /path/to/your/project
-vstack validate
+
+# Move to your repository root and run install — no --target needed
+cd /path/to/your/project
+vstack install        # seeds .vstack/config.yaml and generates .github/ in the current directory
+vstack validate       # confirm no errors
 ```
 
+When you omit `--target`, vstack uses the current working directory. The equivalent
+explicit form is `vstack install --target /path/to/your/project`.
+
 Run a first task in Copilot Agent Mode:
 
 ```text
@@ -101,6 +112,57 @@ Expected result:
 - `vstack validate` reports no unresolved template tokens
 - Agent command returns a concrete verification summary for your repository
 
+## Quick upgrade
+
+### Patch or minor version (e.g. v3.1 → v3.2, same major)
+
+Docs paths never change within a major version. Only `.github/` artifacts are updated.
+
+```bash
+pipx upgrade vstack
+
+cd /path/to/your/project
+vstack init           # idempotent — safe to run in CI
+```
+
+### Major version (e.g. v2 → v3)
+
+Docs paths may change on a major version bump. Run `vstack migrate` before `vstack init`.
+
+```bash
+pipx upgrade vstack
+
+cd /path/to/your/project
+vstack migrate        # moves docs files to their new paths (auto-detects installed version)
+vstack init           # regenerates .github/ artifacts
+
+# Only if you see "Legacy manifest schema detected" in the output above:
+vstack manifest upgrade
+vstack init
+```
+
+Preview the docs moves without touching any files:
+
+```bash
+vstack migrate --dry-run
+```
+
+For upgrades spanning multiple major versions (e.g. v1 → v3), `vstack migrate` chains
+all intermediate steps automatically. Use `--from` and `--to` to specify the range
+explicitly if auto-detection from the manifest fails:
+
+```bash
+vstack migrate --from 1 --to 3
+vstack init
+```
+
+### Force reinstall (overwrite local edits)
+
+```bash
+vstack install --force                       # overwrite all managed artifacts
+vstack install --force-name agent/engineer   # overwrite one specific artifact
+```
+
 ## Why this helps
 
 - Consistent role boundaries for planning, implementation, validation, and release
@@ -112,10 +174,17 @@ Expected result:
 ```bash
 vstack --version
 vstack validate
+
+# Run from your repository root (--target defaults to the current directory)
+vstack install
+vstack init
+vstack migrate
+vstack manifest verify
+vstack manifest status
+vstack manifest upgrade
+
+# Or specify a path explicitly
 vstack install --target /path/to/your/project
-vstack manifest verify --target /path/to/your/project
-vstack manifest status --target /path/to/your/project
-vstack manifest upgrade --target /path/to/your/project
 ```
 
 ## Common usage patterns
@@ -123,6 +192,11 @@ vstack manifest upgrade --target /path/to/your/project
 Repository-scoped install (recommended for teams):
 
 ```bash
+# Move to your repository root and install there
+cd /path/to/your/project
+vstack install
+
+# Or specify a path explicitly from any directory
 vstack install --target /path/to/your/project
 ```
 
@@ -149,15 +223,81 @@ exclude:
 If you already have agents, skills, or other files in `.github/`, run a dry-run first to see what would be preserved before committing:
 
 ```bash
-vstack install --dry-run --target /path/to/your/project
+# Run from your repository root
+vstack install --dry-run
 ```
 
 The summary lists preserved files as `type/name` selectors (e.g. `agent/engineer`). Resolve each conflict with `--force-name type/name` to overwrite, `--adopt-name type/name` to take ownership without overwriting, or `--force` to overwrite everything.
 
+## Reading `.vstack/config.yaml`
+
+- Lines starting with `#` are comments, explanation, or example configuration and are not active.
+- Only uncommented YAML keys are active configuration.
+- To enable an example block, remove `#` from that block and keep valid YAML indentation.
+- After any config change, run `vstack init` to apply it to generated `.github/` artifacts.
+
+## Workflow modes
+
+vstack supports three workflow modes via `.vstack/config.yaml`:
+
+```yaml
+workflow:
+  mode: agentic  # default
+```
+
+After changing `workflow.mode`, regenerate artifacts:
+
+```bash
+vstack init
+```
+
+| Mode      | Behavior                                                     | Planner file  | Worker handoff buttons |
+| --------- | ------------------------------------------------------------ | ------------- | ---------------------- |
+| `agentic` | Planner orchestrates stage progression using subagents       | generated     | omitted                |
+| `manual`  | User progresses stage-by-stage manually                      | not generated | shown                  |
+| `hybrid`  | Both planner orchestration and manual handoffs are available | generated     | shown                  |
+
+Execution semantics:
+
+- `workflow.stages` order is the canonical progression order.
+- `agentic` is stage-sequential by default: planner advances one stage at a time in configured order.
+- Parallelization is still possible inside a stage (independent subtasks), but cross-stage progression remains ordered.
+
+Handoff target semantics:
+
+- `handoffs.prompt` is the transition prompt text.
+- If `handoffs.agent` is omitted, the target defaults to the next role in `workflow.stages`.
+- You can set `handoffs.agent` explicitly to override that default target in `manual`/`hybrid`.
+- In `agentic`, worker handoff buttons are hidden; planner controls progression.
+
+Mode quickstart in Copilot Agent Mode:
+
+| Mode      | Start here               | First prompt example                                    |
+| --------- | ------------------------ | ------------------------------------------------------- |
+| `agentic` | `@planner`               | `@planner Run the workflow for this repository change.` |
+| `manual`  | `@product`               | `@product Define requirements for this change.`         |
+| `hybrid`  | `@planner` or `@product` | `@planner Run the workflow for this repository change.` |
+
+Usage guidance:
+
+- Use `agentic` when you want one deterministic orchestration path.
+- Use `manual` when your team prefers explicit user-controlled stage transitions.
+- Use `hybrid` only when your team intentionally wants both options.
+
+Hybrid operating rule:
+
+- Choose one path per session (planner-led or manual handoffs) and stay on it.
+- Mixing both paths in one session increases the chance of duplicate stage transitions.
+
+Hybrid warning:
+
+- In `hybrid`, users can click handoff buttons while a planner-led flow is also available.
+- This can cause unintended progression jumps or duplicated transitions if your process assumes one strict path.
+
 ## Fast troubleshooting
 
 - Command not found after install: ensure your `pipx` binary path is in `PATH`
-- Validation error: rerun `vstack install --target ...` and then `vstack validate`
+- Validation error: rerun `vstack install` from your repository root and then `vstack validate`
 - Agent results look generic: explicitly invoke a role (for example `@tester`) before a skill
 
 ## Full documentation

{vstack-3.0.0 → vstack-3.2.0}/README-pypi.md

@@ -6,7 +6,7 @@
 [![Python version](https://img.shields.io/badge/python-3.11--3.14-0B8A6F)](https://github.com/eschaar/vstack/blob/main/pyproject.toml)
 [![Verify status](https://img.shields.io/github/actions/workflow/status/eschaar/vstack/verify.yml?label=verify&color=1D6FA5)](https://github.com/eschaar/vstack/actions/workflows/verify.yml)
 [![Security checks](https://img.shields.io/github/actions/workflow/status/eschaar/vstack/security.yml?label=security&color=B15E00)](https://github.com/eschaar/vstack/actions/workflows/security.yml)
-[![Runtime: stdlib only](https://img.shields.io/badge/runtime-stdlib%20only-5B6C8F)](https://github.com/eschaar/vstack/blob/main/pyproject.toml)
+[![Runtime: PyYAML](https://img.shields.io/badge/runtime-PyYAML-5B6C8F)](https://github.com/eschaar/vstack/blob/main/pyproject.toml)
 [![License: MIT](https://img.shields.io/github/license/eschaar/vstack?color=5F7A1F)](https://github.com/eschaar/vstack/blob/main/LICENSE)
 [![GitHub Discussions](https://img.shields.io/badge/discussions-ask%20%26%20share-blueviolet?logo=github)](https://github.com/eschaar/vstack/discussions)
 
@@ -14,7 +14,7 @@ The VS Code-native AI workflow system for backend engineering.
 
 vstack installs structured agents, skills, instructions, and prompts into `.github/` so GitHub Copilot Agent Mode can run repeatable backend workflows with clear role boundaries.
 
-It provides a fixed role model for end-to-end software delivery: `product`, `architect`, `designer`, `engineer`, `tester`, and `release`.
+It provides six delivery roles for end-to-end software work: `product`, `architect`, `designer`, `engineer`, `tester`, and `release`, coordinated by `planner`.
 
 ## Best for
 
@@ -24,10 +24,10 @@ It provides a fixed role model for end-to-end software delivery: `product`, `arc
 
 ## What you get
 
-- Fixed role model: `product`, `architect`, `designer`, `engineer`, `tester`, `release`
+- Fixed role model: six delivery roles plus a planner coordinator
 - Template-driven install model from `src/vstack/_templates/`
 - Backend-first verification, security, and release discipline
-- Standard-library-only runtime dependencies
+- One runtime dependency: PyYAML
 
 ## Building blocks
 
@@ -53,16 +53,23 @@ VS Code command palette (`Chat: Run Prompt File`) or the Copilot Chat attach but
 | `migration-safety`  | Review DB migration safety, rollback, and zero-downtime   |
 | `release-readiness` | Evaluate release readiness from reports and open blockers |
 
-## Quick start
+## Quickstart — fresh install
 
 Install with `pipx`, then install vstack artifacts into your repository:
 
 ```bash
+# Install the CLI once, globally
 pipx install vstack
-vstack install --target /path/to/your/project
-vstack validate
+
+# Move to your repository root and run install — no --target needed
+cd /path/to/your/project
+vstack install        # seeds .vstack/config.yaml and generates .github/ in the current directory
+vstack validate       # confirm no errors
 ```
 
+When you omit `--target`, vstack uses the current working directory. The equivalent
+explicit form is `vstack install --target /path/to/your/project`.
+
 Run a first task in Copilot Agent Mode:
 
 ```text
@@ -74,6 +81,57 @@ Expected result:
 - `vstack validate` reports no unresolved template tokens
 - Agent command returns a concrete verification summary for your repository
 
+## Quick upgrade
+
+### Patch or minor version (e.g. v3.1 → v3.2, same major)
+
+Docs paths never change within a major version. Only `.github/` artifacts are updated.
+
+```bash
+pipx upgrade vstack
+
+cd /path/to/your/project
+vstack init           # idempotent — safe to run in CI
+```
+
+### Major version (e.g. v2 → v3)
+
+Docs paths may change on a major version bump. Run `vstack migrate` before `vstack init`.
+
+```bash
+pipx upgrade vstack
+
+cd /path/to/your/project
+vstack migrate        # moves docs files to their new paths (auto-detects installed version)
+vstack init           # regenerates .github/ artifacts
+
+# Only if you see "Legacy manifest schema detected" in the output above:
+vstack manifest upgrade
+vstack init
+```
+
+Preview the docs moves without touching any files:
+
+```bash
+vstack migrate --dry-run
+```
+
+For upgrades spanning multiple major versions (e.g. v1 → v3), `vstack migrate` chains
+all intermediate steps automatically. Use `--from` and `--to` to specify the range
+explicitly if auto-detection from the manifest fails:
+
+```bash
+vstack migrate --from 1 --to 3
+vstack init
+```
+
+### Force reinstall (overwrite local edits)
+
+```bash
+vstack install --force                       # overwrite all managed artifacts
+vstack install --force-name agent/engineer   # overwrite one specific artifact
+```
+
 ## Why this helps
 
 - Consistent role boundaries for planning, implementation, validation, and release
@@ -85,10 +143,17 @@ Expected result:
 ```bash
 vstack --version
 vstack validate
+
+# Run from your repository root (--target defaults to the current directory)
+vstack install
+vstack init
+vstack migrate
+vstack manifest verify
+vstack manifest status
+vstack manifest upgrade
+
+# Or specify a path explicitly
 vstack install --target /path/to/your/project
-vstack manifest verify --target /path/to/your/project
-vstack manifest status --target /path/to/your/project
-vstack manifest upgrade --target /path/to/your/project
 ```
 
 ## Common usage patterns
@@ -96,6 +161,11 @@ vstack manifest upgrade --target /path/to/your/project
 Repository-scoped install (recommended for teams):
 
 ```bash
+# Move to your repository root and install there
+cd /path/to/your/project
+vstack install
+
+# Or specify a path explicitly from any directory
 vstack install --target /path/to/your/project
 ```
 
@@ -122,15 +192,81 @@ exclude:
 If you already have agents, skills, or other files in `.github/`, run a dry-run first to see what would be preserved before committing:
 
 ```bash
-vstack install --dry-run --target /path/to/your/project
+# Run from your repository root
+vstack install --dry-run
 ```
 
 The summary lists preserved files as `type/name` selectors (e.g. `agent/engineer`). Resolve each conflict with `--force-name type/name` to overwrite, `--adopt-name type/name` to take ownership without overwriting, or `--force` to overwrite everything.
 
+## Reading `.vstack/config.yaml`
+
+- Lines starting with `#` are comments, explanation, or example configuration and are not active.
+- Only uncommented YAML keys are active configuration.
+- To enable an example block, remove `#` from that block and keep valid YAML indentation.
+- After any config change, run `vstack init` to apply it to generated `.github/` artifacts.
+
+## Workflow modes
+
+vstack supports three workflow modes via `.vstack/config.yaml`:
+
+```yaml
+workflow:
+  mode: agentic  # default
+```
+
+After changing `workflow.mode`, regenerate artifacts:
+
+```bash
+vstack init
+```
+
+| Mode      | Behavior                                                     | Planner file  | Worker handoff buttons |
+| --------- | ------------------------------------------------------------ | ------------- | ---------------------- |
+| `agentic` | Planner orchestrates stage progression using subagents       | generated     | omitted                |
+| `manual`  | User progresses stage-by-stage manually                      | not generated | shown                  |
+| `hybrid`  | Both planner orchestration and manual handoffs are available | generated     | shown                  |
+
+Execution semantics:
+
+- `workflow.stages` order is the canonical progression order.
+- `agentic` is stage-sequential by default: planner advances one stage at a time in configured order.
+- Parallelization is still possible inside a stage (independent subtasks), but cross-stage progression remains ordered.
+
+Handoff target semantics:
+
+- `handoffs.prompt` is the transition prompt text.
+- If `handoffs.agent` is omitted, the target defaults to the next role in `workflow.stages`.
+- You can set `handoffs.agent` explicitly to override that default target in `manual`/`hybrid`.
+- In `agentic`, worker handoff buttons are hidden; planner controls progression.
+
+Mode quickstart in Copilot Agent Mode:
+
+| Mode      | Start here               | First prompt example                                    |
+| --------- | ------------------------ | ------------------------------------------------------- |
+| `agentic` | `@planner`               | `@planner Run the workflow for this repository change.` |
+| `manual`  | `@product`               | `@product Define requirements for this change.`         |
+| `hybrid`  | `@planner` or `@product` | `@planner Run the workflow for this repository change.` |
+
+Usage guidance:
+
+- Use `agentic` when you want one deterministic orchestration path.
+- Use `manual` when your team prefers explicit user-controlled stage transitions.
+- Use `hybrid` only when your team intentionally wants both options.
+
+Hybrid operating rule:
+
+- Choose one path per session (planner-led or manual handoffs) and stay on it.
+- Mixing both paths in one session increases the chance of duplicate stage transitions.
+
+Hybrid warning:
+
+- In `hybrid`, users can click handoff buttons while a planner-led flow is also available.
+- This can cause unintended progression jumps or duplicated transitions if your process assumes one strict path.
+
 ## Fast troubleshooting
 
 - Command not found after install: ensure your `pipx` binary path is in `PATH`
-- Validation error: rerun `vstack install --target ...` and then `vstack validate`
+- Validation error: rerun `vstack install` from your repository root and then `vstack validate`
 - Agent results look generic: explicitly invoke a role (for example `@tester`) before a skill
 
 ## Full documentation

{vstack-3.0.0 → vstack-3.2.0}/pyproject.toml

@@ -5,7 +5,7 @@ description = "VS Code-native AI engineering workflow system for microservices,
 license = "MIT"
 readme = "README-pypi.md"
 requires-python = ">=3.11,<3.15"
-dependencies = []
+dependencies = ["pyyaml>=6.0"]
 keywords = [
     "github-copilot",
     "vscode",
@@ -19,8 +19,19 @@ keywords = [
     "api",
     "workflow-automation",
     "release-engineering",
+    "agentic-workflow",
+    "agentic-ai",
+    "ai-agent",
+    "llm",
+    "llm-agents",
+    "prompt-engineering",
+    "code-generation",
+    "scaffolding",
+    "cli",
+    "agents",
 ]
 classifiers = [
+    "Development Status :: 4 - Beta",
     "License :: OSI Approved :: MIT License",
     "Programming Language :: Python :: 3",
     "Programming Language :: Python :: 3.11",
@@ -30,9 +41,11 @@ classifiers = [
     "Environment :: Console",
     "Intended Audience :: Developers",
     "Topic :: Software Development :: Build Tools",
+    "Topic :: Software Development :: Code Generators",
     "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Utilities",
 ]
-version = "3.0.0"
+version = "3.2.0"
 
 [project.urls]
 Homepage = "https://github.com/eschaar/vstack"
@@ -55,20 +68,22 @@ vstack = "vstack:main"
 packages = [{include = "vstack", from = "src"}]
 include = [
     { path = "src/vstack/_templates", format = ["sdist", "wheel"] },
+    { path = "src/vstack/_migrations", format = ["sdist", "wheel"] },
 ]
 # Keep the placeholder version last because the plugin may remove/re-add it in
 # PEP 621 mode, which otherwise causes noisy key reordering.
 
 [tool.poetry.requires-plugins]
-poetry-dynamic-versioning = { version = ">=1.0.0,<2.0.0", extras = ["plugin"] }
+poetry-dynamic-versioning = { version = ">=1.10.0,<2.0.0", extras = ["plugin"] }
 
 [tool.poetry.group.dev.dependencies]
-pytest = ">=9.0"
-pytest-cov = ">=6.0"
+pytest = ">=9.0.3"
+pytest-cov = ">=7.1.0"
 ruff = ">=0.15.12"
-mypy = ">=1.20.2"
+mypy = ">=2.1.0"
 pre-commit = ">=4.6.0"
-tox = ">=4.15"
+tox = ">=4.54.0"
+types-PyYAML = ">=6.0.12.20260510"
 
 
 # ---------------------------------------------------------------------------
@@ -117,12 +132,21 @@ warn_unused_ignores = true
 warn_return_any = false
 ignore_missing_imports = true
 
+# ---------------------------------------------------------------------------
+# pylint
+# ---------------------------------------------------------------------------
+
+[tool.pylint.main]
+# Ensure src-layout imports (e.g. vstack.hooks) resolve in editor-integrated pylint runs.
+init-hook = "import sys; sys.path.insert(0, 'src')"
+py-version = "3.11"
+
 # ---------------------------------------------------------------------------
 # build system
 # ---------------------------------------------------------------------------
 
 [build-system]
-requires = ["poetry-core>=1.0.0", "poetry-dynamic-versioning>=1.0.0,<2.0.0"]
+requires = ["poetry-core>=2.4.0", "poetry-dynamic-versioning>=1.10.0,<2.0.0"]
 build-backend = "poetry_dynamic_versioning.backend"
 
 # ---------------------------------------------------------------------------
@@ -153,7 +177,7 @@ extraPaths = ["scripts"]
 [tool.tox]
 legacy_tox_ini = """
 [tox]
-min_version = 4.15
+min_version = 4.54.0
 env_list = py311, py312, py313, py314, lint, type
 skip_missing_interpreters = true
 
@@ -161,8 +185,9 @@ skip_missing_interpreters = true
 description = Run pytest for {env_name}
 package = skip
 deps =
-    pytest>=9.0
-    pytest-cov>=6.0
+    pytest>=9.0.3
+    pytest-cov>=7.1.0
+    pyyaml>=6.0.3
 setenv =
     PYTHONPATH = {tox_root}/src
 commands =
@@ -172,7 +197,7 @@ commands =
 description = Run ruff lint checks
 package = skip
 deps =
-    ruff>=0.15
+    ruff>=0.15.12
 commands =
     ruff check src tests
 
@@ -180,7 +205,8 @@ commands =
 description = Run mypy type checks
 package = skip
 deps =
-    mypy>=1.20
+    mypy>=2.1.0
+    types-PyYAML>=6.0.12.20260510
 commands =
     mypy src tests
 """

vstack-3.2.0/src/vstack/_migrations/README.md

@@ -0,0 +1,45 @@
+# vstack migration records
+
+This directory contains machine-readable migration records for `docs/` artifact path
+changes across major vstack version boundaries.
+
+Each file covers one major version transition and is named `v{M}_to_v{N}.yaml` where
+`M` is the source major version and `N` is the target major version.
+
+These files are read by `vstack migrate` to relocate agent-owned docs files when their
+paths change between major versions.
+
+## Usage
+
+```
+vstack migrate [--target <dir>] [--from <major>] [--to <major>] [--dry-run]
+```
+
+Run from the project root (or pass `--target`) after upgrading vstack to a new major
+version. The command chains all necessary migration steps between the installed major
+and the current package major.
+
+| Flag             | Description                                                     |
+| ---------------- | --------------------------------------------------------------- |
+| `--target <dir>` | Project root to migrate (default: current directory)            |
+| `--from <major>` | Source major version (default: read from `.vstack/vstack.json`) |
+| `--to <major>`   | Target major version (default: current vstack package major)    |
+| `--dry-run`      | Print moves without touching the filesystem                     |
+
+`vstack migrate` only moves files that exist at the old path; absent files are silently
+skipped. It reads `items.root` from `.vstack/config.yaml` (with `artifacts.root`
+as a legacy fallback) and adjusts destination paths when the project uses a custom
+docs root.
+
+## Schema
+
+```yaml
+from_version: "3.x"        # semver range for the source version
+to_version: "4.0"          # first minor of the target major
+moves:
+  - old: docs/path/old.md  # path relative to project root
+    new: docs/path/new.md  # path relative to project root
+    type: docs              # always "docs" for this directory
+    notes: >               # optional: human-readable explanation
+      Why this path changed and what to do with the old file after migration.
+```