@ngocsangairvds/vsaf 4.1.9 → 4.1.10

package/skills/vds-skill/runtime/docs/agents/reference/agent-operational-contract.md

@@ -0,0 +1,162 @@
+<!-- diátaxis: reference -->
+# Agent Operational Contract
+
+This reference defines the runtime contract for AI agents operating inside the VDS WHO ecosystem. All behaviors listed here are required unless explicitly gated by capability flags.
+
+---
+
+## Token Budgets
+
+### Default session limits
+
+| Tier | Context tokens | Output tokens | Typical use |
+|------|---------------|---------------|-------------|
+| Fast | 8K | 1K | Grep, status, quick reads |
+| Standard | 32K | 4K | Most authoring and debugging |
+| Deep | 128K | 8K | Audit analysis, large diffs |
+
+### Budget gates
+
+- Agents must declare intent before entering a deep reasoning pass.
+- Agents must stop and report when a task exceeds the declared tier.
+- Compaction and checkpointing are preferred over silent truncation.
+
+---
+
+## Skill Loading
+
+### Canonical source
+
+Skills are loaded on-demand from:
+
+```
+WHO-project/vds-skills/skills/<skill-name>/SKILL.md
+```
+
+### Load order
+
+1. Check `cat skills/<skill-name>/SKILL.md` at the canonical path.
+2. Fallback to direct file read at the canonical path above.
+3. If both fail, report the exact missing path and stop.
+
+### Skill scope rules
+
+- Skills are advisory, not overriding. Runtime behavior in code wins when there is a conflict.
+- Agents must not inline skill content into instructions or AGENTS.md.
+- Agents must not modify canonical `SKILL.md` files unless the user explicitly requests a skill update.
+
+---
+
+## Tool Patterns
+
+### Execution primitives
+
+| Tool | Purpose | Escalation rule |
+|------|---------|-----------------|
+| `edit_file` | Apply structured patches to code | Approval required when >5 files or >100 lines changed |
+| `exec_command` | Run shell commands via PTY | Always return output and exit code; never hide failures |
+| `read_file` | Fetch file contents | Use absolute or workspace-relative paths; quote paths with spaces |
+| `glob` | List matching files | Prefer `rg` or `sg` over unbounded `find .` |
+| `web_search` | External research | Verify against local evidence before acting |
+
+### Concurrency rules
+
+- Background commands: use `run_in_background: true` for any command expected to take over 5 seconds.
+- Read commands: always wait for output before issuing dependent writes.
+- Mock rule for tests: external services must be mocked; no real API calls in test files.
+
+---
+
+## Memory Recall
+
+### Session memory
+
+- Ephemeral session context is provided by the harness (cwd, env vars, file tree).
+- Agents must treat session hints as advisory; verify against current filesystem state.
+
+### Persistent memory
+
+- Long-term memory is stored via the `memory_orchestrator` API.
+- Commands: `vds-cli memory search`, `vds-cli memory store`.
+- Category tags used: `code`, `design`, `incident`, `onboarding`.
+
+### Cross-agent recall
+
+- Shared memory writes must include `--importance high` when the discovery is likely to affect other agents.
+- Agents must search memory before claiming a new root-cause diagnosis.
+
+---
+
+## Escalation Rules
+
+### When to escalate
+
+- Command fails due to sandbox, permission, or path restriction.
+- External API returns unreachable or rate-limited.
+- Task boundary is crossed (e.g., moving from docs to Confluence sync to CI pipeline changes).
+- Uncertainty about whether a change affects AGENTS.md sync lines or validator counts.
+
+### Escalation format
+
+Include in every escalation:
+1. Exact command that failed
+2. Exit code and last 5 lines of output
+3. File paths involved
+4. Concrete next step you need approval for
+
+---
+
+## Compaction Management
+
+### Trigger conditions
+
+- Tool context grows beyond the session tier limit.
+- Multiple file reads accumulate without producing a write.
+- A long reasoning chain is about to generate a large single edit.
+
+### Compaction steps
+
+1. Summarize completed work in 3–5 sentences.
+2. List open questions or blockers.
+3. Preserve file paths and line-number anchors for the next action.
+4. Discard verbose tool output that has already informed a decision.
+
+---
+
+## Persona Boundaries
+
+### Human-facing docs
+
+- Tutorials and how-to guides are written for human contributors.
+- Code blocks must be copy-pasteable without modification.
+- Paths must be quoted and iCloud-safe.
+
+### Agent-facing docs
+
+- Reference and explanation docs are written for AI agents.
+- May include pseudocode, decision matrices, and validator call patterns.
+- Should explicitly mark machine-executable steps with `>` or code fences.
+
+---
+
+## Validation Hooks
+
+### Required pre-merge checks
+
+- `vds-cli docs validate` exits 0.
+- New files linked from `llms.txt` or `AGENTS.md`.
+- Diátaxis quadrant declared via `<!-- diátaxis: X -->` header.
+
+### Optional but recommended
+
+- `vds-cli docs check-freshness` reports 0 stale pairs.
+- `vds-cli spec validate` passes on spec files in the patch.
+
+---
+
+## Environment Assumptions
+
+- `cwd` is the monorepo root unless the user specifies a worktree path.
+- Shell is `zsh` on macOS, `bash` elsewhere.
+- Python tooling is executed through `uv run --project <pkg>`.
+- Secrets live in `~/.vds/.env` and are never inlined.

