@ngocsangairvds/vsaf 4.0.6 → 4.0.8

package/skills/vds-skill/vds-scripts/jira_viettelmoney_orchestrator/tests/test_worklog.py

@@ -0,0 +1,265 @@
+from __future__ import annotations
+
+from unittest.mock import Mock, patch
+
+from typer.testing import CliRunner
+from vds_jira_orchestrator.cli import app
+from vds_jira_orchestrator.errors import VDSClientError
+
+
+def _runner() -> CliRunner:
+    return CliRunner()
+
+
+@patch("vds_jira_orchestrator.cli.JiraAdapter")
+@patch("vds_jira_orchestrator.cli.JiraSettings")
+def test_worklog_get_requires_issue_key(
+    mock_settings: Mock, mock_adapter_cls: Mock
+) -> None:
+    """Test that worklog get requires --issue-key."""
+    runner = _runner()
+    result = runner.invoke(app, ["worklog", "get"])
+    assert result.exit_code != 0
+    assert "--issue-key required" in result.stderr
+
+
+@patch("vds_jira_orchestrator.cli.JiraAdapter")
+@patch("vds_jira_orchestrator.cli.JiraSettings")
+def test_worklog_get_success(mock_settings: Mock, mock_adapter_cls: Mock) -> None:
+    """Test successful worklog get."""
+    runner = _runner()
+    mock_adapter = Mock()
+    mock_adapter.get_worklogs.return_value = {
+        "worklogs": [{"id": "123", "timeSpent": "2h"}]
+    }
+    mock_adapter_cls.return_value = mock_adapter
+
+    result = runner.invoke(app, ["worklog", "get", "--issue-key", "NTTC-1"])
+    assert result.exit_code == 0
+    mock_adapter.get_worklogs.assert_called_once_with("NTTC-1")
+    assert "NTTC-1" in result.stdout or "worklogs" in result.stdout
+
+
+@patch("vds_jira_orchestrator.cli.JiraAdapter")
+@patch("vds_jira_orchestrator.cli.JiraSettings")
+def test_worklog_add_requires_yes(mock_settings: Mock, mock_adapter_cls: Mock) -> None:
+    """Test that worklog add requires --yes."""
+    runner = _runner()
+    result = runner.invoke(
+        app,
+        [
+            "worklog",
+            "add",
+            "--issue-key",
+            "NTTC-1",
+            "--time-spent",
+            "2h",
+            "--comment",
+            "Test",
+        ],
+    )
+    assert result.exit_code != 0
+    assert "Refusing to add worklog without --yes" in result.stderr
+
+
+@patch("vds_jira_orchestrator.cli.JiraAdapter")
+@patch("vds_jira_orchestrator.cli.JiraSettings")
+def test_worklog_add_requires_issue_key(
+    mock_settings: Mock, mock_adapter_cls: Mock
+) -> None:
+    """Test that worklog add requires --issue-key."""
+    runner = _runner()
+    result = runner.invoke(app, ["worklog", "add", "--time-spent", "2h", "--yes"])
+    assert result.exit_code != 0
+    assert "--issue-key required" in result.stderr
+
+
+@patch("vds_jira_orchestrator.cli.JiraAdapter")
+@patch("vds_jira_orchestrator.cli.JiraSettings")
+def test_worklog_add_requires_time(mock_settings: Mock, mock_adapter_cls: Mock) -> None:
+    """Test that worklog add requires --time-spent or --time-sec."""
+    runner = _runner()
+    result = runner.invoke(app, ["worklog", "add", "--issue-key", "NTTC-1", "--yes"])
+    assert result.exit_code != 0
+    assert "--time-spent or --time-sec required" in result.stderr
+
+
+@patch("vds_jira_orchestrator.cli.JiraAdapter")
+@patch("vds_jira_orchestrator.cli.JiraSettings")
+def test_worklog_add_with_time_spent(
+    mock_settings: Mock, mock_adapter_cls: Mock
+) -> None:
+    """Test successful worklog add with time-spent."""
+    runner = _runner()
+    mock_adapter = Mock()
+    mock_adapter.issue_add_worklog.return_value = {"id": "123", "timeSpent": "2h"}
+    mock_adapter_cls.return_value = mock_adapter
+
+    result = runner.invoke(
+        app,
+        [
+            "worklog",
+            "add",
+            "--issue-key",
+            "NTTC-1",
+            "--time-spent",
+            "2h",
+            "--comment",
+            "Test work",
+            "--yes",
+        ],
+    )
+    assert result.exit_code == 0
+    mock_adapter.issue_add_worklog.assert_called_once_with(
+        issue_key="NTTC-1",
+        time_spent="2h",
+        comment="Test work",
+        started=None,
+        time_sec=None,
+    )
+
+
+@patch("vds_jira_orchestrator.cli.JiraAdapter")
+@patch("vds_jira_orchestrator.cli.JiraSettings")
+def test_worklog_add_with_time_sec(mock_settings: Mock, mock_adapter_cls: Mock) -> None:
+    """Test successful worklog add with time-sec."""
+    runner = _runner()
+    mock_adapter = Mock()
+    mock_adapter.issue_add_worklog.return_value = {
+        "id": "123",
+        "timeSpentSeconds": 7200,
+    }
+    mock_adapter_cls.return_value = mock_adapter
+
+    result = runner.invoke(
+        app,
+        [
+            "worklog",
+            "add",
+            "--issue-key",
+            "NTTC-1",
+            "--time-sec",
+            "7200",
+            "--started",
+            "2025-11-12T10:00:00Z",
+            "--yes",
+        ],
+    )
+    assert result.exit_code == 0
+    mock_adapter.issue_add_worklog.assert_called_once_with(
+        issue_key="NTTC-1",
+        time_spent="",
+        comment=None,
+        started="2025-11-12T10:00:00Z",
+        time_sec=7200,
+    )
+
+
+@patch("vds_jira_orchestrator.cli.JiraAdapter")
+@patch("vds_jira_orchestrator.cli.JiraSettings")
+def test_worklog_updated_requires_since(
+    mock_settings: Mock, mock_adapter_cls: Mock
+) -> None:
+    """Test that worklog updated requires --since."""
+    runner = _runner()
+    result = runner.invoke(app, ["worklog", "updated"])
+    assert result.exit_code != 0
+    assert "--since required" in result.stderr
+
+
+@patch("vds_jira_orchestrator.cli.JiraAdapter")
+@patch("vds_jira_orchestrator.cli.JiraSettings")
+def test_worklog_updated_success(mock_settings: Mock, mock_adapter_cls: Mock) -> None:
+    """Test successful worklog updated."""
+    runner = _runner()
+    mock_adapter = Mock()
+    mock_adapter.get_updated_worklogs.return_value = {"values": [{"id": "123"}]}
+    mock_adapter_cls.return_value = mock_adapter
+
+    result = runner.invoke(
+        app, ["worklog", "updated", "--since", "2025-11-12 10:00:00"]
+    )
+    assert result.exit_code == 0
+    mock_adapter.get_updated_worklogs.assert_called_once_with(
+        "2025-11-12 10:00:00", expand=None
+    )
+
+
+@patch("vds_jira_orchestrator.cli.JiraAdapter")
+@patch("vds_jira_orchestrator.cli.JiraSettings")
+def test_worklog_updated_with_expand(
+    mock_settings: Mock, mock_adapter_cls: Mock
+) -> None:
+    """Test worklog updated with expand parameter."""
+    runner = _runner()
+    mock_adapter = Mock()
+    mock_adapter.get_updated_worklogs.return_value = {"values": []}
+    mock_adapter_cls.return_value = mock_adapter
+
+    result = runner.invoke(
+        app,
+        [
+            "worklog",
+            "updated",
+            "--since",
+            "2025-11-12 10:00:00",
+            "--expand",
+            "properties",
+        ],
+    )
+    assert result.exit_code == 0
+    mock_adapter.get_updated_worklogs.assert_called_once_with(
+        "2025-11-12 10:00:00", expand="properties"
+    )
+
+
+@patch("vds_jira_orchestrator.cli.JiraAdapter")
+@patch("vds_jira_orchestrator.cli.JiraSettings")
+def test_worklog_deleted_requires_since(
+    mock_settings: Mock, mock_adapter_cls: Mock
+) -> None:
+    """Test that worklog deleted requires --since."""
+    runner = _runner()
+    result = runner.invoke(app, ["worklog", "deleted"])
+    assert result.exit_code != 0
+    assert "--since required" in result.stderr
+
+
+@patch("vds_jira_orchestrator.cli.JiraAdapter")
+@patch("vds_jira_orchestrator.cli.JiraSettings")
+def test_worklog_deleted_success(mock_settings: Mock, mock_adapter_cls: Mock) -> None:
+    """Test successful worklog deleted."""
+    runner = _runner()
+    mock_adapter = Mock()
+    mock_adapter.get_deleted_worklogs.return_value = {"values": [{"id": "123"}]}
+    mock_adapter_cls.return_value = mock_adapter
+
+    result = runner.invoke(
+        app, ["worklog", "deleted", "--since", "2025-11-12 10:00:00"]
+    )
+    assert result.exit_code == 0
+    mock_adapter.get_deleted_worklogs.assert_called_once_with("2025-11-12 10:00:00")
+
+
+@patch("vds_jira_orchestrator.cli.JiraAdapter")
+@patch("vds_jira_orchestrator.cli.JiraSettings")
+def test_worklog_unknown_action(mock_settings: Mock, mock_adapter_cls: Mock) -> None:
+    """Test that unknown action raises error."""
+    runner = _runner()
+    result = runner.invoke(app, ["worklog", "unknown"])
+    assert result.exit_code != 0
+    assert "Unknown action" in result.stderr
+
+
+@patch("vds_jira_orchestrator.cli.JiraAdapter")
+@patch("vds_jira_orchestrator.cli.JiraSettings")
+def test_worklog_adapter_error(mock_settings: Mock, mock_adapter_cls: Mock) -> None:
+    """Test that adapter errors are handled."""
+    runner = _runner()
+    mock_adapter = Mock()
+    mock_adapter.get_worklogs.side_effect = VDSClientError("Adapter error")
+    mock_adapter_cls.return_value = mock_adapter
+
+    result = runner.invoke(app, ["worklog", "get", "--issue-key", "NTTC-1"])
+    assert result.exit_code != 0
+    assert "Error" in result.stderr

