feat: add deterministic read-only runtime doctor

docs/development/testing.mdx

@@ -136,6 +136,10 @@ The reproducible `metrics:architecture` collector is the full evidence
 workflow; it requires a clean working tree and writes reports outside the
 repository.
 
+Architecture fixtures that resolve TypeScript symbols should share one compiler
+program containing production sources and isolated fixture modules. Retain the
+real bindings and every assertion; rebuilding the whole project for each fixture
+can exhaust a Jest worker during full platform verification.
 The raw-error boundary suite shares one real TypeScript compiler graph across
 the repository scan and its six fixture modules. It keeps all seven assertions
 and checks the real logger/sanitizer declarations. This reduces repeated

docs/issues/comment-commands.mdx

@@ -45,6 +45,7 @@ Commands are recognized at the beginning of a comment, case-insensitively. The c
 | `/copilot findings` | Reconcile and publish current findings. | No |
 | `/copilot recheck` | Re-run the review against the current branch. | No |
 | `/copilot status` | Show the current Copilot status. | No |
+| `/copilot doctor` | Check runtime prerequisites using bounded read-only evidence. | No |
 | `/copilot description` | Refresh the PR description when that action is configured. | No |
 | `/copilot fix <finding-id> [finding-id ...]` | Fix one or more existing Bugbot findings. | Yes, if authorized |
 | `/copilot dismiss <finding-id> [finding-id ...]` | Dismiss one or more findings. | No file changes |
@@ -60,7 +61,7 @@ whitespace-separated, and commands are limited to 2,000 characters and 20
 arguments. Missing or malformed required arguments produce a validation reply;
 they never mean “all” or authorize a broad change.
 
-`help`, `status`, `dismiss`, `remember` and rejected commands do not run a
+`help`, `status`, `doctor`, `dismiss`, `remember` and rejected commands do not run a
 model or change the temporary agent activity label. `sync-branch --dry-run`
 and `--no-agent` also avoid model activity. Ordinary sync may use the conflict
 fixer, and `findings` runs a fresh review. These distinctions preserve each
@@ -113,7 +114,6 @@ You can combine plain and quoted IDs. Use JSON escapes for a literal double
 quote or backslash; malformed, empty or multiline quoted IDs are rejected.
 The command still accepts at most 20 IDs and 2,000 characters.
 
-
 `/copilot status` reports lifecycle, waiting state, branch, labels, and the
 canonical Bugbot counts: open, reopened, verification-required, unknown, and
 resolved. In a PR conversation, it reads one trusted complete Bugbot status
@@ -125,6 +125,47 @@ separate from an issue with the same number. Status and description queries
 preserve existing lifecycle and waiting labels when they make no lifecycle
 decision.
 
+`/copilot doctor` reads seven bounded groups: effective workflow and dependency
+settings, eligible issue/SDD prerequisites, the issue's native linked branch,
+installed workflow structure, the trusted approval policy, declared approval
+prerequisites, and the exact current PR identity. It has no arguments and
+never invokes a model or repairs the repository. Participants can request this
+metadata report even when model automation is restricted to organization members.
+
+Its structural workflow check requires issue `labeled`, issue-comment `created`,
+and pull-request `opened` entry activities when an explicit `types` filter is
+present. A valid but irrelevant filter such as issue-comment `deleted` is
+blocked. Unknown dynamic job conditions remain unavailable; this does not prove
+a workflow is disabled, and retrying alone cannot certify those conditions.
+
+The reply distinguishes **pass**, **warning**, **blocked**, **unavailable**, and
+**not applicable**. A successfully read invalid policy is blocked; a denied or
+failed read is unavailable. Completed independent checks remain visible. Only
+verified absence of both repository and organization policy values selects the
+existing off default. Active approval settings are declared prerequisites,
+which need independent producer verification and do not certify write access.
+
+Workflow files and specification prerequisites are read at one verified immutable
+default-branch revision, linked in the report. A moved default head makes that
+sample unavailable. Native linked branches require complete same-repository
+association and a matching live ref. A null or missing linked ref remains
+unavailable; only a complete empty page proves that no branch is linked.
+Specification prerequisites require canonical catalog metadata and evidence
+arrays, supported status/date values, unique ownership and regular referenced
+files in the same complete immutable tree (at most 10,000 entries). Doctor keeps
+six bounded content reads; full as-built document contents and uncatalogued
+specification discovery remain CI checks. Denied or incomplete tree evidence is
+unavailable. Effective dependency, default and linked branches must be valid
+bounded literal Git branch names, including every path component. A PR request checks only its exact event
+PR and fences its current head; optional issue context is not inferred from
+an equal conversation number. Reports use the repository locale in English or
+Spanish with atomic fallback and one correlated reply per source comment.
+
+Inspect the displayed primary action and the workflow run, correct any proven
+invalid configuration through the usual maintainer flow, then retry
+`/copilot doctor`. The command does not read secret values, test write access,
+provision setup, change labels or approvals, or infer grants from workflow text.
+
 For issue types covered by `pre-branch-sdd`, status also appends an SDD
 readiness section. It reports when an SDD is not required and marks required
 SDD evidence unavailable until the reader verifies the current owned card,