package/skills/vds-skill/runtime/docs/agents/reference/alignment-phase179-report.md

@@ -0,0 +1,144 @@
+# VDS-Scripts Agent Team Research: Doc↔Code↔Confluence Alignment Report
+
+**Date:** 2026-04-29  
+**Spec:** DOC-SPEC-009+ (Phase 179)  
+**Branch:** master (post-merge phase9/wave2-agent-core-expansion)
+
+---
+
+## Executive Summary
+
+| Check | Status | Score |
+|-------|--------|-------|
+| Validation (docs validate) | ✅ Pass | 100% |
+| Confluence sync (10 pages) | ✅ All synced | 100% |
+| Code→Docs parity (14 commands) | ✅ All documented | ~100% |
+| llms.txt links | ✅ All valid | 100% |
+| Diátaxis headers | ✅ Clean | 100% |
+| Orphan docs | ✅ 0 orphans | 100% |
+
+---
+
+## Detail: Code → Docs Parity
+
+### `docs_app.commands` in `vds_cli/src/vds_cli/cli.py` (14 commands)
+
+| # | Command | Function Line | Reference Doc | Status |
+|---|---------|---------------|---------------|--------|
+| 1 | `validate` | ~458 | `validation-and-sync-notes.md` + `confluence-sync.md` | ✅ |
+| 2 | `quality-score` | ~535 | `cli-help-matrix.md` + `ci-workflows.md` | ✅ |
+| 3 | `freshness` | ~584 | `validation-and-sync-notes.md` | ✅ |
+| 4 | `init-repo` | ~643 | `agent-operational-contract.md` | ✅ |
+| 5 | `ecosystem-index` | ~670 | `ecosystem-architecture.md` | ✅ |
+| 6 | `onboarding-funnel` | ~680 | `who-capability-inventory.md` | ✅ |
+| 7 | `freshness-heatmap` | ~728 | `cli-help-matrix.md` | ✅ |
+| 8 | `monthly-consumption` | ~747 | `cli-help-matrix.md` | ✅ |
+| 9 | `confluence-sync` | ~767 | `confluence-sync.md` + `confluence-sync-target.md` | ✅ |
+| 10 | `watch-agents` | ~818 | `watch-agents.md` | ✅ |
+| 11 | `watch-agents-install` | ~960 | `watch-agents.md` | ✅ |
+| 12 | `watch-agents-uninstall` | ~989 | `watch-agents.md` | ✅ |
+| 13 | `watch-agents-status` | ~1002 | `watch-agents.md` | ✅ |
+
+> **Note:** Two commands (`generate`, `spec-convert`) appear in `docs_app` but are commented/legacy. Not counted.
+
+---
+
+## Detail: Confluence Sync Alignment
+
+### English Pages (Auto)
+
+| Page ID | Title | Source File | Version | Status |
+|---------|-------|-------------|---------|--------|
+| 98997962 | WHO-Project Ecosystem Documentation | `AGENTS.md` + `ECOSYSTEM_ALIGNMENT.md` | v13 | ✅ Synced |
+| 98997963 | Ecosystem Installation Guide | `docs/agents/how-to/install-and-bootstrap-who-scripts-and-skills.md` | v3 | ✅ Synced |
+| 98997964 | vds-scripts Quick Reference | `AGENTS.md` | v3 | ✅ Synced |
+| 98997965 | vds-skills Quick Reference | `docs/vi/agents/how-to/install-and-bootstrap-who-scripts-and-skills.md` | v6 | ✅ Synced |
+| 98997966 | vds-claude-plugins Quick Reference | `vds_cli/README.md` | v6 | ✅ Synced |
+| 98997968 | Documentation Health Dashboard | `docs/agents/reference/health-dashboard.md` | v6 | ✅ Synced |
+
+### Vietnamese Pages (Manual IDs, Auto Content)
+
+| Page ID | Title | Source File | Version | Status |
+|---------|-------|-------------|---------|--------|
+| 99846963 | Hướng dẫn cài đặt hệ sinh thái | `AGENTS.vi.md` | v1 | ✅ Synced (no content change) |
+| 99846964 | Tài liệu tham khảo vds-scripts | `AGENTS.vi.md` | v1 | ✅ Synced (no content change) |
+| 99846965 | Tài liệu tham khảo vds-skills | `AGENTS.vi.md` | v1 | ✅ Synced (no content change) |
+| 99846966 | Tài liệu tham khảo vds-claude-plugins | `AGENTS.vi.md` | v1 | ✅ Synced (no content change) |
+
+---
+
+## Detail: CI Pipeline Alignment
+
+| Check | File | Status |
+|-------|------|--------|
+| Trigger on push (master, main) | `.github/workflows/confluence-sync.yml` | ✅ |
+| Validation before sync | `--check-vi --check-diataxis` | ✅ |
+| link validation flag | `--validate-links` | ✅ |
+| Secrets documented | `README.md` + `AGENTS.md` | ✅ |
+| Vietnamese pages in workflow | Not explicitly handled (no `--create-missing`) | ⚠️ By design—VI pages created manually |
+| Artifact upload | `.github/workflows/docs-confluence-evidence.yml` | ✅ (separate workflow) |
+
+---
+
+## Fixes Applied (DOC-SPEC-009)
+
+| Issue | File | Resolution |
+|-------|------|-----------|
+| Broken `llms.txt` link (wrong relative path) | `llms.txt` | Fixed `../` → `../../` |
+| Missing Diátaxis header | `backup-restore.md` | Added `<!-- diátaxis: reference -->` |
+| Missing Diátaxis header | `migration-playbook.md` | Added `<!-- diátaxis: reference -->` |
+| Orphaned docs not in llms.txt | `backup-restore.md`, `migration-playbook.md` | Registered entries in `llms.txt` |
+
+---
+
+## Commits
+
+| Hash | Description |
+|------|-------------|
+| `146441ba` | DOC-SPEC-009: Fix alignment issues (master, pushed) |
+| `41953385` | Merge phase9/wave2-agent-core-expansion to master |
+| `ae7b1d18` | DOC-SPEC-008: Sync scope + VI policy |
+| `260e54b8` | DOC-SPEC-007: Map VI page IDs |
+| `45396dad` | DOC-SPEC-006: Sync live pages |
+
+---
+
+## Next Steps / Open Items
+
+1. **No CI runs yet** — Confirm: `confluence-sync.yml` is wired but has no execution history on GitHub/Bitbucket Actions.
+2. **Command parity audit for `env` and `skills` sub-apps** — Could extend research to `env_app` and `skills_app` commands.
+3. **Vietnamese page version bump** — When `AGENTS.vi.md` is edited, these pages will get version bumps automatically.
+4. **Cross-repo alignment** — Check `vds-skills/` and `vds-claude-plugins/` docs against Confluence.
+
+---
+
+*Generated by vds-scripts alignment research team (Phase 179).*
+
+---
+
+## Post-Report Findings (DOC-SPEC-011)
+
+### Critical Gap: Stale vds-claude-plugins references in `.confluence.yaml`
+
+**Found by:** Agent team research (subagent `19-docs-confluence-alignment`)  
+**Fixed:** 2026-04-29 in commit `830f884`
+
+**Problem:**
+- `.confluence.yaml` listed `vds-claude-plugins` in `repos` section with `active: true`
+- But the repo was merged into `vds-skills` on 2026-04-22 per `ECOSYSTEM-CHANGELOG.md`
+- The vds-claude-plugins worktree no longer exists on disk
+- Sync code falls back to `vds-scripts` (default repo) content, but keeps the old page title
+- Result: **Misrepresentation bug** — Confluence pages (98997966, 99846966) show stale "vds-claude-plugins" branding
+
+**Fix:**
+- Changed `active: true` → `active: false` for vds-claude-plugins in `.confluence.yaml`
+- Added description: "vds-claude-plugins merged into vds-skills (2026-04-22). Content maintained in vds-skills repo."
+- Preserved page entries (IDs remain) so existing pages stay linked but won't get stale content
+
+**Impact:**
+| Page ID | Title | Content Source | Status Post-Fix |
+|---------|-------|---------------|-----------------|
+| 98997966 | vds-claude-plugins Quick Reference | vds-scripts (fallback) | ⚠️ Page exists, stale branding |
+| 99846966 | Tài liệu tham khảo vds-claude-plugins | vds-scripts (fallback) | ⚠️ Page exists, stale branding |
+
+> **Recommendation:** Consider archiving or renaming these pages in Confluence, or moving their content under the vds-skills pages.

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