package/skills/vds-skill/vds-scripts/llms.txt

@@ -0,0 +1,159 @@
+# VDS Scripts
+
+> Routed CLI/orchestrator workspace for WHO automation, audit workflows, spec tooling, and operational runbooks.
+
+Use this index to quickly locate runtime contracts, command references, and phase archives.
+
+## Core Instructions
+
+- [AGENTS](./AGENTS.md): Tier-0 runtime contract and operator rules.
+- [CLI Commands Reference](./docs/agents/reference/cli-commands.md): Extended command catalog and operator patterns.
+- [Phase Changelog Archive](./docs/phases/CHANGELOG.md): Prior phase notes extracted from AGENTS history.
+
+## CLI and Packages
+
+- [vds_cli package](./vds_cli/): Unified router (`vds-cli`) and docs sync commands.
+- [audit_orchestrator package](./audit_orchestrator/): Core audit workflow engine.
+- [spec_orchestrator package](./spec_orchestrator/): Spec validate/alignment/consolidation tooling.
+
+## Optional
+
+- [Scripts README](./scripts/README.md): Shell helper contract and script authoring rules.
+
+
+## Docs Index
+
+- [README](./docs/agents/README.md)
+- [index](./docs/agents/explanation/index.md)
+- [runtime-verification-and-gap-reporting](./docs/agents/explanation/runtime-verification-and-gap-reporting.md)
+- [who-ecosystem-model](./docs/agents/explanation/who-ecosystem-model.md)
+- [02-using-vds-ai-memory](./docs/agents/how-to/02-using-vds-ai-memory.md)
+- [03-memory-cross-agent](./docs/agents/how-to/03-memory-cross-agent.md)
+- [04-using-progress-reports](./docs/agents/how-to/04-using-progress-reports.md)
+- [08-semantic-search](./docs/agents/how-to/08-semantic-search.md)
+- [choose-the-right-command-or-skill](./docs/agents/how-to/choose-the-right-command-or-skill.md)
+- [index](./docs/agents/how-to/index.md)
+- [run-ecosystem-daily-report](./docs/agents/how-to/run-ecosystem-daily-report.md): Generating the ecosystem daily summary.
+- [install-and-bootstrap-who-scripts-and-skills](./docs/agents/how-to/install-and-bootstrap-who-scripts-and-skills.md)
+- [phase131-all-project-preparation](./docs/agents/how-to/phase131-all-project-preparation.md)
+- [phase131-bounded-parallel-analysis](./docs/agents/how-to/phase131-bounded-parallel-analysis.md)
+- [phase131-confluence-upload-recovery](./docs/agents/how-to/phase131-confluence-upload-recovery.md)
+- [phase132-department-preparation](./docs/agents/how-to/phase132-department-preparation.md)
+- [research-spec-audit-workflow](./docs/agents/how-to/orchestrator-workflows/research-spec-audit-workflow.md): Research → Spec → Audit cross-orchestrator workflow
+- [confluence-bitbucket-sync-workflow](./docs/agents/how-to/orchestrator-workflows/confluence-bitbucket-sync-workflow.md): Confluence → Bitbucket sync workflow
+- [memory-progress-workflow](./docs/agents/how-to/orchestrator-workflows/memory-progress-workflow.md): Memory → Progress tracking workflow
+- [first-audit-run](./docs/agents/how-to/first-audit-run.md)
+- [backup-restore](./docs/agents/reference/backup-restore.md): PostgreSQL, Redis, Qdrant backup and restore procedures.
+- [migration-playbook](./docs/agents/reference/migration-playbook.md): Orchestrator migration commands and profiles.
+- [decision-tree](./docs/agents/how-to/decision-tree.md)
+- [audit-triage-playbook](./docs/agents/reference/audit-triage-playbook.md)
+- [capability-coverage-review](./docs/agents/reference/capability-coverage-review.md)
+- [cli-development-standards](./docs/agents/reference/cli-development-standards.md)
+- [cli-help-matrix](./docs/agents/reference/cli-help-matrix.md)
+- [index](./docs/agents/reference/index.md)
+- [orchestrator-architecture](./docs/agents/reference/orchestrator-architecture.md)
+- [portable-paths-and-config](./docs/agents/reference/portable-paths-and-config.md)
+- [portable-paths-validation-matrix](./docs/agents/reference/portable-paths-validation-matrix.md)
+- [progress-report-cli](./docs/agents/reference/progress-report-cli.md)
+- [search-tools](./docs/agents/reference/search-tools.md)
+- [skills-reference](./docs/agents/reference/skills-reference.md)
+- [validation-and-sync-notes](./docs/agents/reference/validation-and-sync-notes.md)
+- [vds-ai-memory-api](./docs/agents/reference/vds-ai-memory-api.md)
+- [vds-cli-reference](./docs/agents/reference/vds-cli-reference.md)
+- [agent-operational-contract](./docs/agents/reference/agent-operational-contract.md)
+- [who-capability-inventory](./docs/agents/reference/who-capability-inventory.md)
+- [who-capability-routing-matrix](./docs/agents/reference/who-capability-routing-matrix.md)
+- [index](./docs/agents/tutorials/index.md)
+- [who-skills-and-scripts-onboarding](./docs/agents/tutorials/who-skills-and-scripts-onboarding.md)
+
+## Vietnamese Docs
+- [AGENTS (Tiếng Việt)](./AGENTS.vi.md): Hợp đồng vận hành Tier-0.
+- [README (Tiếng Việt)](./docs/vi/agents/README.md): Chỉ mục tài liệu tiếng Việt.
+- [Hướng dẫn cài đặt](./docs/vi/agents/how-to/install-and-bootstrap-who-scripts-and-skills.md): Khởi tạo WHO scripts và skills (scaffold).
+- [Zero-to-Productive Developer](./docs/vi/agents/tutorials/zero-to-productive-developer.md): Hướng dẫn 7 ngày cho lập trình viên mới (scaffold).
+- [Agent Operational Contract](./docs/vi/agents/reference/agent-operational-contract.md): Hợp đồng runtime cho agent (scaffold).
+
+- [zero-to-productive-developer](./docs/agents/tutorials/zero-to-productive-developer.md): Day 0→7 human onboarding tutorial
+- [agent-operational-contract](./docs/agents/reference/agent-operational-contract.md): AI agent operational contract
+- [decision-tree](./docs/agents/how-to/decision-tree.md): Diátaxis quadrant decision guide
+
+## Phase 180 — Comprehensive Docs
+- [who-ecosystem-introduction](./docs/agents/explanation/who-ecosystem-introduction.md): Introduction
+- [quick-start](./docs/agents/tutorials/quick-start.md): Quick start tutorial
+- [system-requirements](./docs/agents/reference/system-requirements.md): System requirements
+- [configuration-reference](./docs/agents/reference/configuration-reference.md): Configuration reference
+- [features-overview](./docs/agents/explanation/features-overview.md): Features overview
+- [feature-progression-guide](./docs/agents/tutorials/feature-progression-guide.md): Day 8-14 feature progression
+- [orchestrator-comparison-matrix](./docs/agents/reference/orchestrator-comparison-matrix.md): Orchestrator comparison
+- [orchestrator-architecture](./docs/agents/reference/orchestrator-architecture.md): Orchestrator architecture
+- [system-architecture](./docs/agents/explanation/system-architecture.md): System architecture
+- [data-flow](./docs/agents/explanation/data-flow.md): Data flow diagrams
+- [whats-new](./docs/agents/explanation/whats-new.md): Recently added features
+- [development-roadmap](./docs/agents/explanation/development-roadmap.md): Development roadmap
+- [contribute-new-orchestrator](./docs/agents/how-to/contribute-new-orchestrator.md): Add a new orchestrator
+- [tips-and-tricks](./docs/agents/how-to/tips-and-tricks.md): Tips and tricks
+- [troubleshooting-guide](./docs/agents/how-to/troubleshooting-guide.md): Troubleshooting guide
+- [common-errors](./docs/agents/reference/common-errors.md): Common errors
+
+## Confluence
+- [WHO-Project Ecosystem Documentation](http://confluence.digital.vn/display/TTCN24/WHO-Project+Ecosystem+Documentation): Central human-facing documentation hub
+
+## Orchestrator Reference Docs
+
+- [orchestrator-index](docs/agents/reference/orchestrator-index.md)
+- [bitbucket-orchestrator](docs/agents/reference/bitbucket-orchestrator.md)
+- [brd-orchestrator](docs/agents/reference/brd-orchestrator.md)
+- [circular-dependency-orchestrator](docs/agents/reference/circular-dependency-orchestrator.md)
+- [confluence-orchestrator](docs/agents/reference/confluence-orchestrator.md)
+- [db-query-orchestrator](docs/agents/reference/db-query-orchestrator.md)
+- [diagrams-orchestrator](docs/agents/reference/diagrams-orchestrator.md)
+- [elastic-orchestrator](docs/agents/reference/elastic-orchestrator.md)
+- [evolution-orchestrator](docs/agents/reference/evolution-orchestrator.md)
+- [excel-orchestrator](docs/agents/reference/excel-orchestrator.md)
+- [git-orchestrator](docs/agents/reference/git-orchestrator.md)
+- [google-sheets-orchestrator](docs/agents/reference/google-sheets-orchestrator.md)
+- [grafana-orchestrator](docs/agents/reference/grafana-orchestrator.md)
+- [hexagonal-orchestrator](docs/agents/reference/hexagonal-orchestrator.md)
+- [intellij-orchestrator](docs/agents/reference/intellij-orchestrator.md)
+- [jira-orchestrator](docs/agents/reference/jira-orchestrator.md)
+- [links-orchestrator](docs/agents/reference/links-orchestrator.md)
+- [lsp-orchestrator](docs/agents/reference/lsp-orchestrator.md)
+- [markdown-orchestrator](docs/agents/reference/markdown-orchestrator.md)
+- [mcp-orchestrator](docs/agents/reference/mcp-orchestrator.md)
+- [memory-orchestrator](docs/agents/reference/memory-orchestrator.md)
+- [metabase-orchestrator](docs/agents/reference/metabase-orchestrator.md)
+- [multi-agent-orchestrator](docs/agents/reference/multi-agent-orchestrator.md)
+- [openapi-orchestrator](docs/agents/reference/openapi-orchestrator.md)
+- [pdf-orchestrator](docs/agents/reference/pdf-orchestrator.md)
+- [progress-orchestrator](docs/agents/reference/progress-orchestrator.md)
+- [public-interface-orchestrator](docs/agents/reference/public-interface-orchestrator.md)
+- [research-orchestrator](docs/agents/reference/research-orchestrator.md)
+- [schema-orchestrator](docs/agents/reference/schema-orchestrator.md)
+- [sonarqube-orchestrator](docs/agents/reference/sonarqube-orchestrator.md)
+- [spec-orchestrator](docs/agents/reference/spec-orchestrator.md)
+- [structure-orchestrator](docs/agents/reference/structure-orchestrator.md)
+- [tasks-orchestrator](docs/agents/reference/tasks-orchestrator.md)
+
+## Orchestrator Reference Docs (Tiếng Việt)
+
+- [orchestrator-index](docs/vi/agents/reference/orchestrator-index.md): Chỉ mục điều phối viên
+- [research-orchestrator](docs/vi/agents/reference/research-orchestrator.md): Điều phối viên nghiên cứu
+- [memory-orchestrator](docs/vi/agents/reference/memory-orchestrator.md): Điều phối viên bộ nhớ
+- [spec-orchestrator](docs/vi/agents/reference/spec-orchestrator.md): Điều phối viên spec
+- [tasks-orchestrator](docs/vi/agents/reference/tasks-orchestrator.md): Điều phối viên tác vụ
+- [progress-orchestrator](docs/vi/agents/reference/progress-orchestrator.md): Điều phối viên tiến độ
+- [analytics-pipeline-workflow](./docs/agents/how-to/orchestrator-workflows/analytics-pipeline-workflow.md): Elastic → Grafana → Metabase analytics pipeline
+- [code-quality-gate-workflow](./docs/agents/how-to/orchestrator-workflows/code-quality-gate-workflow.md): SonarQube → Hexagonal → Structure → Circular Dependency quality gate
+- [document-delivery-workflow](./docs/agents/how-to/orchestrator-workflows/document-delivery-workflow.md): Markdown → Diagrams → PDF → Confluence delivery pipeline
+- [cli-commands](./docs/agents/reference/cli-commands.md): Extended CLI command catalog and operator patterns.
+- [confluence-sync](./docs/agents/reference/confluence-sync.md): Sync docs to Confluence (WIP).
+- [ecosystem-daily-report](./docs/agents/reference/ecosystem-daily-report.md): Reference for `vds-cli docs ecosystem-report`.
+- [env-git-helper](./docs/agents/reference/env-git-helper.md): Reference for `vds-cli env git-helper` lifecycle.
+- [lint-cli](./docs/agents/reference/lint-cli.md): Reference for `vds-cli lint cli` compliance diagnostics.
+- [skills-commands](./docs/agents/reference/skills-commands.md): Reference for `vds-cli skills` subcommands.
+- [infrastructure-v2.15](./docs/agents/reference/infrastructure-v2.15.md): Infrastructure v2.15.x operator reference (PgBouncer, healthchecks, container cycling).
+- [ci-workflows](./docs/agents/reference/ci-workflows.md): CI/CD workflow operational contract.
+- [Phase 220 spec health audit](../../.gpt-5.4/specs/vds-ai-memory/research/phase220-spec-health-audit/): Cross-spec dependency analysis.
+- [alignment-phase179-report](docs/agents/reference/alignment-phase179-report.md): Phase 179 alignment research (doc↔code↔Confluence).
+- [confluence-sync-target](./docs/agents/reference/confluence-sync-target.md): Confluence sync target doc with live page inventory.
+- [apply-phase3-migration](./docs/agents/how-to/apply-phase3-migration.md)

package/skills/vds-skill/vds-scripts/markdown_orchestrator/README.md

@@ -0,0 +1,72 @@
+# VDS Markdown Orchestrator
+
+Modern Python-based markdown processing and validation tool for the VDS platform.
+
+## Features
+
+- **Markdown Validation**: Check formatting with mdformat
+- **Auto-formatting**: Fix markdown issues automatically
+- **Git Integration**: Work with staged or workspace files
+- **VDS Standards**: Follows VDS CLI patterns and conventions
+
+## Installation
+
+This tool is part of the VDS scripts ecosystem. Use it via uv:
+
+```bash
+cd WHO-project/vds-scripts
+./scripts/worktree_uv.sh run --project vds_cli vds-cli markdown --help
+```
+
+## Usage
+
+### Check Markdown Formatting
+```bash
+# Check all modified markdown files
+./scripts/worktree_uv.sh run --project vds_cli vds-cli markdown check
+
+# Check specific files
+./scripts/worktree_uv.sh run --project vds_cli vds-cli markdown check README.md docs/*.md
+
+# Check only staged files
+./scripts/worktree_uv.sh run --project vds_cli vds-cli markdown check --staged
+```
+
+### Format Markdown Files
+```bash
+# Format all modified markdown files
+./scripts/worktree_uv.sh run --project vds_cli vds-cli markdown format
+
+# Format specific files
+./scripts/worktree_uv.sh run --project vds_cli vds-cli markdown format README.md docs/*.md
+
+# Format only staged files
+./scripts/worktree_uv.sh run --project vds_cli vds-cli markdown format --staged
+```
+
+### Custom Line Width
+```bash
+./scripts/worktree_uv.sh run --project vds_cli vds-cli markdown check --wrap 100
+./scripts/worktree_uv.sh run --project vds_cli vds-cli markdown format --wrap 100
+```
+
+## Console Scripts
+
+- `vds-cli markdown` - Main CLI tool
+- `mdformat-vds` - Alias for compatibility
+
+## Migration from Bash Script
+
+This tool replaces `WHO-project/insurance-document/scripts/lint-markdown.sh` (formerly `docs-nttc/scripts/lint-markdown.sh`) with:
+
+- ✅ Same functionality (check/format modes)
+- ✅ Git-aware file discovery
+- ✅ Better error handling and output
+- ✅ VDS-standardized CLI patterns
+- ✅ Modern Python implementation
+
+## Requirements
+
+- Python 3.13+
+- mdformat (install with `uv tool install mdformat`)
+- Git repository context for file discovery

package/skills/vds-skill/vds-scripts/markdown_orchestrator/pyproject.toml

@@ -0,0 +1,39 @@
+[project]
+name = "vds-markdown-orchestrator"
+version = "0.1.0"
+description = "VDS Markdown processing and validation orchestrator"
+readme = "README.md"
+requires-python = ">=3.13"
+dependencies = [
+    "vds-cli-common",
+    "typer>=0.24.1",
+    "pydantic>=2.12.5",
+    "pydantic-settings>=2.12.0",
+    "rich>=14.3.3",
+    "structlog>=25.5.0",
+    "markdown>=3.10",
+    "mdformat>=0.7.17",
+    "click>=8.3.1",
+]
+
+[project.scripts]
+vds-markdown = "vds_markdown_orchestrator.cli:app"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/vds_markdown_orchestrator"]
+
+[tool.uv]
+package = true
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.2",
+    "ruff>=0.14.11",
+]
+
+[tool.uv.sources]
+vds-cli-common = { workspace = true }

