feat: optional gcloud-doctor for Windows, macOS and Linux

.github/workflows/gcloud-doctor.yml

@@ -0,0 +1,52 @@
+name: gcloud-doctor
+
+on:
+  push:
+    branches: [master, 'feat/gcloud-doctor-cross-platform']
+    paths:
+      - 'plugin/skills/gcloud-doctor/**'
+      - 'skills/gcloud-doctor.md'
+      - 'skills.json'
+      - 'package.json'
+      - 'tests/gcloud-doctor.test.mjs'
+      - '.github/workflows/gcloud-doctor.yml'
+  pull_request:
+    paths:
+      - 'plugin/skills/gcloud-doctor/**'
+      - 'skills/gcloud-doctor.md'
+      - 'skills.json'
+      - 'package.json'
+      - 'tests/gcloud-doctor.test.mjs'
+      - '.github/workflows/gcloud-doctor.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: gcloud-doctor-${{ github.workflow }}-${{ github.event_name }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    name: ${{ matrix.os }} / Node ${{ matrix.node }}
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 10
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        node: ['22.18.0', '24.x']
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262
+        with:
+          persist-credentials: false
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020
+        with:
+          node-version: ${{ matrix.node }}
+      - name: Syntax and SDK-free help
+        run: |
+          node --check plugin/skills/gcloud-doctor/scripts/doctor.mjs
+          node plugin/skills/gcloud-doctor/scripts/doctor.mjs --help
+      - name: Fixture-based diagnostic and integration tests
+        run: npm run test:gcloud-doctor

README.md

@@ -60,9 +60,28 @@ Opens **http://localhost:4599** → add a project folder → **▶ Run Codex**.
 Windows shortcuts: `start.cmd` / `install-shortcut.cmd`.  
 macOS: `start.command` / `install-shortcut.command`.
 
+### Optional Google Cloud environment checks
+
+`$gcloud-doctor` adds local Google Cloud diagnostics on **Windows, macOS and Linux**.
+It checks the actual SDK version, PATH ambiguity, Python, project configuration,
+and separate CLI/ADC evidence. It does not make Google Cloud a GitMir dependency
+and does not run at startup. No login, update, registry edit, deployment or billing
+operation is performed by the diagnostic CLI.
+
+```text
+npm run doctor:gcloud
+npm run doctor:gcloud -- --json
+npm run test:gcloud-doctor
+```
+
+[Full guide, platform-specific maintenance and verification limits](plugin/skills/gcloud-doctor/references/maintenance.md).
+The skill and all runtime assets are inside `plugin/skills/gcloud-doctor`, so they
+also work with the standalone installed plugin. Tests use a fake SDK; a passing
+local report is not proof of cloud API access, IAM permissions or valid tokens.
+
 ### Windows maintenance recipes
 
-[Google Cloud SDK: update to 584.0.0 and repair WinGet `Unknown`](docs/windows/gcloud-winget-version-repair/README.md) — PowerShell script, one-line command, troubleshooting, registry rollback guidance, and validation criteria. The guide is in Russian and records the Windows end-to-end validation status. This is an optional manual procedure, not a GitMir dependency or startup action.
+[Google Cloud SDK: update to 584.0.0 and repair WinGet `Unknown`](docs/windows/gcloud-winget-version-repair/README.md) — PowerShell script, one-line command, troubleshooting, registry rollback guidance, and validation criteria. The guide is in Russian and records the Windows end-to-end validation status. This is an optional manual procedure, not a GitMir dependency or startup action. It is a historical fixed-version case, not the cross-platform doctor's update policy.
 
 ---
 
@@ -81,6 +100,7 @@ macOS: `start.command` / `install-shortcut.command`.
 | `$context-distillation` | Messy input → `.gitmir/brief.json` |
 | `$legacy-maintenance` | Safe changes on coupled systems |
 | `$stack-port` | Port old stack → new without losing behaviour |
+| `$gcloud-doctor` | Optional Windows/macOS/Linux Google Cloud environment diagnostics; explicitly authorized maintenance only |
 
 Flat copies under `skills/` are for the dashboard UI (copy-paste). Canonical Codex layout is `plugin/skills/<name>/SKILL.md`.
 

package.json