@@ -306,6 +347,17 @@ correlated replies; the welcome text embeds no separate marker.
 
 See [Bugbot detection](/bugbot/detection), [Autofix](/bugbot/autofix), and [Do user request](/bugbot/do-user-request) for the execution details.
 
+The runtime doctor distinguishes proven missing files from inaccessible evidence.
+A contents API 404 needs an independent complete tree at the same verified
+commit before it can be reported as missing. Denied or incomplete tree reads
+remain unavailable. The proof adds at most two shared read requests and never
+changes repository files or permissions.
+
+The doctor workflow group checks that Copilot is in an eligible job and step for
+the required event. Disabled jobs or steps cannot make it pass. Runtime-dependent
+or unsupported conditions are reported as unavailable because a repository
+snapshot cannot establish their result. Inspect those conditions and the actual
+workflow run; a structural pass still does not prove runner availability.
 ### Recent operation history
 
 `/copilot history` shows at most ten supported requests in this issue or PR's
@@ -340,10 +392,27 @@ SDD status keeps an unknown requirement visible when the issue has no admitted
 workflow kind. Evidence links use the configured GitHub server origin and the
 same issue identity; an untrusted or mismatched URL is shown without navigation.
 
+Doctor treats a valid native issue with no description as an empty body, so
+independent checks can still complete. Unknown evidence groups are rejected;
+installed workflow activity filters must contain a non-empty array of text
+values. A malformed filter is blocked rather than reported as a valid trigger.
+
+Doctor's bounded workflow interpreter leaves mixed-type comparisons unavailable
+rather than applying JavaScript equality to GitHub expressions. Inspect the
+actual condition when that prerequisite is unavailable; the report does not
+execute the expression or infer that the job is disabled.
 When the detected request language and writing script already match the target,
 Copilot keeps the original wording and omits a redundant translation disclosure.
 Mixed-language requests and different writing scripts can still be translated.
 
+Doctor verifies that every inspected configuration/workflow path is a regular file in the same immutable Git tree. Contents returned through a symlink do not establish valid installed prerequisites.
+
+
+Doctor checks whether an Action job has usable structural scheduling evidence.
+A static empty matrix blocks that job. Dynamic matrices and include/exclude
+transformations are reported as unavailable because doctor does not simulate
+the workflow. Ordinary nonmatrix and supported static jobs remain eligible;
+this check does not certify a runner or real tool execution.
 History requests are deterministic on issue comments and PR review comments.
 Their activity-admission policy neither inspects agent role availability nor activates the temporary agent
 activity label; unavailable model configuration does not turn a history read
@@ -412,3 +481,30 @@ help answers from non-comment events retain their ordinary immutable reply.
 that exact PR, even when its linked issue has a different number. The query uses
 the PR locale and does not infer an issue from the PR number. Review threads
 continue to direct you to the main conversation; arguments are not accepted.
