@ngocsangairvds/vsaf 4.1.9 → 4.1.10

package/skills/vds-skill/runtime/docs/vi/agents/how-to/phase131-all-project-preparation.md

@@ -0,0 +1,213 @@
+<!-- diátaxis: how-to -->
+
+<!-- TODO: translate — Vietnamese translation pending -->
+
+# Phase 131 All-Project Preparation
+
+Use this guide when you want to prepare multiple projects for parent `workflow-projects` execution before or during bounded analysis.
+For shared env/config/cache path behavior and portable cache-root conventions, see `../reference/portable-paths-and-config.md`.
+When running from a dedicated `vds-scripts` worktree, prefer `./scripts/worktree_uv.sh run --project audit_orchestrator ...` over plain `uv run ...` so a different checkout's active `.venv` does not leak into the current worktree.
+
+> **Note — interactive use vs. shell scripts**: The `uv run --project <path>` commands below are for interactive terminal or agent use from the repo root. When writing shell scripts, use `vds_uv_run_package <member>` from `scripts/vds_sh_helpers.sh` instead — see `scripts/README.md` for the canonical contract.
+
+## What `workflow-projects` preparation does
+
+The parent command is intentionally thin. It composes existing runtime surfaces rather than replacing them:
+
+- `parse-registry` for project discovery when `--registry-page` is used
+- `prepare` for project-scoped material preparation
+- `state readiness` as the authoritative child-launch gate
+- `state completeness` as a material-quality signal surfaced in parent artifacts
+- child `workflow-project` for actual project analysis
+
+Parent artifacts are derived orchestration outputs only:
+
+- `dispatch-manifest.json`
+- `dispatch-progress.state`
+- `cross-project-summary.json`
+
+Do not treat these files as a replacement for centralized readiness, completeness, evidence, or child terminal truth.
+
+## Selection modes
+
+### Registry-wide discovery
+
+Use `--registry-page` when the registry page should decide project scope.
+
+```bash
+./scripts/worktree_uv.sh run --project audit_orchestrator \
+  vds-cli audit workflow-projects \
+  --registry-page <REGISTRY_PAGE_ID> \
+  --prepare-materials \
+  --max-projects-prepare-concurrent 3 \
+  --max-projects-concurrent 3 \
+  --max-concurrent 16
+```
+
+### Explicit project set
+
+Use `--project-storage-keys` when you already know the exact project page IDs.
+
+> **State prerequisite**: Projects must already be present in centralized Postgres state before `--project-storage-keys` can select them. If any key is missing, `workflow-projects` fails loudly with "missing from centralized state". For newly created Confluence pages that have not yet been parsed, run `parse-registry --registry-page <PARENT_OR_DEPARTMENT_PAGE_ID> --state-dsn env` first.
+
+```bash
+# If projects are new (Confluence-only), parse first:
+./scripts/worktree_uv.sh run --project audit_orchestrator \
+  vds-cli audit parse-registry --registry-page <PARENT_PAGE_ID> --state-dsn env
+
+# Then run workflow-projects with explicit keys:
+./scripts/worktree_uv.sh run --project audit_orchestrator \
+  vds-cli audit workflow-projects \
+  --project-storage-keys 88727304,88718940 \
+  --prepare-materials \
+  --max-projects-prepare-concurrent 2 \
+  --max-projects-concurrent 2 \
+  --max-concurrent 16
+```
+
+### Explicit checklist page when discovery fails
+
+When the checklist page is **not a direct child of the project page** (e.g., Payment department projects where checklist page `88722450` lives at the root level), auto-discovery fails and child `workflow-project` runs fall back to targeted mode (1-3 rows) instead of the full canonical 56-row evaluation.
+
+**Important page ID facts**:
+- `88722450` — standard backend checklist page; correct for all Payment department projects. This produces a full 56-row evaluation. Confirmed bootstrap signal: `canonical_checklist_bootstrap_preflight_passed: source=explicit_page_id`
+- `88716673` — Payment-specific page with topology issues (`checklist_topology_report=null`); do NOT use this as the `--checklist-page-id` value; the parser cannot extract rows from it.
+
+Pass `--checklist-page-id` to `workflow-projects` and it is forwarded to all child runs:
+
+```bash
+# Payment department example — checklist page is at root, not under each project
+# Repo-page publication defaults to the canonical project page as the hierarchy anchor.
+# Omit --confluence-parent; the publisher creates the shared Project Audit node under each project page.
+./scripts/worktree_uv.sh run --project audit_orchestrator \
+  vds-cli audit workflow-projects \
+  --project-storage-keys 91334048,91335346 \
+  --checklist-page-id 88722450 \
+  --prepare-materials \
+  --max-projects-prepare-concurrent 2 \
+  --max-projects-concurrent 2 \
+  --max-concurrent 4
+```
+
+The same flag works on `workflow-project` (single project):
+
+```bash
+./scripts/worktree_uv.sh run --project audit_orchestrator \
+  vds-cli audit workflow-project \
+  --project-storage-key 91334048 \
+  --thread-id <thread_id> \
+  --checklist-page-id 88722450
+```
+
+For repo-page publication on a single Payment project, omit `--confluence-parent` in the normal case. The project page is the default hierarchy anchor; `88716694` remains the department discovery page, not the upload parent:
+
+```bash
+./scripts/worktree_uv.sh run --project audit_orchestrator \
+  vds-cli audit workflow-project \
+  --project-storage-key 91334048 \
+  --thread-id <thread_id> \
+  --checklist-page-id 88722450 \
+  --upload-to-confluence
+```
+
+Supply `--confluence-parent` only when overriding the default project-page anchor (e.g., for a specific target page). Resolution uses three-tier fallback: explicit `--confluence-parent` → canonical project page id → `project_storage_key`.
+
+Run-intent guidance:
+- use a fresh `--thread-id` when you want a new run identity
+- when the command surface supports resume-specific-run or publish-only-by-run-root, prefer that explicit selector over implicit auto-resume when reusing a known prior run
+
+## Preparation and gating controls
+
+### Default preparation behavior
+
+`workflow-projects` defaults to `--prepare-materials`.
+
+That means each selected project is prepared before child project analysis is launched. In the current runtime, parent preparation can surface preparation payload details such as readiness and completeness summaries into parent project entries.
+
+### Skip preparation
+
+Use `--skip-materials` only when the project set is already ready or when a resume-driven rerun should rely on current centralized state instead of re-preparing everything.
+
+```bash
+./scripts/worktree_uv.sh run --project audit_orchestrator \
+  vds-cli audit workflow-projects \
+  --project-storage-keys 88727304,88718940 \
+  --skip-materials \
+  --max-projects-concurrent 2 \
+  --max-concurrent 16
+```
+
+### Strict material gate
+
+Use `--require-all-materials` when any failed preparation/readiness result should block analysis launch for the selected scope.
+
+```bash
+./scripts/worktree_uv.sh run --project audit_orchestrator \
+  vds-cli audit workflow-projects \
+  --registry-page <REGISTRY_PAGE_ID> \
+  --prepare-materials \
+  --require-all-materials \
+  --max-projects-prepare-concurrent 3 \
+  --max-projects-concurrent 3 \
+  --max-concurrent 16
+```
+
+In strict mode, the parent run completes preparation/readiness evaluation for the selected set, records blocking projects in parent artifacts, and returns a blocked parent outcome instead of failing on the first project.
+
+## Reading the parent artifacts
+
+### `dispatch-manifest.json`
+
+Use this to inspect:
+
+- selected projects
+- parent thread ID
+- child thread IDs and child report roots
+- preparation and execution status per project
+- readiness/completeness information surfaced from preparation payloads
+- pressure diagnostics such as effective preparation and analysis concurrency
+
+### `dispatch-progress.state`
+
+Use this for a current progress snapshot while the parent run is active.
+
+### `cross-project-summary.json`
+
+Use this after the run for rollup triage:
+
+- counts by status
+- project-level recovery states
+- parent pressure diagnostics
+- upload outcome collection
+- child report locations
+
+## Verification sequence
+
+Before a large run, it is still safer to verify:
+
+1. credentials and profile availability
+2. project selection scope
+3. preparation behavior on a small slice
+4. parent artifacts and child report layout
+
+Recommended checks:
+
+```bash
+./scripts/worktree_uv.sh run --project audit_orchestrator \
+  vds-cli audit --json-only doctor profile-availability --mode active
+
+./scripts/worktree_uv.sh run --project audit_orchestrator \
+  vds-cli audit --json-only state readiness --project 88727304
+
+./scripts/worktree_uv.sh run --project audit_orchestrator \
+  vds-cli audit --json-only state completeness --project 88727304
+
+./scripts/worktree_uv.sh run --project audit_orchestrator \
+  vds-cli audit query-checklist --checklist-page 88722450 --summary-only
+```
+
+Use `query-checklist` when you need to confirm the source checklist page is parsable before a broad parent run, especially when department-level auto-discovery has already shown `checklist_discovery_failed` in earlier attempts.
+
+## Current caveat
+
+The historical Phase 131 parent workstream is now part of the merged mainline parent runtime. For broad all-project operation, still use bounded slices first and scale outward only after checking parent artifacts and child report layout on a smaller set.

