@ngocsangairvds/vsaf 5.5.0 → 5.5.2

package/package.json

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

package/skills/sdlc/onboard-code/SKILL.md

@@ -142,7 +142,10 @@ Icon: `⏳` running, `✅` done, `❌` error.
     - Code module (from GitNexus) → is there a corresponding business concept? (check graph.json)
       - YES → record mapping
       - NO → technical module (infra, utils) — OK, record note
-17. Update `CONTEXT.md` with technical terms from code:
+17. Update `CONTEXT.md` with technical terms from code — IDEMPOTENTLY (never overwrite the whole file, never
+    blind-append; re-runs must not bloat it): PRESERVE the `## Shared Language` section written by onboard-docs;
+    own `## Cross-Domain Verification` + `## Technical Terms` — if a section exists REPLACE its body in place,
+    else append it; one row per mapping/term (dedupe, update rather than duplicate):
 
 ```markdown
 ## Technical Terms

package/skills/sdlc/onboard-docs/SKILL.md

@@ -155,7 +155,10 @@ Print conversion summary:
 [ONBOARD-DOCS] [4/4] Extract domain terms → CONTEXT.md... ⏳
 ```
 
-15. From the completed graph, extract domain terms → `CONTEXT.md`
+15. From the completed graph, extract domain terms → `CONTEXT.md` — update IDEMPOTENTLY (never overwrite the
+    whole file, never blind-append; re-runs must not bloat it): ensure one top `# Project Context: {name}`
+    heading, then own the `## Shared Language` section — if it exists REPLACE its body in place, else append it;
+    leave other sections (`## Technical Terms`, `## Cross-Domain Verification`) untouched; one row per Term (dedupe).
 16. Format Shared Language table:
 
 ```markdown

package/workflows/sdlc/onboard-code.yaml

@@ -0,0 +1,108 @@
+name: onboard-code
+description: |
+  Onboard Code — GitNexus index + verify + environment setup + cross-domain verify (mirrors the
+  sdlc-onboard-code skill, one node per phase). Detect structure -> GitNexus index -> verify index ->
+  env/Docker -> cross-domain verify (reads graphify-out/graph.json from onboard-docs) -> summary.
+  GitNexus is the SINGLE SOURCE OF TRUTH for code; graphify/graph.json is docs-only and READ-ONLY here.
+provider: claude
+model: sonnet
+nodes:
+  - id: detect-structure
+    description: Code 1/6 — detect project structure (single / multi-repo / non-git)
+    permission_mode: bypassPermissions
+    workspace: false
+    timeout: 900000
+    prompt: |
+      You are a Senior DevOps + Code Architect onboarding a codebase. Project path: $ARGUMENTS (or current dir).
+      Print `[ONBOARD-CODE] [1/6] Detect project structure... ⏳/✅`.
+
+      Determine structure: root `.git`? → single repo. No root `.git` → scan 1–2 levels for `.git/`:
+      found N → multi-repo/microservice (list {path, remote, branch}); none → non-git project.
+      Record the result under `## Project Structure` in `.vsaf/docs/onboarding/env-setup.md`.
+      Artifact boundary: write only at project root or under root `.vsaf/`. ⛔ Do NOT modify `graphify-out/` or `.gitnexus/`.
+
+  - id: gitnexus-index
+    description: Code 2/6 — build the GitNexus code index (single unified index at project root)
+    workspace: false
+    timeout: 3600000
+    depends_on:
+      - detect-structure
+    bash: |
+      set -e
+      echo "[ONBOARD-CODE] [2/6] GitNexus index... ⏳"
+      # Use the LOCAL binary — do NOT use `npx -y gitnexus@latest` (native-module crash on Node 24+).
+      if [ -d .git ]; then
+        echo "[ONBOARD-CODE] git repo at root → npx gitnexus analyze ."
+        npx gitnexus analyze .
+      else
+        echo "[ONBOARD-CODE] no root .git → npx gitnexus analyze . --skip-git (covers sub-repos too)"
+        npx gitnexus analyze . --skip-git
+      fi
+      echo "[ONBOARD-CODE] [2/6] GitNexus index... ✅ (single .gitnexus/ at project root)"
+
+  - id: verify-index
+    description: Code 3/6 — map + verify the GitNexus index via MCP (do NOT trust blindly)
+    permission_mode: bypassPermissions
+    workspace: false
+    timeout: 1800000
+    depends_on:
+      - gitnexus-index
+    prompt: |
+      Print `[ONBOARD-CODE] [3/6] Verify GitNexus index... ⏳/✅`.
+
+      Claude MUST review the index — do not assume it is correct. Using the GitNexus MCP tools:
+      - `group_sync` if the index needs (re)syncing; `list_repos` — confirm the project root is indexed (one unified index).
+      - `route_map` — confirm API routes from ALL repos are mapped; `tool_map` + `context` on 3–5 key entry points per repo.
+      Check: main entry points indexed? inter-module dependencies correct? for multi-repo, cross-service calls
+      (HTTP/gRPC/event) captured? If something is missing, re-run `group_sync` or record
+      "{module/route} not indexed — needs manual review" in `.vsaf/docs/onboarding/env-setup.md`.
+      ⛔ Only GitNexus writes `.gitnexus/`; do not edit it directly.
+
+  - id: env-docker
+    description: Code 4/6 — environment check + Docker setup suggestion
+    permission_mode: bypassPermissions
+    workspace: false
+    timeout: 1800000
+    depends_on:
+      - verify-index
+    prompt: |
+      Print `[ONBOARD-CODE] [4/6] Environment check + Docker setup... ⏳/✅`.
+
+      Detect the tech stack (read package.json, pom.xml, build.gradle, requirements.txt, Dockerfile, docker-compose.yml).
+      Check the current env (`java -version`, `node -v`, `docker -v`, `python3 --version`, …); compare required vs present
+      and suggest installs. Docker: if no Dockerfile/docker-compose.yml, suggest creating them (app + DB/cache/broker as needed);
+      if present, sanity-check the config. Record everything under `.vsaf/docs/onboarding/env-setup.md`
+      (this is the only md file this phase creates — no project-overview/codebase-map).
+
+  - id: cross-domain
+    description: Code 5/6 — cross-domain verify (GitNexus code ↔ docs graph.json) + technical terms
+    permission_mode: bypassPermissions
+    workspace: false
+    timeout: 1800000
+    depends_on:
+      - env-docker
+    prompt: |
+      Print `[ONBOARD-CODE] [5/6] Cross-domain verify... ⏳/✅`.
+
+      Read `graphify-out/graph.json` (the docs graph from onboard-docs — READ ONLY) and query the code via GitNexus (`query`, `context`). Cross-reference:
+      - business concept (graph.json) → is there a matching code module? YES → record `{concept} ↔ {module/class}`; NO → "{concept} not yet implemented".
+      - code module (GitNexus) → matching business concept? YES → mapping; NO → technical module (infra/utils), record as such.
+      Update `CONTEXT.md` IDEMPOTENTLY — never overwrite the whole file, and never blind-append (re-runs would bloat it). Manage BY SECTION:
+      - PRESERVE the `## Shared Language` section written by onboard-docs — do NOT delete or rewrite it.
+      - You OWN `## Cross-Domain Verification` (the concept↔module mappings above) and `## Technical Terms`
+        (table: | Term | Definition | Maps to Business Concept |). If a section already exists, REPLACE its body in place; otherwise append it.
+      - Keep ONE row per mapping/term (dedupe by key) — update rather than duplicate.
+      Flag any cross-database access. If `graphify-out/graph.json` is absent, note that onboard-docs must run first.
+
+  - id: summary
+    description: Code 6/6 — onboarding summary report
+    model: haiku
+    workspace: false
+    timeout: 600000
+    depends_on:
+      - cross-domain
+    prompt: |
+      Print `[ONBOARD-CODE] [6/6] Create summary report... ⏳/✅` then the report table:
+      Project structure / GitNexus index (N repos) / Index verification / Tech stack / Environment (ready or missing) /
+      Docker (exists or suggested) / Cross-domain mapping (N mapped, M gaps) / CONTEXT.md updated.
+      End with: "Artifacts saved. If interrupted, re-run the next phase — data is safe."