+
+Doctor treats a unique enabled help issue as branchless: incomplete help-form
+headings do not create a branch or SDD requirement. Disabled workflow kinds and
+conflicting kind labels still show their admission block. For simple literal
+workflow matrices, Doctor checks the product against GitHub's 256-job matrix
+limit; it does not expand or execute jobs. Dynamic axes and include/exclude
+transformations remain unavailable rather than receiving a guessed Pass.
+
+Doctor keeps an explicitly absent approval policy separate from a present empty
+value: verified absence retains the off default, while a present empty or
+whitespace value is invalid. A malformed provider value is unavailable. SDD
+catalog prerequisites require every tracked product specification, including
+nested Markdown files, to have a catalog owner; the three top-level standard
+documents are excluded. Independent successful checks remain visible when a
+policy or specification check is blocked.
+
+A workflow Action job cannot receive Pass when a directly required job is
+statically skipped. Other `needs` requirements remain unavailable when runtime
+success, dependency chains, cycles or unsupported override conditions cannot
+be established by the bounded structural inspection. Another independent
+eligible Action job can still satisfy the workflow contract. Doctor does not
+execute jobs or predict their runtime success.
+
+An explicit missing-file result is blocked; an omitted or malformed provider
+entry is unavailable evidence. Doctor never treats an incomplete sample as proof
+that a file or permission is missing. Successful independent checks remain
+visible, and the report points to the run and read-access guidance for retry.

scripts/coverage-budgets.json

@@ -557,6 +557,20 @@
       ],
       "successMessage": "Git hook verification environment coverage: PASS (100% lines/statements/branches/functions)"
     },