package/skills/vds-skill/runtime/docs/vi/agents/how-to/phase131-bounded-parallel-analysis.md

@@ -0,0 +1,125 @@
+<!-- diátaxis: how-to -->
+
+<!-- TODO: translate — Vietnamese translation pending -->
+
+# Phase 131 Bounded Parallel Analysis
+
+Use this guide when running the landed `workflow-projects` parent command with explicit outer-project and inner child concurrency settings.
+When running from a dedicated `vds-scripts` worktree, prefer `./scripts/worktree_uv.sh run --project audit_orchestrator ...` over plain `uv run ...` so a different checkout's active `.venv` does not leak into the current worktree.
+
+> **Note — interactive use vs. shell scripts**: The `uv run --project <path>` commands below are for interactive terminal or agent use from the repo root. When writing shell scripts, use `vds_uv_run_package <member>` from `scripts/vds_sh_helpers.sh` instead — see `scripts/README.md` for the canonical contract.
+
+## The three concurrency layers
+
+Keep these separate:
+
+1. `--max-projects-prepare-concurrent`
+   - parent preparation fan-out ceiling
+2. `--max-projects-concurrent`
+   - parent project-analysis fan-out ceiling
+3. `--max-concurrent`
+   - child `workflow-project` repo-dispatch ceiling
+
+The parent runtime now surfaces pressure diagnostics in parent artifacts so operators can distinguish these lanes.
+
+## Recommended starting posture
+
+For bounded verification, start conservatively:
+
+```bash
+./scripts/worktree_uv.sh run --project audit_orchestrator \
+  vds-cli audit workflow-projects \
+  --registry-page <REGISTRY_PAGE_ID> \
+  --prepare-materials \
+  --max-projects-prepare-concurrent 2 \
+  --max-projects-concurrent 2 \
+  --max-concurrent 4
+```
+
+Then increase only after checking:
+
+- provider launch-readiness
+- DB and state responsiveness
+- Confluence upload expectations
+- child artifact generation rate
+
+## Example bounded runs
+
+### Small explicit slice
+
+```bash
+./scripts/worktree_uv.sh run --project audit_orchestrator \
+  vds-cli audit workflow-projects \
+  --project-storage-keys 88727304,88718940 \
+  --profiles zai-openai \
+  --profile-availability active \
+  --prepare-materials \
+  --max-projects-prepare-concurrent 2 \
+  --max-projects-concurrent 2 \
+  --max-concurrent 4
+```
+
+### Registry-driven bounded run
+
+```bash
+./scripts/worktree_uv.sh run --project audit_orchestrator \
+  vds-cli audit workflow-projects \
+  --registry-page <REGISTRY_PAGE_ID> \
+  --max-projects 3 \
+  --prepare-materials \
+  --max-projects-prepare-concurrent 3 \
+  --max-projects-concurrent 2 \
+  --max-concurrent 16
+```
+
+## Pressure diagnostics to inspect
+
+Parent artifacts may now include a pressure/parallelism section that helps estimate runtime pressure:
+
+- selected projects
+- blocked projects
+- runnable projects
+- effective preparation concurrency
+- effective analysis concurrency
+- child max concurrent
+- maximum parallel repo slots
+- counts snapshot
+
+Interpretation:
+
+- effective preparation concurrency = min(selected projects, `--max-projects-prepare-concurrent`)
+- effective analysis concurrency = min(runnable projects, `--max-projects-concurrent`)
+- maximum parallel repo slots = effective analysis concurrency × child `--max-concurrent`
+
+This is an operator aid, not a promise of perfectly uniform scheduling.
+
+## Resume guidance
+
+The parent command supports:
+
+- `--resume`
+- `--resume-dispatch-manifest <path>`
+
+Use resume when you want to continue from an existing parent manifest scope while preserving child lineage and report roots.
+Use the effective VDS cache root for your environment as defined by the portable Phase 2 contract in `../reference/portable-paths-and-config.md`.
+
+```bash
+./scripts/worktree_uv.sh run --project audit_orchestrator \
+  vds-cli audit workflow-projects \
+  --resume \
+  --report-dir <cache-root>/audit_runs/workflow-projects/<thread_id>
+```
+
+Or explicitly:
+
+```bash
+./scripts/worktree_uv.sh run --project audit_orchestrator \
+  vds-cli audit workflow-projects \
+  --resume-dispatch-manifest <cache-root>/audit_runs/workflow-projects/<thread_id>/dispatch-manifest.json
+```
+
+Resume scope is derived from parent artifacts, but readiness, completeness, and launch gating still need authoritative runtime revalidation.
+
+## Operational rule
+
+Do not describe outer-project concurrency as equivalent to child repo concurrency. The parent command and child command each have separate responsibilities and separate limits.