package/workflows/sdlc/onboard-docs.yaml

@@ -0,0 +1,102 @@
+name: onboard-docs
+description: |
+  Onboard Docs — build & verify the documentation knowledge graph (mirrors the sdlc-onboard-docs
+  skill, one node per phase). Scan/import docs -> graphify build -> Claude verify & supplement ->
+  extract domain terms. Graphify runs ONLY on docs (never source code — that is onboard-code/GitNexus).
+provider: claude
+model: sonnet
+nodes:
+  - id: scan-import
+    description: Docs 1/4 — scan & import documents (markitdown conversion + tier fallbacks)
+    permission_mode: bypassPermissions
+    workspace: false
+    timeout: 1800000
+    prompt: |
+      You are a Knowledge Engineer onboarding project documents. Project path: $ARGUMENTS (or current dir).
+      Print progress as `[ONBOARD-DOCS] [1/4] Scan & import documents... ⏳/✅`.
+
+      1. Scan ALL documents: README, docs/, wiki/, specs/, *.md, *.txt (+ complex binaries). List them.
+      2. Resolve markitdown python:
+           VENVS=$(pipx environment --value PIPX_LOCAL_VENVS 2>/dev/null)
+           MARKITDOWN_PYTHON="${VENVS}/markitdown/bin/python"  (fallback ~/.local/pipx/venvs/markitdown/bin/python)
+         If markitdown is missing, skip conversion and route ALL complex files through fallbacks (step 4).
+      3. Classify each complex file into a tier:
+           - Tier 1 (graphify-native): PDF, DOCX, XLSX, PNG, JPG, GIF, WEBP
+           - Tier 2 (graphify-blind): HTML, PPTX, EPUB, ZIP
+           - .md/.txt are NOT complex (read directly).
+      4. For each complex file: attempt `"$MARKITDOWN_PYTHON" "<this-skill-dir>/convert.py" --input {file} --output .vsaf/docs/onboarding/doc-imports/{name}.md`.
+         Verify the output has real content (not just headers, not an LLM refusal, not hallucinated). On success use it.
+         On failure/verify-fail: Tier 1 -> append original path to `.vsaf/docs/onboarding/graphify-direct-read.txt`;
+         Tier 2 HTML -> Read the file + write clean markdown to doc-imports/{name}.md; Tier 2 PPTX/EPUB/ZIP -> skip.
+      5. Print a conversion summary (markitdown OK / graphify-direct / Claude-Read / skipped counts).
+
+      Artifact boundary: write generated artifacts ONLY at project root or under root `.vsaf/`. ⛔ Do NOT modify `graphify-out/` or `.gitnexus/`.
+
+  - id: graphify-build
+    description: Docs 2/4 — graphify build over a docs-only staging dir -> graph.json
+    permission_mode: bypassPermissions
+    workspace: false
+    timeout: 3600000
+    depends_on:
+      - scan-import
+    prompt: |
+      Print progress `[ONBOARD-DOCS] [2/4] Graphify build for docs... ⏳/✅`.
+
+      1. Create `.vsaf/docs/onboarding/graphify-staging/` and populate it with ALL doc inputs:
+         original text docs (.md/.txt/README), converted .md from `.vsaf/docs/onboarding/doc-imports/`,
+         and the original binaries listed in `.vsaf/docs/onboarding/graphify-direct-read.txt`.
+         This staging dir is the SINGLE input to graphify — it guarantees graphify sees docs only, never code.
+      2. Run `/graphify .vsaf/docs/onboarding/graphify-staging/`.
+      3. Output: `graphify-out/graph.json`.
+
+      ⛔ CRITICAL: graphify is ONLY for docs — DO NOT run graphify on source code (code = GitNexus, in onboard-code).
+      Only graphify may write `graphify-out/`.
+
+  - id: verify-fix
+    description: Docs 3/4 — Claude verifies graph vs docs and supplements missing nodes/edges
+    permission_mode: bypassPermissions
+    workspace: false
+    timeout: 3600000
+    depends_on:
+      - graphify-build
+    prompt: |
+      Print progress `[ONBOARD-DOCS] [3/4] Verify & fix graph... ⏳/✅`.
+
+      Do NOT trust the graph blindly. For EACH original doc:
+      1. Re-read it — extract concepts, relationships, business rules, constraints.
+      2. Read `graphify-out/graph.json` — find the corresponding nodes/edges.
+      3. Compare: concept/relationship/rule present in the doc but missing in the graph = MISSING.
+      4. Supplement any MISSING nodes/edges DIRECTLY into `graph.json` (this Phase-3 supplementation is the
+         ONLY permitted direct write to graph.json). Report per doc: "{doc}: +N nodes, +M edges".
+
+      Every missing concept/relationship MUST be supplemented, not skipped.
+
+  - id: extract-terms
+    description: Docs 4/4 — extract domain terms from the graph into CONTEXT.md (Shared Language)
+    model: haiku
+    permission_mode: bypassPermissions
+    workspace: false
+    timeout: 900000
+    depends_on:
+      - verify-fix
+    prompt: |
+      Print progress `[ONBOARD-DOCS] [4/4] Extract domain terms → CONTEXT.md... ⏳/✅`.
+
+      From the completed `graph.json`, extract DOMAIN terms (business vocabulary, not technical/code terms —
+      those are added later by onboard-code).
+
+      Update `CONTEXT.md` at the project root IDEMPOTENTLY — never overwrite the whole file, and never blind-append
+      (re-running onboarding would bloat it). Manage the file BY SECTION:
+      - Ensure a single top `# Project Context: {project-name}` heading (create once if missing).
+      - You OWN the `## Shared Language` section: if it already exists, REPLACE its body in place; otherwise append it.
+        Leave every other section (e.g. `## Technical Terms`, `## Cross-Domain Verification`) untouched.
+      - Keep ONE row per Term (dedupe by term name) — update an existing term's row instead of adding a duplicate.
+
+      ## Shared Language
+
+      | Term | Definition | Example |
+      |------|-----------|---------|
+      | {term} | {1-line definition} | {concrete example} |
+
+      The graph is the single source of truth — do NOT create redundant overview/summary md files.
+      Then print: "Artifacts saved. If interrupted, re-run the next phase — data is safe."