+    {
+      "name": "Doctor matrix eligibility",
+      "missingEntryLabel": "doctor matrix eligibility",
+      "rules": [
+        {
+          "files": [
+            "src/application/policies/doctor_workflow_matrix_policy.ts"
+          ],
+          "mode": "each",
+          "thresholdProfile": "exhaustive"
+        }
+      ],
+      "successMessage": "doctor matrix eligibility coverage: PASS (100% all metrics)"
+    },
     {
       "name": "Reply request freshness",
       "missingEntryLabel": "reply request freshness",

specs/architecture-quality-and-scalability-hardening.md

@@ -880,6 +880,7 @@ package validation when bundles change, and `graphify update .` after code chang
 - Decision: quality is satisfied by observable invariants and evidence. Static
   scores guide review but are never optimized independently of cohesion and risk.
 
+Native doctor parent integration 38277723562 exhausted a Jest worker in the raw-error logging architecture suite. Its unchanged seven assertions now share one real TypeScript program with all production roots and six isolated fixture modules, instead of rebuilding the project per fixture. Real logger/sanitizer symbol resolution and the complete source scan remain mandatory. No new acceptance case is claimed and no threshold, platform or check is reduced.
 
 ### Share the real compiler graph in raw-error boundary checks (2026-10-12)
 

specs/catalog.json

@@ -129,6 +129,7 @@
         "src/application/usecases/comment_automation_command_workflow.ts",
         "src/application/usecases/steps/commit/bugbot/dismiss_bugbot_findings_use_case.ts",
         "src/application/policies/inactivity_result_counts_projection_policy.ts",
+        "src/domain/copilot_command.ts",
         "src/domain/copilot_operation.ts",
         "src/application/policies/copilot_history_policy.ts",
         "src/application/policies/copilot_history_projection_policy.ts",
@@ -680,19 +681,24 @@
       "status": "implemented",
       "scope": "Plan, validate, provision, and audit a repository installation without exposing credentials",
       "owner": "Copilot maintainers",
-      "lastVerified": "2026-10-11",
+      "lastVerified": "2026-10-13",
       "specs": [
         "specs/setup-configuration-credentials-and-doctor.md",
         "specs/setup-doctor-architecture-hardening.md",
-        "specs/setup-pat-permission-guidance-and-verification.md"
+        "specs/setup-pat-permission-guidance-and-verification.md",
+        "specs/github-runtime-doctor-command.md"
       ],
       "workflows": [
         "setup/workflows/agent-cli-provisioning.yml",
-        "setup/workflows/copilot_credential_health.yml"
+        "setup/workflows/copilot_credential_health.yml",
+        ".github/workflows/copilot_issue_comment.yml",
+        ".github/workflows/copilot_pull_request_comment.yml"
       ],
       "entrypoints": [
         "src/cli/commands/setup.ts",
-        "src/cli/commands/doctor.ts"
+        "src/cli/commands/doctor.ts",
+        "src/application/usecases/issue_comment_use_case.ts",
+        "src/application/usecases/pull_request_review_comment_use_case.ts"
       ],
       "code": [
         "src/domain/setup.ts",
@@ -779,7 +785,21 @@
         "src/cli/setup_workflow_pat_storage_copy.ts",
         "src/cli/commands/setup_policy.ts",
         "src/application/usecases/execution/execution_issue_number_policy.ts",
-        "src/application/usecases/execution/setup_execution_workflow.ts"
+        "src/application/usecases/execution/setup_execution_workflow.ts",
+        "src/domain/github_runtime_doctor.ts",
+        "src/domain/copilot_command.ts",
+        "src/application/usecases/comment_automation_command_workflow.ts",
+        "src/application/policies/copilot_interaction_policy.ts",
+        "src/application/policies/publication_message_catalog.ts",
+        "src/application/ports/github_runtime_doctor_ports.ts",
+        "src/application/policies/github_runtime_doctor_policy.ts",
+        "src/application/policies/doctor_workflow_condition_policy.ts",
+        "src/application/policies/github_runtime_doctor_presentation_policy.ts",
+        "src/application/usecases/read_copilot_doctor_workflow.ts",
+        "src/data/repository/github/runtime_doctor_repository.ts",
+        "src/infrastructure/composition/github_runtime_doctor_composition_root.ts",
+        "src/application/policies/agent_activity_policy.ts",
+        "src/application/policies/doctor_workflow_matrix_policy.ts"
       ],
       "tests": [
         "src/data/repository/__tests__/repository_version_tags_query_repository.test.ts",
@@ -845,7 +865,19 @@
         "src/actions/__tests__/local_setup_apply_contract.test.ts",
         "src/cli/commands/__tests__/setup_policy.test.ts",
         "src/application/usecases/execution/__tests__/execution_issue_number_policy.test.ts",
-        "src/application/usecases/execution/__tests__/setup_execution_workflow.test.ts"
+        "src/application/usecases/execution/__tests__/setup_execution_workflow.test.ts",
+        "src/domain/__tests__/github_runtime_doctor.test.ts",
+        "src/domain/__tests__/copilot_command.test.ts",
+        "src/application/usecases/__tests__/comment_automation_use_case.test.ts",
+        "src/application/policies/__tests__/github_runtime_doctor_policy.test.ts",
+        "src/application/policies/__tests__/doctor_workflow_condition_policy.test.ts",
+        "src/application/policies/__tests__/github_runtime_doctor_presentation_policy.test.ts",
+        "src/application/usecases/__tests__/read_copilot_doctor_workflow.test.ts",
+        "src/application/usecases/__tests__/runtime_doctor_security_integration.test.ts",
+        "src/data/repository/github/__tests__/runtime_doctor_repository.test.ts",
+        "src/infrastructure/composition/__tests__/github_runtime_doctor_composition_root.test.ts",
+        "src/application/policies/__tests__/runtime_doctor_agent_activity.test.ts",
+        "src/application/policies/__tests__/doctor_workflow_matrix_policy.test.ts"
       ],
       "documentation": [
         "README.md",
@@ -859,7 +891,8 @@
         "docs/security-operations/security/credentials.mdx",
         "docs/single-actions/workflow-and-cli.mdx",
         "docs/security-operations/operations/verification.mdx",
-        "docs/development/setup-pat-provider-audit-2026-10-06.md"
+        "docs/development/setup-pat-provider-audit-2026-10-06.md",
+        "docs/issues/comment-commands.mdx"
       ]
     },
     {