devops-whc 1.0.1 → 1.0.2-next

package/{AGENT_MCP_USAGE.md → AGENT_USAGE.md}

@@ -1,10 +1,10 @@
-# WHC MCP Agent Usage Guide
+# WHC CLI Agent Usage Guide
 
-This guide is for AI agents and operators who need predictable, safe usage of the WHC MCP server.
+This guide is for AI agents and operators who need predictable, safe usage of the WHC tool server.
 
 ## 1. Goal
 
-Use WHC MCP to run a safe release flow:
+Use WHC CLI to run a safe release flow:
 
 1. Initialize workspace state (`whc_prepare`).
 2. Validate connectivity and environment.
@@ -14,17 +14,16 @@ Use WHC MCP to run a safe release flow:
 
 ## 2. Runtime Model
 
-The server supports two workflow modes:
+The server supports two workflow modes:
+
+1. `git_deploy`
+2. `ssh_scp_wpcli`
+
+`git_deploy` means local source is pushed to a cPanel-managed Git repository and deployment is triggered from that repository.
+`ssh_scp_wpcli` means source-first delivery over SSH/SCP with runtime bootstrap via WP-CLI and smoke gating.
+If `WHC_WORKFLOW_MODE` is omitted, default to `ssh_scp_wpcli`.
 
-1. `managed_clone_sync`
-2. `git_controlled`
-
-Most WHC managed WordPress flows use `managed_clone_sync`.
-
-If server env sets `WHC_WORKFLOW_MODE=managed_clone_sync`, treat staging as managed-only.
-Do not call `git_controlled` for staging in that mode.
-
-## 2.2 MCP Registration Standard
+## 2.2 Tool Server Registration Standard
 
 Use one of these two registration patterns and keep them consistent with README.
 
@@ -33,36 +32,36 @@ Published package (`npx`) recommended for most users:
 ```jsonc
 {
   "servers": {
-    "whc-mcp": {
+    "whc": {
       "type": "stdio",
       "command": "npx",
       "args": ["-y", "devops-whc", "--serve"],
       "env": {
         "WHC_ENV_FILE": "${workspaceFolder}/.env",
         "WHC_LOCAL_PROJECT_ROOT": "${workspaceFolder}",
-        "WHC_STATE_ROOT": ".mcp/whc-mcp",
-        "WHC_MCP_INSTANCE_NAME": "whc-mcp"
+        "WHC_STATE_ROOT": ".whc",
+        "WHC_INSTANCE_NAME": "whc"
       }
     }
   }
 }
 ```
 
-Local clone (`start-mcp.cjs`) for contributors:
+Local clone (`start-whc.cjs`) for contributors:
 
 ```jsonc
 {
   "servers": {
-    "whc-mcp": {
+    "whc": {
       "type": "stdio",
       "command": "node",
-      "args": ["./scripts/start-mcp.cjs"],
+      "args": ["./scripts/start-whc.cjs"],
       "cwd": "${workspaceFolder}",
       "env": {
         "WHC_ENV_FILE": "${workspaceFolder}/.env",
         "WHC_LOCAL_PROJECT_ROOT": "${workspaceFolder}",
-        "WHC_STATE_ROOT": ".mcp/whc-mcp",
-        "WHC_MCP_INSTANCE_NAME": "whc-mcp"
+        "WHC_STATE_ROOT": ".whc",
+        "WHC_INSTANCE_NAME": "whc"
       }
     }
   }
@@ -85,10 +84,12 @@ Release commands:
 
 ```powershell
 npm run pack:check
