@ngocsangairvds/vsaf 4.1.15 → 4.1.17

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngocsangairvds/vsaf",
-  "version": "4.1.15",
+  "version": "4.1.17",
   "description": "logging step",
   "main": "packages/core/dist/index.js",
   "types": "packages/core/dist/index.d.ts",

package/skills/vds-skill/runtime/docs/agents/reference/audit-triage-playbook.md

@@ -46,7 +46,7 @@ uv run --directory ~/.claude/vds-scripts --package audit_orchestrator \
 ## Targeted Rerun Commands
 
 > **Recommended for runs expected to take more than 5 minutes**: use `./scripts/run-audit-in-tmux.sh` to prevent session timeout orphaning. The parent process must stay alive while child workflow processes run — tmux ensures this. See [cli-commands.md](./cli-commands.md#persistent-execution) for the full pattern.
-> `run-audit-in-tmux.sh` inherits the shared-env bootstrap behavior of `worktree_uv.sh`, so normal runs should load `VDS_AUDIT_STATE_DSN` and other shared runtime keys from `~/.vds/.env` automatically. Explicit `--state-dsn` is still propagated to child workflow lanes after the parent resolves it.
+> Normal runs load `VDS_AUDIT_STATE_DSN` and other shared runtime keys from `~/.vds/.env` automatically via `vds_cli_common.env`. Explicit `--state-dsn` is still propagated to child workflow lanes after the parent resolves it.
 
 Use the effective repo-cache root for your environment as defined by the portable Phase 2 cache-root model documented in `portable-paths-and-config.md`.
 

package/skills/vds-skill/runtime/docs/agents/reference/cli-commands.md

@@ -4,7 +4,7 @@
 
 Current command surface is WHO-owned and runs from `WHO-project/vds-scripts`.
 When operating from a dedicated `vds-scripts` worktree, prefer `uv run --directory ~/.claude/vds-scripts ...` so a different checkout's active `.venv` does not leak into the current worktree.
-`worktree_uv.sh` also bootstraps missing shared runtime env from `~/.vds/.env` (or `VDS_ENV_FILE`) and re-roots execution to the owning repo, so detached shells and tmux sessions do not depend on manual `source ~/.vds/.env`.
+The shared runtime env is bootstrapped from `~/.vds/.env` (or `VDS_ENV_FILE`) automatically by `vds_cli_common.env`, so detached shells and tmux sessions do not depend on manual `source ~/.vds/.env`.
 
 > **Interactive use vs. shell scripts**
 >

package/skills/vds-skill/runtime/docs/vi/agents/reference/audit-triage-playbook.md

@@ -48,7 +48,7 @@ uv run --directory ~/.claude/vds-scripts --package audit_orchestrator \
 ## Targeted Rerun Commands
 
 > **Recommended for runs expected to take more than 5 minutes**: use `./scripts/run-audit-in-tmux.sh` to prevent session timeout orphaning. The parent process must stay alive while child workflow processes run — tmux ensures this. See [cli-commands.md](./cli-commands.md#persistent-execution) for the full pattern.
-> `run-audit-in-tmux.sh` inherits the shared-env bootstrap behavior of `worktree_uv.sh`, so normal runs should load `VDS_AUDIT_STATE_DSN` and other shared runtime keys from `~/.vds/.env` automatically. Explicit `--state-dsn` is still propagated to child workflow lanes after the parent resolves it.
+> Normal runs load `VDS_AUDIT_STATE_DSN` and other shared runtime keys from `~/.vds/.env` automatically via `vds_cli_common.env`. Explicit `--state-dsn` is still propagated to child workflow lanes after the parent resolves it.
 
 Use the effective repo-cache root for your environment as defined by the portable Phase 2 cache-root model documented in `portable-paths-and-config.md`.
 

package/skills/vds-skill/runtime/docs/vi/agents/reference/cli-commands.md

@@ -6,7 +6,7 @@
 
 Current command surface is WHO-owned and runs from `WHO-project/vds-scripts`.
 When operating from a dedicated `vds-scripts` worktree, prefer `uv run --directory ~/.claude/vds-scripts ...` so a different checkout's active `.venv` does not leak into the current worktree.
-`worktree_uv.sh` also bootstraps missing shared runtime env from `~/.vds/.env` (or `VDS_ENV_FILE`) and re-roots execution to the owning repo, so detached shells and tmux sessions do not depend on manual `source ~/.vds/.env`.
+The shared runtime env is bootstrapped from `~/.vds/.env` (or `VDS_ENV_FILE`) automatically by `vds_cli_common.env`, so detached shells and tmux sessions do not depend on manual `source ~/.vds/.env`.
 
 > **Interactive use vs. shell scripts**
 >

package/skills/vds-skill/runtime/vds_cli/tests/unit/test_confluence_sync.py

@@ -165,7 +165,7 @@ def test_render_installation_guide(sample_config: ConfluenceHubConfig) -> None:
 
     assert "<h1>Ecosystem Installation Guide</h1>" in body
     assert "git clone" in body
-    assert "worktree_uv.sh sync" in body
+    assert "uv sync --directory ~/.claude/vds-scripts --all-packages" in body
 
 
 def test_render_quick_reference_vds_scripts_fallback(sample_config: ConfluenceHubConfig) -> None:

package/skills/vds-skill/runtime/vds_cli_common/tests/test_env.py

@@ -1,7 +1,6 @@
 from __future__ import annotations
 
 import os
-import subprocess
 from pathlib import Path
 
 import pytest
@@ -19,10 +18,6 @@ def _write_env(path: Path, content: str) -> None:
     path.write_text(content, encoding="utf-8")
 
 
-def _worktree_uv_script() -> Path:
-    return Path(__file__).resolve().parents[2] / "scripts" / "worktree_uv.sh"
-
-
 def test_load_shared_env_first_file_wins_when_keys_overlap(tmp_path: Path, monkeypatch) -> None:
     primary = tmp_path / "primary.env"
     fallback = tmp_path / "fallback.env"
@@ -133,103 +128,3 @@ def test_render_shared_env_exports_override_true_emits_existing_values(tmp_path:
     assert exports == "export TOKEN=from-file"
 
 
-@pytest.mark.integration
-@pytest.mark.slow
-def test_worktree_uv_bootstraps_shared_env_for_python_entrypoint(tmp_path: Path) -> None:
-    env_file = tmp_path / "shared.env"
-    _write_env(env_file, "VDS_AUDIT_STATE_DSN=postgresql://from-file/state\n")
-
-    script = _worktree_uv_script()
-    result = subprocess.run(
-        [
-            str(script),
-            "run",
-            "--project",
-            "audit_orchestrator",
-            "python",
-            "-c",
-            "import os; print(os.getenv('VDS_AUDIT_STATE_DSN') or '')",
-        ],
-        cwd=script.parent.parent,
-        env={
-            "HOME": os.environ["HOME"],
-            "PATH": os.environ["PATH"],
-            "VDS_ENV_FILE": str(env_file),
-        },
-        capture_output=True,
-        text=True,
-        check=False,
-        timeout=30,
-    )
-
-    assert result.returncode == 0, result.stderr
-    assert result.stdout.strip() == "postgresql://from-file/state"
-
-
-@pytest.mark.integration
-@pytest.mark.slow
-def test_worktree_uv_preserves_explicit_state_dsn_over_shared_env(tmp_path: Path) -> None:
-    env_file = tmp_path / "shared.env"
-    _write_env(env_file, "VDS_AUDIT_STATE_DSN=postgresql://from-file/state\n")
-
-    script = _worktree_uv_script()
-    result = subprocess.run(
-        [
-            str(script),
-            "run",
-            "--project",
-            "audit_orchestrator",
-            "python",
-            "-c",
-            "import os; print(os.getenv('VDS_AUDIT_STATE_DSN') or '')",
-        ],
-        cwd=script.parent.parent,
-        env={
-            "HOME": os.environ["HOME"],
-            "PATH": os.environ["PATH"],
-            "VDS_ENV_FILE": str(env_file),
-            "VDS_AUDIT_STATE_DSN": "postgresql://from-shell/state",
-        },
-        capture_output=True,
-        text=True,
-        check=False,
-        timeout=30,
-    )
-
-    assert result.returncode == 0, result.stderr
-    assert result.stdout.strip() == "postgresql://from-shell/state"
-
-
-@pytest.mark.integration
-@pytest.mark.slow
-def test_worktree_uv_bootstraps_shared_env_from_external_cwd(tmp_path: Path) -> None:
-    env_file = tmp_path / "shared.env"
-    _write_env(env_file, "VDS_AUDIT_STATE_DSN=postgresql://from-file/state\n")
-
-    script = _worktree_uv_script()
-    outside_cwd = tmp_path / "outside"
-    outside_cwd.mkdir()
-    result = subprocess.run(
-        [
-            str(script),
-            "run",
-            "--project",
-            "audit_orchestrator",
-            "python",
-            "-c",
-            "import os; print(os.getenv('VDS_AUDIT_STATE_DSN') or '')",
-        ],
-        cwd=outside_cwd,
-        env={
-            "HOME": os.environ["HOME"],
-            "PATH": os.environ["PATH"],
-            "VDS_ENV_FILE": str(env_file),
-        },
-        capture_output=True,
-        text=True,
-        check=False,
-        timeout=30,
-    )
-
-    assert result.returncode == 0, result.stderr
-    assert result.stdout.strip() == "postgresql://from-file/state"

package/skills/vds-skill/vds-scripts-skill/SKILL.md

@@ -112,6 +112,20 @@ uv run --directory ~/.claude/vds-scripts --package spec_orchestrator vds-spec --
 - Research-backed investigation → `research-skill`
 - Structural graph review → `code-review-graph-skill`
 
+## Mandatory Rules
+
+### Confluence Content Export
+
+When fetching or exporting Confluence page content (especially BRD, KBNV, SRS pages with tables and images), you **MUST** read and follow `references/confluence-content-export.md` before proceeding. Key rules:
+
+1. **Use `body.storage`** (not `body.view`) as source of truth for image references
+2. **Only download attachments referenced in `body.storage`** — never bulk-download all attachments
+3. **Preserve image position** in output — replace `ac:image` with `![](images/...)` in-place, never collect at end
+4. **Keep HTML tables** in markdown output — do not flatten to pipe tables
+5. **Verify image count** matches between `body.storage` and output before reporting done
+
+Failure to follow these rules causes silent data loss (wrong images downloaded, table structure destroyed, image↔text mapping broken).
+
 ## Progressive Disclosure
 
 Use these bundled references for depth:
@@ -121,6 +135,7 @@ Use these bundled references for depth:
 - `references/validation-commands.md`
 - `references/development-commands.md`
 - `references/specialist-routing.md`
+- `references/confluence-content-export.md`
 
 ## Notes
 

package/skills/vds-skill/vds-scripts-skill/references/confluence-content-export.md

@@ -0,0 +1,127 @@
+# Confluence Content Export — Mandatory Rules
+
+When extracting content from a Confluence page (BRD, KBNV, SRS, or any page with tables/images), follow these rules strictly. Violations cause data loss that is invisible to the user.
+
+## Rule 1 — Use `body.storage` as the Single Source of Truth for Image Refs
+
+- **Never** rely on `body.view` for image references — it is post-render HTML that may add or drop images via macros.
+- `body.storage` is raw XHTML containing `<ac:image><ri:attachment ri:filename="..."/></ac:image>` — this is the definitive set of inline images.
+- **Only download attachments whose filename appears in `body.storage`**. Do not bulk-download from `attachments --list`.
+
+```bash
+# Step 1: fetch storage body
+uv run --directory ~/.claude/vds-scripts --package vds-cli \
+  vds-cli confluence content page <PAGE_ID> --expand body.storage
+```
+
+```python
+# Step 2: extract referenced filenames from storage XHTML
+import re
+storage_xml: str = ...  # body.storage content
+referenced = set(re.findall(r'ri:filename="([^"]+)"', storage_xml))
+# referenced = {'screen-login.png', 'flow-diagram.png', 'table-header.png'}
+```
+
+## Rule 2 — Preserve Image-to-Text Positional Mapping
+
+When converting to markdown/local file:
+
+- Replace each `<ac:image>...<ri:attachment ri:filename="X"/>...</ac:image>` with `![X](images/X)` **at its original position** in the document. Never collect images into a list at the end.
+- If the content contains `<table>`, **keep HTML table markup** in the markdown output. Markdown viewers (GitHub, Obsidian, VS Code) all render HTML tables. Do not flatten tables with nested bullets or merged cells into pure-markdown `|` tables — this destroys row/column relationships.
+- Place the `images/` folder at the same level as `content.md`.
+
+```python
+# Step 3: convert storage XHTML → markdown with inline image refs
+import re
+
+def storage_to_markdown(storage_xml: str) -> str:
+    """Convert Confluence storage XHTML to markdown, preserving image positions and tables."""
+    result = storage_xml
+
+    # Replace ac:image with markdown image refs (in-place)
+    def replace_ac_image(match: re.Match) -> str:
+        filename = re.search(r'ri:filename="([^"]+)"', match.group(0))
+        if filename:
+            name = filename.group(1)
+            return f'![{name}](images/{name})'
+        return match.group(0)
+
+    result = re.sub(
+        r'<ac:image[^>]*>.*?</ac:image>',
+        replace_ac_image,
+        result,
+        flags=re.DOTALL,
+    )
+
+    # Keep <table>...</table> blocks as-is (HTML in markdown)
+    # Convert other XHTML elements to markdown as usual:
+    # <p> → newline, <h1> → #, <li> → -, <strong> → **, etc.
+    # ...
+
+    return result
+```
+
+## Rule 3 — Classify Downloaded Attachments
+
+If the user requests "all attachments" (audit/backup scenario):
+
+- Split into two directories:
+  - `images/` — files referenced inline in `body.storage`
+  - `images_unused/` — attached to the page but **not** referenced inline
+- Report summary: `Used: N inline / Total: M attached`
+
+```bash
+# Download only referenced attachments
+for filename in $REFERENCED_FILES; do
+  att_id=$(vds-cli confluence content list-attachments <PAGE_ID> --json-only \
+    | jq -r ".[] | select(.title == \"$filename\") | .id")
+  uv run --directory ~/.claude/vds-scripts --package vds-cli \
+    vds-cli confluence content download-attachment "$att_id" --out "images/$filename"
+done
+```
+
+## Rule 4 — Verify Before Reporting "Done"
+
+After generating `content.md`:
+
+1. Count inline image refs in output: `grep -c '!\[.*\](images/.*)' content.md`
+2. Count `ri:filename` occurrences in `body.storage`
+3. **Both counts must match.** If they differ, log a warning with the diff:
+
+```
+WARNING: Image ref mismatch — storage has 3 ri:filename refs, content.md has 2 inline images.
+Missing: screen-step3.png
+```
+
+Do not report success if counts diverge.
+
+## Rule 5 — Correct Invocation Sequence (Step by Step)
+
+```bash
+# B1: Fetch storage body (source of truth for image refs)
+uv run --directory ~/.claude/vds-scripts --package vds-cli \
+  vds-cli confluence content page <PAGE_ID> --expand body.storage
+
+# B2: Extract ri:filename values from storage XML (see Rule 1 Python snippet)
+
+# B3: Download only referenced attachments
+uv run --directory ~/.claude/vds-scripts --package vds-cli \
+  vds-cli confluence content download-attachment <ATT_ID> --out images/<filename>
+
+# B4: Convert storage XHTML → markdown (see Rule 2 Python snippet)
+#     - ac:image → ![](images/...) in-place
+#     - tables stay as HTML
+#     - output: content.md + images/
+
+# B5: Verify (see Rule 4)
+```
+
+## Anti-Patterns (What NOT to Do)
+
+| Anti-pattern | Why it fails |
+|---|---|
+| Fetch `body.view` then strip HTML | Loses image positions, macro-injected images leak in |
+| `attachments --list` then download all | Downloads orphaned/versioned files (59 vs 3 actually used) |
+| Flatten `<table>` to markdown `\|` pipe tables | Destroys merged cells, nested bullets, colspan/rowspan |
+| Collect images at end of document | Breaks image↔context mapping (which screen? which step?) |
+| Skip verification | Silent data loss — user trusts output without knowing images are missing |