package/skills/vds-skill/vds-scripts/markdown_orchestrator/src/vds_markdown_orchestrator/__init__.py

@@ -0,0 +1,5 @@
+"""VDS Markdown orchestrator package."""
+
+__all__ = ["__version__"]
+
+__version__ = "0.1.0"

package/skills/vds-skill/vds-scripts/markdown_orchestrator/src/vds_markdown_orchestrator/cli.py

@@ -0,0 +1,102 @@
+"""CLI for markdown validation and formatting."""
+
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+
+import mdformat
+import typer
+from rich.console import Console
+
+from vds_markdown_orchestrator import __version__
+
+app = typer.Typer(name="vds-markdown", help="Markdown formatting and validation orchestrator")
+console = Console()
+
+
+def _tracked_markdown_files(*, staged: bool) -> list[Path]:
+    cmd = ["git", "diff", "--name-only"]
+    if staged:
+        cmd.append("--cached")
+    cmd.extend(["--", "*.md"])
+    try:
+        result = subprocess.run(cmd, check=False, capture_output=True, text=True)
+    except OSError:
+        return []
+    if result.returncode != 0:
+        return []
+    files = [Path(line.strip()) for line in result.stdout.splitlines() if line.strip()]
+    return [path for path in files if path.exists() and path.is_file()]
+
+
+def _resolve_files(paths: list[str], *, staged: bool) -> list[Path]:
+    if paths:
+        resolved = [Path(path) for path in paths]
+        return [path for path in resolved if path.exists() and path.is_file() and path.suffix.lower() == ".md"]
+    return _tracked_markdown_files(staged=staged)
+
+
+def _format_text(content: str, *, wrap: int) -> str:
+    return mdformat.text(content, options={"wrap": wrap})
+
+
+@app.command("check")
+def check_cmd(
+    paths: list[str] = typer.Argument(None, help="Markdown file paths"),
+    staged: bool = typer.Option(False, "--staged", help="Check staged markdown files"),
+    wrap: int = typer.Option(120, "--wrap", help="Target line wrap width"),
+) -> None:
+    """Check markdown formatting and exit non-zero if changes are needed."""
+    files = _resolve_files(paths, staged=staged)
+    if not files:
+        console.print("[yellow]No markdown files found.[/yellow]")
+        raise typer.Exit(0)
+
+    not_formatted: list[Path] = []
+    for file_path in files:
+        original = file_path.read_text(encoding="utf-8")
+        formatted = _format_text(original, wrap=wrap)
+        if formatted != original:
+            not_formatted.append(file_path)
+
+    if not_formatted:
+        for file_path in not_formatted:
+            console.print(f"[red]needs formatting[/red] {file_path}")
+        raise typer.Exit(1)
+
+    console.print(f"[green]All {len(files)} markdown files are formatted.[/green]")
+
+
+@app.command("format")
+def format_cmd(
+    paths: list[str] = typer.Argument(None, help="Markdown file paths"),
+    staged: bool = typer.Option(False, "--staged", help="Format staged markdown files"),
+    wrap: int = typer.Option(120, "--wrap", help="Target line wrap width"),
+) -> None:
+    """Format markdown files in place."""
+    files = _resolve_files(paths, staged=staged)
+    if not files:
+        console.print("[yellow]No markdown files found.[/yellow]")
+        raise typer.Exit(0)
+
+    changed = 0
+    for file_path in files:
+        original = file_path.read_text(encoding="utf-8")
+        formatted = _format_text(original, wrap=wrap)
+        if formatted != original:
+            file_path.write_text(formatted, encoding="utf-8")
+            changed += 1
+            console.print(f"[green]formatted[/green] {file_path}")
+
+    console.print(f"[green]Updated {changed} file(s).[/green]")
+
+
+@app.command("version")
+def version_cmd() -> None:
+    """Show version."""
+    console.print(__version__)
+
+
+if __name__ == "__main__":
+    app()