package/skills/vds-skill/runtime/docs/vi/agents/how-to/phase131-confluence-upload-recovery.md

@@ -0,0 +1,206 @@
+<!-- diátaxis: how-to -->
+
+<!-- TODO: translate — Vietnamese translation pending -->
+
+# Phase 131 Confluence Upload and Recovery
+
+Use this guide when enabling Confluence publication through `workflow-projects`.
+When running from a dedicated `vds-scripts` worktree, prefer `./scripts/worktree_uv.sh run --project audit_orchestrator ...` over plain `uv run ...` so a different checkout's active `.venv` does not leak into the current worktree.
+
+> **Note — interactive use vs. shell scripts**: The `uv run --project <path>` commands below are for interactive terminal or agent use from the repo root. When writing shell scripts, use `vds_uv_run_package <member>` from `scripts/vds_sh_helpers.sh` instead — see `scripts/README.md` for the canonical contract.
+
+Default child publication writes a rich Confluence page body. `--upload-to-confluence` alone should still publish summary, findings, checklist, and provenance content; `--upload-attachments` only controls whether files are attached alongside that page body.
+
+## Upload ownership model
+
+Upload remains child-owned.
+
+Parent `workflow-projects` does **not** replace child publication logic. Instead it:
+
+- forwards `--upload-to-confluence`
+- forwards `--confluence-parent`
+- collects child upload outcomes in parent artifacts
+
+Repo-page publication now defaults to the canonical project page as the hierarchy anchor. You do not need to supply `--confluence-parent` for normal runs. The publisher creates one shared `Project Audit - <project name> (<project page id>)` node under that project page and places each repo report page beneath it. When `--confluence-parent` is supplied, it overrides the default anchor for all projects in that invocation — use this only for manual routing corrections. Do not pass `--confluence-parent 88716694` as a global override for Payment publication, as it pins all project audit pages under the department page.
+
+Child `workflow-project` still owns:
+
+- repo page uploads
+- project aggregate uploads
+- upload error details
+
+Default publication should still produce rich Confluence storage-format page bodies for both repo pages and the project aggregate page. `--upload-attachments` only controls attachment transfer; it must not downgrade the page body to a plain/minimal upload.
+
+## Enabling upload
+
+`--confluence-parent` is no longer required when enabling upload. The normal runtime path anchors repo-page publication on the canonical project page for each child project.
+
+Normal upload invocation (no explicit parent needed):
+
+```bash
+./scripts/worktree_uv.sh run --project audit_orchestrator \
+  vds-cli audit workflow-projects \
+  --project-storage-keys 88727304,88718940 \
+  --prepare-materials \
+  --upload-to-confluence \
+  --max-projects-prepare-concurrent 2 \
+  --max-projects-concurrent 2 \
+  --max-concurrent 4
+```
+
+Use `--confluence-parent` only as a manual override when auto-resolution is insufficient (e.g., routing a project to a non-department parent page):
+
+```bash
+./scripts/worktree_uv.sh run --project audit_orchestrator \
+  vds-cli audit workflow-projects \
+  --project-storage-keys 88727304 \
+  --prepare-materials \
+  --upload-to-confluence \
+  --confluence-parent 12345 \
+  --max-projects-prepare-concurrent 2 \
+  --max-projects-concurrent 2 \
+  --max-concurrent 4
+```
+
+> **Note**: `--confluence-parent` supplied to `workflow-projects` overrides auto-resolution for ALL projects in that run. Do not supply it for multi-department runs where projects belong to different departments.
+
+## FR-150 — Confluence parent auto-resolution
+
+FR-150 introduced `_resolve_confluence_parent_for_project`, a utility that auto-derives the correct Confluence parent for each project. It uses a three-tier fallback:
+
+1. **Explicit `--confluence-parent`** — overrides everything; applies to all projects in the run
+2. **canonical project page id** — derived from `project_page.page_id`, top-level `page_id`, or `_project_and_department_page_metadata`; routes each project to its own project page
+3. **`project_storage_key`** — last-resort fallback when richer project-page metadata is unavailable
+
+This means:
+- Payment department projects publish under their own canonical project pages by default
+- Finance Platform projects publish under their own canonical project pages by default
+- Admin Products projects publish under their own canonical project pages by default
+- Operators running multi-project publication get per-project project-page anchoring without any extra flags
+
+Auto-resolution is logged with `confluence_parent_auto_resolved` when the resolved parent differs from an explicit argument. Check `dispatch-manifest.json` for `resolved_parent` per child project.
+
+### Payment department — publication examples
+
+Single project without explicit parent (normal case):
+
+```bash
+vds-cli audit workflow-project \
+  --project-storage-key 91334048 \
+  --thread-id <thread_id> \
+  --checklist-page-id 88722450 \
+  --upload-to-confluence
+```
+
+Multi-project across Payment department without explicit parent:
+
+```bash
+vds-cli audit workflow-projects \
+  --project-storage-keys 91334048,91335346 \
+  --checklist-page-id 88722450 \
+  --prepare-materials \
+  --upload-to-confluence \
+  --max-projects-concurrent 2 \
+  --max-concurrent 4
+```
+
+Cross-department run (auto-resolution routes each project to its own department):
+
+```bash
+vds-cli audit workflow-projects \
+  --project-storage-keys 91334048,88718940 \
+  --checklist-page-id 88722450 \
+  --prepare-materials \
+  --upload-to-confluence \
+  --max-projects-concurrent 2 \
+  --max-concurrent 4
+# 91334048 (Payment) → parent 88716694
+# 88718940 (Core Technology) → parent 88718815
+```
+
+### When to use `publish-project-run` (Phase 147-E)
+
+`publish-project-run` with `--resume-run` is the explicit publish-only surface (Phase 147-E, implemented in the phase147e worktree). Prefer it over `workflow-project --upload-to-confluence` when you need to publish a completed run without re-evaluating. Supply `--resume-run <thread_id>` to resolve the report directory from the prior run root automatically. FR-150 auto-resolution handles the Confluence parent — no `--confluence-parent` override needed.
+
+## Confluence endpoint note
+
+Current runtime treats configured Confluence URLs as explicit endpoints, not fallback targets. Operators may configure alternate internal or external URLs in the shared config for diagnostics, but runtime operations stay on the selected base URL.
+
+Operational guidance:
+- keep the normal internal/external server selection unchanged in commands unless a specific page URL implies the other server,
+- treat alternate endpoint probes as connectivity diagnostics, not as a signal that page identity changed,
+- if upload or checklist bootstrap fails with hostname reachability symptoms, inspect the configured Confluence URLs before assuming the page id or parent page is wrong.
+
+## What to inspect after upload
+
+### Parent artifacts
+
+Inspect:
+
+- `dispatch-manifest.json`
+- `dispatch-progress.state`
+- `cross-project-summary.json`
+
+Useful fields include:
+
+- project execution status
+- recovery status
+- upload summary
+- upload errors
+- project page identity as page id plus title/display name
+- department page identity as page id plus title/display name when lineage is available
+- if `parse-registry` starts from a department page or a direct project page, lineage reconstruction must still preserve those same additive `(page_id, title)` pairs before publication summaries are written
+- child report directories
+- collected `confluence_repo_page_ids`
+- collected `confluence_aggregate_page_id`
+
+### Child artifacts
+
+Use child report roots for authoritative publication truth when triaging upload problems.
+
+## Recovery states to watch
+
+Parent rollups may classify child outcomes such as:
+
+- `completed`
+- `failed`
+- `timed_out`
+- `exception`
+- `provider_blocked`
+- `upload_failed`
+
+These are recovery aids for project-scope triage. Final child truth still lives in child artifacts and centralized state.
+
+## Resume after partial upload
+
+If a parent run produced the expected manifest, prefer resuming from it rather than reconstructing scope manually.
+Use the effective VDS cache root for your environment as defined by the portable Phase 2 contract in `../reference/portable-paths-and-config.md`.
+
+```bash
+./scripts/worktree_uv.sh run --project audit_orchestrator \
+  vds-cli audit workflow-projects \
+  --resume-dispatch-manifest <cache-root>/audit_runs/workflow-projects/<thread_id>/dispatch-manifest.json
+```
+
+Before resuming, verify:
+
+- the manifest matches the intended parent run root
+- current provider availability is acceptable
+- centralized state is still valid for readiness/completeness gates
+- the Confluence parent page is still the intended destination
+
+Run-intent guidance:
+- when reusing a known prior run, prefer an explicit resume-specific-run or publish-from-run-root path when available
+- when you want a clean execution similar to a new Jenkins build, use a fresh run/thread id and do not rely on implicit auto-resume
+- do not mix department-level selection with project-page-rooted publication anchors
+
+## Suggested bounded verification sequence
+
+1. Run one or two projects first.
+2. Enable upload only after parent artifact shape looks correct.
+3. Confirm child repo pages and aggregate page creation.
+4. Resume from the parent manifest if upload recovery is needed.
+
+## Caveat
+
+The historical Phase 131 upload-pass-through work is now part of the merged parent runtime. For partial-upload and recovery scenarios, still validate the artifact shape on one or two bounded projects before broad parent reruns.