package/workflows/sdlc/onboarding.yaml

@@ -1,11 +1,28 @@
 name: onboarding
-description: "Utility — Onboarding: docs graph + code graph + env setup (not part of main flow)"
+description: |
+  Phase 0 — Onboarding orchestrator (utility; NOT part of the master SDLC flow). Runs the two
+  step-level phase workflows in ONE run/workspace via sub-workflow includes:
+  init artifact structure -> onboard-docs (docs knowledge graph) -> onboard-code (GitNexus index +
+  env/Docker + cross-domain verify). Ordering matters: onboard-code reads graphify-out/graph.json
+  produced by onboard-docs, so docs MUST run before code.
+  Prerequisite (one-time, per machine): run `/sdlc-setup` to install tooling (GitNexus, markitdown).
 nodes:
-  - id: docs
-    description: "Onboard Docs: build documentation knowledge graph"
-    command: sdlc-onboard-docs
+  - id: init
+    description: Phase 0.1 — initialize .vsaf artifact structure (.vsaf/docs, CONTEXT.md, .gitignore)
+    model: haiku
+    permission_mode: bypassPermissions
     workspace: false
+    timeout: 600000
+    command: sdlc-init
+
+  - id: docs
+    description: Phase 0.2 — onboard-docs (build + verify docs knowledge graph)
+    depends_on:
+      - init
+    workflow: sdlc/onboard-docs
+
   - id: code
-    description: "Onboard Code: analyze codebase structure and conventions"
-    command: sdlc-onboard-code
-    workspace: false
+    description: Phase 0.3 — onboard-code (index code + env/Docker + cross-domain verify)
+    depends_on:
+      - docs
+    workflow: sdlc/onboard-code