-npm --prefix packages/devops-whc publish
+npm run publish:npm
 ```
 
 `npm run pack:check` will run publish preparation and package dry-run against the subpackage.
+`npm run publish:npm` runs `npm publish` from the publish subpackage.
+For prerelease versions, `npm run publish:npm` automatically adds `--tag next` unless an explicit tag is provided.
 
 ## 2.1 Why `whc_setup_remote` Exists
 
@@ -98,7 +99,14 @@ It only prepares the remote Git endpoint on cPanel (repository root + SSH hint)
 
 Think of it as wiring transport, not shipping release.
 
-After `whc_setup_remote`, a manual or automated `git push` from local source is still required, then `whc_deploy` triggers deployment tasks.
+After `whc_setup_remote`, a manual or automated `git push` from local source is still required.
+
+Current boundary:
+
+1. `whc_setup_remote` is ready for remote Git repository setup.
+2. `check:generic` is the main trustworthy readiness gate for both workflow modes.
+3. `whc_deploy` for `git_deploy` triggers the real cPanel deployment task for a given `repository_root` and optional `branch`.
+4. `whc_deploy` does not yet execute the full `ssh_scp_wpcli` runtime pipeline; keep that in project-local scripts for now.
 
 ## 3. Required Context Before Any Write
 
@@ -106,15 +114,9 @@ Always collect these first:
 
 1. Active workflow mode.
 2. Target environment (`staging` or `live`).
-3. Direction (for managed clone/sync):
-   - `live_to_staging`
-   - `staging_to_live`
-4. Sync scope:
-   - `files`
-   - `database`
-   - `everything`
-5. Whether `dry_run` and `confirmed` are required by policy.
-6. For `git_controlled`, ensure `repository_root` belongs to current `WHC_USER` home path (`/home/<WHC_USER>/...`).
+3. For `git_deploy`, identify the remote repository root and branch that should be deployed.
+4. For `ssh_scp_wpcli`, identify the local app root, staging SSH target, and runtime bootstrap path.
+5. Whether `dry_run` and `confirmed` are required by policy.
 
 ## 3.1 Manual vs Agent Responsibilities
 
@@ -123,32 +125,42 @@ User/operator must do manually (once per environment):
 2. Add SSH public key to correct cPanel account.
 3. Confirm host/path ownership and account scope.
 
-Agent can automate repeatedly:
-1. Validate context and run dry-run checks.
-2. Create/list repository via `whc_setup_remote`.
-3. Trigger deployment via `whc_deploy`.
-4. Execute safe runtime probes and logs/health collection.
+Agent can automate repeatedly:
+1. Validate context and run dry-run checks.
+2. Create/list repository via `whc_setup_remote`.
+3. Push local source to the cPanel-managed Git repository when credentials are available.
+4. Trigger deployment via `whc_deploy` for the intended `repository_root` and optional `branch`.
+5. Execute safe runtime probes and logs/health collection.
+6. Run source-compatibility checks and hidden-state bootstrap for a specific project root.
 
 Hybrid step:
 1. `git push` may be run by agent from local terminal when keys/permissions are ready; otherwise operator performs push manually.
 
 ## 4. Safety Rules
 
-1. Never promote live directly without staging verification.
-2. For `staging_to_live` with `database` or `everything`, provide backup reference unless emergency override is explicitly approved.
-3. Prefer `dry_run=true` before state-changing requests.
-4. Always set `confirmed=true` when the policy requires explicit confirmation.
+1. Never claim a deploy was executed unless the handler actually changed remote state.
+2. Never promote live directly without staging verification.
+3. Prefer `dry_run=true` before state-changing requests.
+4. Always set `confirmed=true` when the policy requires explicit confirmation.
 
 ## 5. Tool Order (Recommended)
 
 1. `whc_prepare` to initialize hidden state and readiness checks.
 2. `whc_check_health` for target status and capability baseline.
 3. `whc_get_logs` for pre-deploy signal.
-4. `whc_deploy` with `dry_run=true`.
-5. `whc_deploy` real execution after dry-run passes.
-6. `whc_verify` to produce technical verify report.
-7. Run smoke checks outside or via allowed tool path.
-8. If staging passes, run promote flow for live with explicit direction and backup policy.
+4. For `git_deploy`, run remote repository setup and local `git push`.
+5. For `ssh_scp_wpcli`, run the project-local doctor/SCP/WP-CLI pipeline.
+6. `whc_verify` to produce technical verify report.
+7. Run smoke checks outside or via allowed tool path.
+8. If staging passes, decide whether live release should proceed.
+
+For `ssh_scp_wpcli` projects, replace steps 4-7 with the project-local source pipeline:
+1. doctor
+2. backup
+3. SCP code sync
+4. WP-CLI runtime bootstrap
+5. seed/bootstrap
+6. smoke gate
 
 ## 6.4 Rollback (Level D) Contract
 
@@ -175,74 +187,34 @@ Example rollback preview payload:
 }
 ```
 