package/skills/vds-skill/runtime/docs/vi/agents/how-to/phase132-department-preparation.md

@@ -0,0 +1,146 @@
+<!-- diátaxis: how-to -->
+
+<!-- TODO: translate — Vietnamese translation pending -->
+
+# Phase 132 Department-Wide Materials Preparation
+
+Use this guide when preparing all actionable projects within a department before broad analysis. This guide covers the classification → investigation → re-preparation loop that ensures each project is in a known state before launching analysis.
+
+For the multi-project execution mechanics, see [phase131-all-project-preparation.md](phase131-all-project-preparation.md).
+For portable path conventions, see [../reference/portable-paths-and-config.md](../reference/portable-paths-and-config.md).
+
+## Preparation classification model
+
+After `prepare` runs for each project, `workflow-projects` classifies each project into:
+
+| `materials_classification` | `blocker_class` | Meaning | Action |
+|---------------------------|-----------------|---------|--------|
+| `ready` | (none) | Materials complete, analysis can proceed | Automatic — enters analysis queue |
+| `recoverable` | `missing_materials` | Materials incomplete, generic failure | Re-run `prepare --project <PSK>` |
+| `recoverable` | `projection_lag` | State exists but readiness hasn't caught up | Re-run `state readiness --project <PSK>` |
+| `recoverable` | `external_permission_block` | Bitbucket project is permission-denied | Grant access, then re-run `prepare` |
+| `recoverable` | `missing_linkage` | No Bitbucket repo links found in page or state | Investigate page content or junction state |
+
+Additionally, `quality_classification` describes material quality for `ready` projects:
+
+| `quality_classification` | Meaning |
+|--------------------------|---------|
+| `high_confidence` | All material quality checks passed |
+| `acceptable_with_quality_debt` | Materials present but some quality debt |
+| `quality_unknown` | No quality assessment available |
+
+## Canonical preparation sequence
+
+```bash
+# 1. Discover all child projects under a department page
+vds-cli audit parse-registry --registry-page <DEPARTMENT_PAGE_ID> --state-dsn env
+
+# 2. Prepare materials for a specific project
+vds-cli audit prepare --project <PROJECT_PAGE_ID>
+
+# 3. Verify readiness
+vds-cli audit --json-only state readiness --project <PROJECT_PAGE_ID>
+
+# 4. Run analysis (after all projects are ready)
+vds-cli audit workflow-project \
+  --project-storage-key <PROJECT_PAGE_ID> \
+  --thread-id <THREAD_ID> \
+  --checklist-page-id 88722450
+```
+
+## Department-wide preparation with classification
+
+```bash
+# Prepare all projects under a department with bounded concurrency
+vds-cli audit workflow-projects \
+  --registry-page <DEPARTMENT_PAGE_ID> \
+  --prepare-materials \
+  --max-projects-prepare-concurrent 3 \
+  --max-projects-concurrent 2 \
+  --max-concurrent 4 \
+  --checklist-page-id 88722450
+```
+
+After preparation, inspect the `cross-project-summary.json` artifact to see each project's classification:
+
+```bash
+cat ~/.vds/cache/audit_runs/<run_dir>/cross-project-summary.json | \
+  python3 -c "import json,sys; d=json.load(sys.stdin); [print(f'{p[\"project_storage_key\"]}: {p[\"materials_classification\"]} ({p.get(\"blocker_class\",\"\")}') for p in d.get('projects',[])]"
+```
+
+## Investigating blocked projects
+
+### Permission-blocked (`external_permission_block`)
+
+When `sync repos` cannot access a Bitbucket project:
+
+1. Check `last_error` for the specific Bitbucket project key and error message
+2. Verify the operator's Bitbucket credentials have access: `vds-cli audit doctor credentials --require-state-dsn`
+3. If access was recently granted, re-run preparation for that project only:
+
+```bash
+vds-cli audit prepare --project <PROJECT_PAGE_ID>
+```
+
+The SWIT Bitbucket project is the current known reference case for permission-blocked projects.
+
+### Missing linkage (`missing_linkage`)
+
+When a project page has no discoverable Bitbucket repository links:
+
+1. Use `research-skill` to investigate the Confluence page content
+2. Check if junction state already has repo linkage: `vds-cli audit --json-only state readiness --project <PSK>`
+3. If repos exist in Bitbucket but aren't linked from Confluence, add links to the project page and re-parse
+
+### Projection lag (`projection_lag`)
+
+Materials exist in state but readiness hasn't caught up:
+
+```bash
+# Re-run readiness check only (no re-preparation needed)
+vds-cli audit --json-only state readiness --project <PROJECT_PAGE_ID>
+```
+
+### Missing materials (`missing_materials`)
+
+Generic preparation failure. Re-run the full preparation:
+
+```bash
+vds-cli audit prepare --project <PROJECT_PAGE_ID>
+```
+
+## Re-preparing only the recoverable subset
+
+After initial preparation, re-prepare only the projects that failed without re-preparing already-ready siblings:
+
+```bash
+# List the specific PSKs that failed, then target them explicitly
+vds-cli audit workflow-projects \
+  --project-storage-keys <PSK_1>,<PSK_2> \
+  --prepare-materials \
+  --checklist-page-id 88722450
+```
+
+Do NOT re-run the full department scope when only a subset needs re-preparation.
+
+## Skill usage during preparation
+
+| Skill | When to use |
+|-------|-------------|
+| `audit-orchestrator-skill` | Running preparation and analysis commands |
+| `research-skill` | Investigating blockers (permission, linkage, source data) |
+| `git-worktree-skill` | Isolating preparation fixes and verification |
+| `spec-creation-skill` | Updating the audit-orchestrator spec after behavior changes |
+
+## Key safety rules
+
+- `--skip-readiness-check` is a debug-only bypass. Never use it as the normal preparation path.
+- `--require-all-materials` blocks ALL analysis when any project fails. Default is `False` — siblings continue independently.
+- Department page `88716694` (Payment) is the selection anchor for Payment projects. Each project resolves its own Confluence parent via FR-150 auto-resolution.
+- Checklist page `88722450` is at the root level and must be passed explicitly for department pages where auto-discovery fails.
+
+## Related guides
+
+- [All-project preparation](phase131-all-project-preparation.md)
+- [Confluence upload recovery](phase131-confluence-upload-recovery.md)
+- [CLI commands reference](../reference/cli-commands.md)