@@ -0,0 +1,256 @@
+<!-- diátaxis: reference -->
+
+# Audit Triage Playbook
+
+Use the audit orchestrator as the authoritative triage entrypoint.
+
+## Flow
+
+1. Check environment and credentials.
+2. Check state readiness.
+3. Inspect source checklist rows with `query-checklist` when checklist-page resolution or row identity is unclear.
+4. Run targeted workflow or workflow-project.
+4. Validate spec sync before accepting doc or spec changes.
+
+## Checklist Inspection Commands
+
+Use `query-checklist` to inspect source checklist content directly before a rerun when the operator needs to confirm row ids, category placement, or checklist bootstrap behavior without launching workflow evaluation.
+
+```bash
+./scripts/worktree_uv.sh run --project audit_orchestrator \
+  vds-cli audit query-checklist --checklist-page 88722450 --summary-only
+
+./scripts/worktree_uv.sh run --project audit_orchestrator \
+  vds-cli audit query-checklist --checklist-page 88722450 --target row-1
+
+./scripts/worktree_uv.sh run --project audit_orchestrator \
+  vds-cli audit query-checklist --checklist-page 88722450 --target chk_1
+```
+
+Selector rule:
+- Treat `query-checklist` as the canonical selector-discovery surface for source checklist pages.
+- Prefer row ids (`row-1`) or numeric row selectors (`1`) from `query-checklist` output when targeting a unique source checklist row.
+- Parser check ids such as `chk_1` are accepted but may repeat across sections on the same checklist page, so use them only when you intentionally want that broader match set.
+- Do not copy `dispatch-manifest.json` internal payloads such as `explicit:88722450:...` into `workflow --target` or `query-checklist --target`; those are dispatch-internal row-key bundles, not operator-facing selector strings.
+
+If the checklist page should be inferred from centralized state instead of passed explicitly:
+
+```bash
+./scripts/worktree_uv.sh run --project audit_orchestrator \
+  vds-cli audit query-checklist \
+  --project-storage-key 88727304 \
+  --checklist-profile default \
+  --summary-only
+```
+
+## 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.
+
+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`.
+
+The commands below use the convenient interactive form (`uv run --project <path>` from the monorepo root).
+When calling from a shell script, use `vds_uv_run_package audit_orchestrator` instead — see
+[`scripts/README.md`](../../scripts/README.md#uv-contract--canonical-usage).
+
+```bash
+./scripts/worktree_uv.sh run --project audit_orchestrator \
+  vds-cli audit workflow <repo-cache-root>/PAR-project/merchant-report \
+  --profile zai-openai \
+  --project-storage-key 88727304 \
+  --thread-id phase124-row2-par-mr-zai \
+  --target row-2
+```
+Note: `--canonical-checklist` is no longer needed — full canonical 56-row evaluation is the default since Phase 133. Use `--target` to run specific rows within canonical mode.
+
+Use `workflow-project` only for project-scope lanes. For single-row `workflow` reruns, use `--target`; do not use unsupported legacy selectors such as `--check-ids` or `--targeted-rows`.
+For source-checklist single-row reruns, prefer selectors you already verified with `query-checklist`, for example `--target row-1`. Use `chk_*` only when you deliberately want every source row carrying that repeated parser-local id.
+
+For `CL-002`, expect one of two valid outcome shapes only:
+- strict skill routing resolves only `public-interface-boundary-skill`
+- for multi-repo CL-002 review, one project-scope `vds-cli public-interface scan-project` artifact may be reused as shared companion context across repo rows
+- when knowledge reuse is enabled, `workflow-project` may persist that shared project scan once and expose repo-keyed code-linked companion knowledge to later CL-002 row execution
+- that shared artifact is not authoritative by itself; final CL-002 evidence must still stay repo-grounded for the row being finalized
+- final exported evidence stays on boundary-relevant code refs; do not keep app-config, logging config, or generic build metadata as authoritative CL-002 evidence unless they directly prove the boundary rule
+- decisive verified public-interface boundary violation anchors => `FAIL`
+- no confirmed violation plus incomplete repo scan => `PARTIAL` with `evidence_gap_diagnostics.classification=evidence_gap`
+
+For `CL-006`, expect one valid proof-complete pass shape:
+- decisive verified production config excerpt => `PASS`
+- exported excerpt must retain datasource plus pool-limit keys (`minimum-idle`, `maximum-pool-size`, `max-lifetime` or equivalent)
+- generic caveats such as “chưa so sánh trực tiếp với service khác” or “không có bằng chứng trực tiếp để xác nhận ... KHÔNG dùng chung datasource” must not keep the row in `PARTIAL`/`FAIL` once the verified production trace already proves the required app-config keys
+- when the row guidance is app-config-specific, strict skill routing should resolve only `app-config-discovery-skill`
+
+For `CL-015`, keep environment precedence explicit:
+- decisive production app-config evidence can support `PASS` or `FAIL`
+- `staging`, `alpha`, or any lower-precedence env by itself remains `PARTIAL`
+- when the row guidance is app-config-specific, strict skill routing should resolve only `app-config-discovery-skill`
+
+For `CL-004`, expect one valid project-scope pass shape:
+- strict skill routing recommends only `circular-dependency-skill`
+- final exported evidence refs come from the project-scope dependency artifacts, not repo-local fallback files
+- decisive pass exports should retain:
+  - `project-dependency-graph.json`
+  - `project-cycle-report.json`
+  - `project-topology.json`
+
+For `CL-007`, expect one migration-only evidence shape:
+- strict skill routing resolves only `migration-script-detection-skill`
+- once the strict single-skill lane shows an effective execution-class call, take that skill result as authoritative and skip extra unverified-ref corrective retry churn plus DSPy judge/arbitration churn
+- final evidence should be migration manifests, changelogs, versioned SQL files, or execution/build wiring
+- do not attach centralized app-config companion refs as authoritative `CL-007` evidence
+- do not keep generic entities, services, adapters, or unrelated Java classes as authoritative `CL-007` evidence
+- if the repo has no migration assets, conclude from that absence directly instead of degrading into arbitrary code refs
+
+## Phase 3 Runtime Verification
+
+Phase 3 requires runtime-availability verification to be separate from
+file/catalog alignment. Use currently supported runtime checks and record any
+mismatch explicitly instead of assuming convenience commands exist.
+
+### Runtime verification flow
+
+1. Verify credentials with supported doctor commands.
+2. Verify active profile/provider availability.
+3. Verify project/repo readiness when the workflow depends on prepared state.
+4. Verify checklist/source retrieval separately when the problem is source-page
+   access rather than repo/project readiness.
+5. Record any verified mismatch in a dedicated runtime-status / known-runtime-
+   gaps section.
+
+### Supported checks
+
+```bash
+# Credentials
+./scripts/worktree_uv.sh run --project audit_orchestrator \
+  vds-cli audit --json-only doctor credentials --require-state-dsn
+
+# Profile / provider availability
+./scripts/worktree_uv.sh run --project audit_orchestrator \
+  vds-cli audit --json-only doctor profile-availability --mode active
+
+# Project readiness
+./scripts/worktree_uv.sh run --project audit_orchestrator \
+  vds-cli audit --json-only state readiness --project <PROJECT_PAGE_ID>
+```
+
+### Common runtime-gap scenarios
+
+- **Connectivity**: required services cannot be reached.
+- **Auth**: configured credentials are invalid or insufficient.
+- **Functional**: the service is reachable but the required operation still
+  fails.
+- **Environment**: local profile/config/runtime setup does not match the
+  documented expectation.
+
+For the full runtime-discovery and gap-reporting contract, see
+[Runtime Verification and Gap Reporting](../explanation/runtime-verification-and-gap-reporting.md).
+
+## Checklist Page Resolution Failures
+
+### Symptom: workflow evaluates only 1-3 rows instead of full 56-row canonical
+
+**Root cause**: Checklist auto-discovery failed — the checklist page is not a direct child of the project page, so the runtime falls back to targeted mode.
+
+**Fix**: Pass `--checklist-page-id <CHECKLIST_PAGE_ID>` explicitly to restore full canonical evaluation.
+
+For Payment department projects, the verified working command is:
+
+```bash
+./scripts/worktree_uv.sh run --project audit_orchestrator \
+  vds-cli audit workflow <repo-cache-root>/<PROJECT-KEY>-project/<repo> \
+  --project-storage-key <PSK> \
+  --checklist-page-id 88722450 \
+  --thread-id <thread_id>
+```
+
+Confirmed bootstrap signal: `canonical_checklist_bootstrap_preflight_passed: source=explicit_page_id`
+
+For `workflow-project` (project scope):
+
+```bash
+vds-cli audit workflow-project \
+  --project-storage-key <PSK> \
+  --thread-id <thread_id> \
+  --checklist-page-id 88722450
+```
+
+For one full prepared repo under project semantics, prefer `--scope-id` from `parse-repo` and omit `--profiles`:
+
+```bash
+./scripts/run-audit-in-tmux.sh <session-name> \
+  workflow-project \
+  --project-storage-key <PSK> \
+  --scope-id <SCOPE_ID_FROM_PARSE_REPO> \
+  --checklist-page-id 88722450 \
+  --max-concurrent 6 \
+  --upload-to-confluence \
+  --incremental-upload \
+  --new-run
+```
+
+Interpretation rules:
+- Prefer `--scope-id` for deterministic DB-native one-repo narrowing on the current merged mainline baseline.
+- Existing `--seed-payload` JSON remains a compatibility path only and emits deprecation warnings.
+- Omitting `--profiles` means "use all currently available profiles after active preflight".
+- `--max-concurrent` caps simultaneously active child lanes only. The total participating profile count may be larger over the full run.
+- Use tmux for this path; parent `workflow-project` must stay alive while child profile lanes run.
+- Phase 156 publication hardening re-parents reused Confluence pages automatically, skips cross-project page-id collisions during registry backfill, and strips `--incremental-upload` when upload is disabled by offline mode.
+- Treat the full Phase 159 work-stealing scope as planned until the new flags appear in live help on mainline.
+
+For `workflow-projects` (multi-project):
+
+```bash
+vds-cli audit workflow-projects \
+  --project-storage-keys <PSK1,PSK2,...> \
+  --checklist-page-id 88722450 \
+  --prepare-materials \
+  --max-projects-concurrent 2 \
+  --max-concurrent 4
+```
+
+**Page ID facts**:
+- `88722450` — standard backend checklist page; correct for Payment department. Use this one.
+- `88716673` — Payment-specific page with `checklist_topology_report=null`; do NOT use as explicit checklist page; causes topology parse failure and 0/56 rows.
+- `88716694` — Payment department parent page; use with `parse-registry --registry-page` to discover child projects.
+
+**Diagnosis steps**:
+1. Check workflow log for `checklist_discovery_failed` or `canonical_checklist=False`.
+2. Confirm the project page ID is correct (not the department page).
+3. Run `vds-cli audit doctor check-confluence --json` to confirm which Confluence endpoints are reachable before assuming a checklist bootstrap problem.
+4. Use `query-checklist --checklist-page 88722450 --summary-only` to verify the source checklist page is reachable and parsable before rerunning workflow.
+5. If direct CQL search looks suspicious, run `vds-cli confluence-cli search -s internal -q 'type=page' --limit 2 --json` to verify the internal server path preserves `start=0` correctly.
+6. If checklist reads need the older external scope intentionally, set `VDS_AUDIT_CHECKLIST_READ_SERVER=external` explicitly before rerunning.
+7. Re-run with `--checklist-page-id 88722450` and verify bootstrap signal shows `source=explicit_page_id`.
+8. If publication is enabled, `--confluence-parent` is auto-resolved from department hierarchy (FR-150) — omit it in normal runs. If publication created pages in the wrong location, use DB-backed publish state plus parent workflow logs first; inspect `dispatch-manifest.json` only as a debug artifact when needed for historical run context.
+9. When investigating a known prior run, prefer explicit resume-specific-run or publish-from-run-root surfaces over implicit auto-resume.
+
+**Live log note**:
+- Realtime JSONL logs are baseline behavior.
+- When triaging with `--target`, root `--verbose`, `--trace`, `--debug-evidence-context`, or `--debug-batch-timing`, the workflow runtime now auto-enables richer live agent event logging for the lane and its child runs.
+- Since Phase 155, `--debug-evidence-context`, `--debug-batch-timing`, and `--trace` are accepted on `workflow-project` and forwarded to child `workflow` lanes. They are still not accepted directly on `workflow-projects`.
+- `--verbose` is a root-level flag: use `vds-cli audit --verbose workflow ...`, not `vds-cli audit workflow ... --verbose`.
+- Expect full payload traces only for `--trace`, `--debug-evidence-context`, or `--debug-batch-timing`; targeted-only reruns keep the lighter live stream.
+
+## Resilience Troubleshooting
+
+### Symptom: all profiles circuit-tripped after a run with timeouts
+
+**Root cause (pre-fix)**: `_classify_provider_failure` in `workflow_cmds.py` previously checked auth keywords before transient keywords. Timeout responses that contained an auth-adjacent substring were misclassified as auth failures, permanently tripping the circuit breaker.
+
+**Fix**: transient keywords are now checked first; timeout handler always classifies as `transient`. Timeouts can no longer permanently trip the circuit breaker.
+
+**If still occurring**: check whether the provider actually returned an auth error (401/403) vs a timeout. Run `vds-cli audit --json-only doctor profile-availability --mode active` to inspect current provider health state.
+
+### Symptom: state manifest load timeouts when running concurrent workflows
+
+**Root cause**: default `VDS_AUDIT_STATE_API_TIMEOUT_SECONDS` is 15 s, which is insufficient when multiple child workflows load the manifest simultaneously.
+
+**Fix**: add `VDS_AUDIT_STATE_API_TIMEOUT_SECONDS=120` to `~/.vds/.env` and restart the workflow.
+
+## Sources
+
+- [Monorepo baseline](../../../../AGENTS.md)
+- [Audit orchestrator guide](../../../audit_orchestrator/README.md)
+- [Scripts workspace guide](../../README.md)