@@ -14,7 +14,9 @@
   },
   "scripts": {
     "start": "node server.ts",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "doctor:gcloud": "node plugin/skills/gcloud-doctor/scripts/doctor.mjs",
+    "test:gcloud-doctor": "node --test tests/gcloud-doctor.test.mjs"
   },
   "devDependencies": {
     "@types/node": "^26.1.2",

plugin/skills/gcloud-doctor/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: gcloud-doctor
+description: >-
+  Use when a Google Cloud project has gcloud, Python, PATH, CLI login, ADC,
+  configuration or WinGet version problems, or the user explicitly requests a
+  Google Cloud environment check on Windows, macOS or Linux.
+---
+
+# Google Cloud environment doctor
+
+Optional local diagnostics for Google Cloud projects. Never make Google Cloud a
+GitMir prerequisite. Do not run this skill at dashboard startup or for unrelated
+projects. Diagnostic permission is not repair, authentication or deployment permission.
+
+## Run the bundled diagnostic
+
+Locate this skill's installed directory containing `SKILL.md`, `scripts/doctor.mjs`
+and `references/maintenance.md`. In a GitMir checkout the directory is
+`plugin/skills/gcloud-doctor`. A dashboard flat copy under `skills/` is not the
+script's directory. Resolve the absolute script path from the installed skill or
+GitMir checkout, not by guessing relative to the user's project.
+
+Run Node.js 22.18 or later against that script, with the user's project as working
+directory. The script has no npm dependencies. From the GitMir checkout:
+
+```text
+node plugin/skills/gcloud-doctor/scripts/doctor.mjs
+node plugin/skills/gcloud-doctor/scripts/doctor.mjs --json
+```
+
+Use `--project` only when the expected project is supplied or established from the
+project's non-secret configuration. It compares configuration; it does not change
+or remotely verify a project. `--min-version` accepts a numeric X.Y.Z minimum,
+not "latest". There is no hardcoded Google Cloud release and no pin operation.
+
+Use `--require-local-adc` only for a workflow that specifically requires a local
+ADC file, not workloads using an attached service account. `--strict` makes
+warnings fail CI. `--gcloud` selects an explicitly identified absolute executable
+path when several installations exist. Read `--help` for the full interface.
+
+## Interpret evidence, not wishful success
+
+The JSON schema is versioned (`schemaVersion: 1`). Checks have stable IDs, a
+`pass`, `warn`, `fail` or `skip` status, a summary and allowlisted details.
+Exit 0 means no failing local checks; warnings may remain. Exit 1 means failures
+or strict-mode warnings. Exit 2 means invalid arguments or an internal error.
+
+Always distinguish:
+
+- Actual SDK version versus the available version displayed by a package manager.
+- A stored active CLI credential entry versus a successful authentication/API call.
+- CLI credentials versus Application Default Credentials used by client libraries.
+- A readable ADC candidate versus valid credentials, scopes, IAM or quota.
+- The current Node/OS architecture versus native architecture of every SDK component.
+
+`cloudAccess` is always `not-tested`. Missing local ADC does not prove workload
+identity or metadata-server credentials are broken. `CLOUDSDK_CONFIG` can alter
+CLI credential storage; application libraries do not all resolve overrides the
+same way. Verify the actual application separately. Do not request or print tokens,
+credential JSON, account email addresses, environment dumps or raw gcloud logs.
+Project IDs, configuration names and non-home paths remain operational metadata;
+review/redact before publishing a report.
+
+## Repairs and GitMir task integration
+
+Read [maintenance.md](references/maintenance.md) before proposing any change.
+Identify the installation owner and the exact installation first. Windows is not
+a synonym for WinGet, macOS is not a synonym for Homebrew, and Linux is not a
+synonym for APT. Never mix package-manager and SDK self-updates blindly.
+
+The CLI intentionally has no `--fix`, login, deploy, update or registry-write
+mode. With explicit user authorization, perform only the selected maintenance
+procedure from the runbook, preserve the prior state, and rerun the diagnostic.
+Registry repair on Windows is a separate metadata operation, not a cloud update
+or version pin. The old 584.0.0 recipe is historical, not a universal updater.
+
+When the user requests queued work, create the next unused `tasks/todo/NNN-*.md`
+in the managed project using the existing `task-planner` shape: `Type: fix`,
+`## Context`, `## Task`, `## Verify`. Include the failed check ID, sanitized
+reproduction, expected result, exact authorized scope and rollback. For cloud or
+machine mutations not yet authorized, create a `Type: verify` task that diagnoses
+only; state the repair is blocked, rather than queueing an autonomous mutation.
+Do not mark a task done until its actual verification has passed. Never auto-push
+reports or change GitMir server routes, cloud resources, IAM, billing or auth.