-## 6. Canonical Payloads
-
-### 6.1 Staging dry-run (managed clone/sync refresh)
-
-```json
-{
-  "dry_run": true,
-  "confirmed": true,
-  "payload": {
-    "workflow_mode": "managed_clone_sync",
-    "target_environment": "staging",
-    "release_intent": "refresh",
-    "pipeline_id": "P3D",
-    "source_profile": {
-      "source_kind": "full_site",
-      "deploy_unit": "raw_source"
-    },
-    "direction": "live_to_staging",
-    "sync_scope": "files",
-    "verify_after_deploy": true,
-    "auto_rollback_on_verify_failure": false
-  }
-}
-```
-
-### 6.2 Staging real refresh sync (managed clone/sync)
-
-```json
-{
-  "confirmed": true,
-  "payload": {
-    "workflow_mode": "managed_clone_sync",
-    "target_environment": "staging",
-    "release_intent": "refresh",
-    "pipeline_id": "P3D",
-    "source_profile": {
-      "source_kind": "full_site",
-      "deploy_unit": "raw_source"
-    },
-    "direction": "live_to_staging",
-    "sync_scope": "files",
-    "verify_after_deploy": true,
-    "auto_rollback_on_verify_failure": false
-  }
-}
-```
-
-### 6.3 Live promote (higher risk)
-
-```json
-{
-  "confirmed": true,
-  "payload": {
-    "workflow_mode": "managed_clone_sync",
-    "target_environment": "live",
-    "release_intent": "promote",
-    "pipeline_id": "P3D",
-    "source_profile": {
-      "source_kind": "full_site",
-      "deploy_unit": "raw_source"
-    },
-    "direction": "staging_to_live",
-    "sync_scope": "files",
-    "verify_after_deploy": true,
-    "auto_rollback_on_verify_failure": true
-  }
-}
-```
+## 6. Canonical Usage Patterns
+
+### 6.1 `git_deploy`
+
+Use this mode when the real delivery path is:
+
+1. local Git repository
+2. push to cPanel-managed repository
+3. cPanel deployment task runs `.cpanel.yml`
+
+Agent expectations today:
+
+1. validate readiness with `check:generic`
+2. ensure remote repo exists with `whc_setup_remote`
+3. push with local Git
+4. trigger the cPanel deployment task with `whc_deploy`
+5. do not overstate this as WordPress runtime bootstrap; that still belongs to separate checks/scripts
+
+### 6.2 `ssh_scp_wpcli`
+
+Use this mode for `mytho/source` style delivery:
+
+1. doctor
+2. backup
+3. SCP code sync
+4. WP-CLI bootstrap
+5. seed/bootstrap
+6. smoke gate
 
 ## 7. Smoke Gate Expectations
 
@@ -259,19 +231,24 @@ If preconditions fail (plugin/page/routes absent), gate must be `HOLD`.
 
 ## 7.1 Pipeline Mindset Guard
 
-Treat these as two different operations:
-
-1. Environment refresh:
-  - `workflow_mode=managed_clone_sync`
-  - `direction=live_to_staging`
-  - `release_intent=refresh`
-2. Release deploy to staging:
-  - Use release candidate source (typically `git_controlled`), not live mirror sync.
-  - Use `repository_root` under `/home/<WHC_USER>/...`; cross-account paths are blocked by policy.
-
-Policy note:
-
-1. `managed_clone_sync + live_to_staging + release_intent=deploy` is blocked by policy because it causes release-testing ambiguity.
+Treat these as two different foundations:
+
+1. `git_deploy`
+   - repository-driven
+   - local `git push`
+   - cPanel deployment task
+   - `.cpanel.yml` at repo root
+2. `ssh_scp_wpcli`
+   - source-driven
+   - SCP file transfer
+   - remote WP-CLI runtime/bootstrap
+   - project-specific smoke gate
+
+Policy note:
+
+1. `ssh_scp_wpcli` is the correct default mindset for `mytho/source`.
+2. `git_deploy` should not be described as staging/live native sync.
+3. If a release note or operator guide mentions `managed_clone_sync`, treat that as stale wording and replace it.
 
 ## 8. Troubleshooting
 
@@ -284,15 +261,16 @@ Symptom:
 Checks:
 
 1. Confirm `WHC_ENV_FILE` points to the intended env file.
-2. Confirm the MCP process has reloaded after env edits.
+2. Confirm The tool server process has reloaded after env edits.
 3. Avoid malformed quoting in key path values.
 
-### 8.2 Deploy validation errors in managed mode
-
-If request fails with missing direction, ensure payload includes:
-
-1. `direction`
-2. `sync_scope`
+### 8.2 Deploy contract confusion
+
+If users are mixing repository deploy with environment-sync wording:
+
+1. for `git_deploy`, think `repository_root`, `branch`, `.cpanel.yml`, and cPanel deployment task
+2. for `ssh_scp_wpcli`, think WordPress app root, `scp`, `wp`, and smoke checks
+3. do not describe either mode as native WHC staging/live clone sync
 
 ## 9. One-Line Operator Playbook
 
@@ -302,13 +280,13 @@ If request fails with missing direction, ensure payload includes:
 
 ### 10.1 Log path
 
-1. Default path: `.mcp/whc-mcp/logs/flow-events.jsonl`
+1. Default path: `.whc/logs/flow-events.jsonl`
 2. Custom path (optional): set `WHC_FLOW_LOG_PATH` in env
 
 ### 10.2 Read latest entries (PowerShell)
 
 ```powershell
-Get-Content .mcp/whc-mcp/logs/flow-events.jsonl -Tail 20
+Get-Content .whc/logs/flow-events.jsonl -Tail 20
 ```
 
 If custom path is configured:
@@ -320,7 +298,7 @@ Get-Content $env:WHC_FLOW_LOG_PATH -Tail 20
 Filter only deploy events:
 
 ```powershell
-Get-Content .mcp/whc-mcp/logs/flow-events.jsonl -Tail 200 |
+Get-Content .whc/logs/flow-events.jsonl -Tail 200 |
   ForEach-Object { $_ | ConvertFrom-Json } |
   Where-Object { $_.tool -eq 'whc_deploy' } |
   Select-Object -Last 10
@@ -343,7 +321,7 @@ Minimal response snippet:
 
 ```text
 Flow log:
-- path: .mcp/whc-mcp/logs/flow-events.jsonl
+- path: .whc/logs/flow-events.jsonl
 - action_id: <value>
 - tool: whc_deploy
 - status: success|failure
@@ -358,24 +336,24 @@ Flow log:
 For local clone workflows, run once per workspace:
 
 ```powershell
-npm run mcp:prepare
+npm run prepare
 ```
 
-For npm-package workflows, call `whc_prepare` once from the MCP client after the server starts.
+For npm-package workflows, call `whc_prepare` once from The tool server client after the server starts.
 
 This initializes hidden management paths automatically:
-1. `.mcp/whc-mcp/state/pipeline-status.json`
-2. `.mcp/whc-mcp/state/releases/`
-3. `.mcp/whc-mcp/state/reports/`
-4. `.mcp/whc-mcp/logs/`
+1. `.whc/state/pipeline-status.json`
+2. `.whc/state/releases/`
+3. `.whc/state/reports/`
+4. `.whc/logs/`
 
-It also ensures `.mcp/` is ignored by git.
+It also ensures `.whc/` is ignored by git.
 
 ## 10.5 Automatic State Tracking
 
-For every write tool run, MCP now auto-updates:
-1. `.mcp/whc-mcp/state/pipeline-status.json` (started/completed/status/next step/error)
-2. `.mcp/whc-mcp/state/releases/<request_id>.auto-manifest.json` (tool metadata + git changed files snapshot)
+For every write tool run, tool server now auto-updates:
+1. `.whc/state/pipeline-status.json` (started/completed/status/next step/error)
+2. `.whc/state/releases/<request_id>.auto-manifest.json` (tool metadata + git changed files snapshot)
 
 No manual template authoring is required for normal DevOps runs.
 
@@ -392,3 +370,6 @@ For `whc_deploy` and `whc_setup_remote`, read these response fields first:
 Decision rule:
 1. If `pipeline_status=pass_partial`, do not claim end-to-end release completion.
 2. Follow `next_step` and unresolved `manual_actions` before moving to next gate.
+
+
+