feat: add GitHub Copilot CLI host adapter

.archcore/.sync-state.json

@@ -3371,6 +3371,46 @@
       "source": "plugin/component-registry.doc.md",
       "target": "plugin/host-wiring-parity.adr.md",
       "type": "related"
+    },
+    {
+      "source": "plugin/copilot-mcp-architecture.adr.md",
+      "target": "plugin/copilot-adapter-design.adr.md",
+      "type": "extends"
+    },
+    {
+      "source": "plugin/copilot-mcp-architecture.adr.md",
+      "target": "plugin/cursor-mcp-architecture.adr.md",
+      "type": "related"
+    },
+    {
+      "source": "plugin/copilot-mcp-architecture.adr.md",
+      "target": "plugin/host-wiring-parity.adr.md",
+      "type": "related"
+    },
+    {
+      "source": "plugin/copilot-mcp-architecture.adr.md",
+      "target": "plugin/component-registry.doc.md",
+      "type": "related"
+    },
+    {
+      "source": "plugin/host-probe-protocol.spec.md",
+      "target": "plugin/host-adapter-contract.spec.md",
+      "type": "implements"
+    },
+    {
+      "source": "plugin/host-probe-protocol.spec.md",
+      "target": "plugin/hooks-validation-system.spec.md",
+      "type": "related"
+    },
+    {
+      "source": "plugin/host-probe-protocol.spec.md",
+      "target": "plugin/jtbd1-phase2-hardening-delegated.plan.md",
+      "type": "related"
+    },
+    {
+      "source": "plugin/host-probe-protocol.spec.md",
+      "target": "plugin/plugin-testing.guide.md",
+      "type": "related"
     }
   ]
 }

.archcore/plugin/actualize-system.spec.md

@@ -8,6 +8,8 @@ tags:
   - "validation"
 ---
 
+---
+
 > **Outcome (2026-05-15):** The Actualize system shipped, but as the `--drift` mode of the unified `/archcore:audit` skill rather than as a standalone `/archcore:actualize` skill. Layer 1 and Layer 2 (the `bin/check-staleness` SessionStart hook and the `bin/check-cascade` PostToolUse hook) shipped as designed. Layer 3 was folded into `audit` per `skill-surface-collapse.adr.md`. The detection protocol now lives at `skills/audit/lib/drift-detection.md`. This spec is preserved for historical context; the active contract is the `--drift` mode in `commands-system.spec.md` and `plugin-architecture.spec.md`.
 
 ## Purpose
@@ -106,7 +108,7 @@ PostToolUse hook, fires after `mcp__archcore__update_document` succeeds. Does NO
 
 #### Handler
 
-`bin/check-cascade`, registered as a PostToolUse hook entry across all hosts (`hooks/hooks.json`, `hooks/cursor.hooks.json`, `hooks/codex.hooks.json`).
+`bin/check-cascade`, registered as a PostToolUse hook entry in all four host hook configs (`hooks/hooks.json`, `hooks/cursor.hooks.json`, `hooks/codex.hooks.json`, `hooks/copilot.hooks.json`).
 
 #### Detection Logic
 
@@ -130,6 +132,8 @@ PostToolUse hook, fires after `mcp__archcore__update_document` succeeds. Does NO
 }
 ```
 
+The wrapper above is Claude Code's and Codex's. Cursor takes `additional_context`, Copilot a bare top-level `additionalContext`, and OpenCode the plain message — the script never builds these by hand; `bin/lib/normalize-stdin.sh` output helpers pick the shape from `ARCHCORE_HOST`.
+
 #### Relation Direction Table
 
 | Relation in graph | Updated doc role | Potentially stale doc | Why |
@@ -183,7 +187,7 @@ Drift mode loads `skills/audit/lib/drift-detection.md` for the detailed protocol
 
 ### hooks configuration
 
-The cascade PostToolUse entry is shipped in all three host hook configs:
+The cascade PostToolUse entry is shipped in all four host hook configs. Claude Code, Cursor and Codex share this shape (the plugin-root variable differs per host):
 
 ```json
 {
@@ -192,6 +196,18 @@ The cascade PostToolUse entry is shipped in all three host hook configs:
 }
 ```
 
+Copilot's entry is structurally different and cannot be produced by search-and-replacing the variable — it is a flat object using `bash` instead of `command`, `timeoutSec` instead of `timeout`, and **no matcher at all**, because Copilot's `postToolUse` does not take one. The script self-filters there on the normalized tool name:
+
+```json
+{
+  "type": "command",
+  "cwd": ".",
+  "bash": "\"${COPILOT_PLUGIN_ROOT}\"/bin/check-cascade",
+  "env": { "ARCHCORE_HOST": "copilot" },
+  "timeoutSec": 3
+}
+```
+
 SessionStart hook calls `bin/check-staleness` internally as part of `bin/session-start`.
 
 ### bin/ Scripts
@@ -206,7 +222,7 @@ Requirements: executable, exits 0, completes within 3 seconds, POSIX shell, degr
 
 PostToolUse handler for cascade detection after `update_document`.
 
-Requirements: executable, exits 0, reads JSON from stdin, outputs JSON with `hookSpecificOutput` when cascade detected, POSIX shell.
+Requirements: executable, exits 0, reads JSON from stdin, outputs the host-shaped context envelope when cascade detected, POSIX shell.
 
 ## Normative Behavior
 
@@ -216,6 +232,7 @@ Requirements: executable, exits 0, reads JSON from stdin, outputs JSON with `hoo
 - Layer 2 MUST fire only after `update_document`, not after `create_document` or `remove_document`.
 - Layer 2 MUST only flag documents connected via `implements`, `depends_on`, or `extends` (not `related`).
 - Layer 2 MUST NOT block the update operation.
+- WHERE a host's PostToolUse event accepts no matcher, `bin/check-cascade` MUST reach the same decision by filtering on the normalized tool name — the set of updates that trigger a cascade warning MUST NOT differ by host.
 - Layer 3 (`/archcore:audit --drift`) MUST verify MCP availability before analysis.
 - Layer 3 MUST NOT modify documents without explicit user confirmation per document.
 - Layer 3 MUST present findings grouped by severity (critical, cascade, temporal).
@@ -252,7 +269,7 @@ The Actualize system conforms to this specification if:
 
 1. `bin/check-staleness` runs at SessionStart and produces code-drift warnings when applicable.
 2. `bin/check-cascade` runs after `update_document` and produces cascade warnings when applicable.
-3. Every host hook config (`hooks.json`, `cursor.hooks.json`, `codex.hooks.json`) registers `check-cascade` on `update_document`.
+3. Every host hook config (`hooks.json`, `cursor.hooks.json`, `codex.hooks.json`, `copilot.hooks.json`) registers `check-cascade` on `update_document` — by matcher where the host has one, and by the script's own filtering on Copilot, which has none.
 4. `/archcore:audit --drift` exists as a mode of the `audit` intent skill, with routing-table support and the 3-dimension analysis.
 5. The drift protocol lives at `skills/audit/lib/drift-detection.md`.
 6. All hooks complete within their timeout budgets.

.archcore/plugin/agent-system.spec.md

@@ -8,25 +8,41 @@ tags:
 
 ## Purpose
 
-Define the contract for the Archcore Claude Plugin's subagents — `archcore-assistant` (read/write) and `archcore-auditor` (read-only).
+Define the contract for the Archcore plugin's subagents — `archcore-assistant` (read/write) and `archcore-auditor` (read-only) — across every host that loads them.
 
 ## Scope
 
-This specification covers both agent definitions in `agents/`, their system prompts, tool restrictions, invocation triggers, and domain expertise.
+This specification covers both agent definitions, their per-host file formats, their system prompts, tool restrictions, invocation triggers, and domain expertise.
 
 ## Authority
 
 This specification is the authoritative reference for both agents. The Single Universal Agent Design ADR provides the original rationale; the Add Read-Only Auditor Agent ADR extends it. The Knowledge Tree Bootstrap ADR (`subagent-knowledge-tree-bootstrap.adr`) is authoritative for the mandatory preamble section in both agent system prompts.
 
 ## Subject
 
+### Per-host file formats
+
+The two agents are one definition each, shipped in the format every host's loader accepts. Content is identical across formats; only the container differs.
+
+| Format | Location | Read by | Notes |
+|---|---|---|---|
+| `<name>.md` | `agents/` | Claude Code, Cursor | The canonical source; agent id comes from frontmatter `name:` |
+| `<name>.toml` | `agents/` | Codex CLI | Adds `sandbox_mode` and `disabled_tools[]`; body kept in parity with the MD |
+| `<name>.agent.md` | `copilot-agents/` | GitHub Copilot CLI | Byte-identical copy of the MD; agent id comes from the filename |
+
+Copilot's copies sit in a directory of their own rather than beside the originals. Its loader accepts only the `*.agent.md` extension, and that extension still matches the `*.md` glob Claude Code and Cursor use — a sibling copy would give both hosts two files declaring the same `name:`. The TOML variants never had this problem because their extension is foreign to every md-globbing host. `test/structure/agents.bats` holds the copies byte-identical (`cmp`) and fails when an agent in `agents/` has no counterpart.
+
+### MCP tool naming
+
+A tool list is only as good as the names in it. The same MCP server appears under three names depending on how it was registered: `mcp__archcore__*` (project `.mcp.json`), `mcp__plugin_archcore_archcore__*` (plugin-bundled on Claude Code), and the flat `archcore-<tool>` (Copilot, which joins server and tool with a hyphen). Every allow-list and deny-list in the agent files carries all three. This matters asymmetrically: an allow-list missing a name loses a capability, while the auditor's TOML **deny**-list missing a name silently grants the read-only agent the power to mutate. `test/structure/agents.bats` pins the twins in both directions.
+
 ### Agent 1: archcore-assistant (Read/Write)
 
 Handles complex, multi-step documentation tasks requiring write access to MCP tools.
 
 #### Definition File
 
-Location: `agents/archcore-assistant.md`
+Location: `agents/archcore-assistant.md` (plus the TOML and `*.agent.md` variants above)
 
 ```yaml
 ---
@@ -54,9 +70,11 @@ tools:
 ---
 ```
 
+(Abbreviated: the shipped file lists each MCP tool under all three namings.)
+
 #### Invocation Triggers
 
-Claude should invoke `archcore-assistant` when:
+The host should invoke `archcore-assistant` when:
 
 - User requests creation of multiple related documents
 - Task involves requirements decomposition (e.g., "break this PRD into specifications")
@@ -69,7 +87,7 @@ Performs documentation health checks without any mutation capability.
 
 #### Definition File
 
-Location: `agents/archcore-auditor.md`
+Location: `agents/archcore-auditor.md` (plus the TOML and `*.agent.md` variants above)
 
 ```yaml
 ---
@@ -94,7 +112,7 @@ tools:
 
 #### Invocation Triggers
 
-Claude should invoke `archcore-auditor` when:
+The host should invoke `archcore-auditor` when:
 
 - User asks for a documentation audit, health check, or review
 - User asks "what's missing?" or "what needs attention?" about documentation
@@ -186,6 +204,7 @@ Three tracks that can coexist:
 - MUST, immediately after the bootstrap calls return, note the categories present, the most common tags, recent accepted decisions, and any draft plans before proceeding with the user's task. This synthesis is a read-only transformation over data already in hand; it adds no new tool calls.
 - MUST use MCP tools for all `.archcore/` operations (no Write/Edit/Bash).
 - MUST call `list_documents` before creating any document to prevent duplicates (subsumed by the bootstrap requirement above, retained for emphasis).
+- MUST list every MCP tool they use under all three namings, so the definition works whether the server was registered by the project, by the plugin, or by Copilot's flattening.
 - Should explain reasoning when choosing document types or relation types.
 
 ### archcore-assistant Only
@@ -209,6 +228,7 @@ Three tracks that can coexist:
 - System prompts must not exceed 2000 lines.
 - Neither agent may modify files outside `.archcore/` via any means.
 - Both agents respect existing document statuses.
+- Format variants exist only where a host's loader requires one. They are copies, not forks: no host-specific instruction may enter any variant (`host-adapter-contract.spec`).
 
 ## Invariants
 
@@ -217,6 +237,8 @@ Three tracks that can coexist:
 - Both agents check for existing documents before suggesting creation.
 - Every sub-agent invocation's first tool calls are `list_documents` and `list_relations` (bootstrap requirement per `subagent-knowledge-tree-bootstrap.adr`). `archcore-auditor` has no exception to this invariant; `archcore-assistant` has a narrow exception only for strictly single-document reads with explicit paths.
 - Both agent system prompts carry a `# First Step — Bootstrap Knowledge Tree` section as the first content section after the YAML frontmatter, with cross-references to `remove-skill-verify-mcp-preamble.cpat` and `subagent-knowledge-tree-bootstrap.adr`, and with the synthesis directive anchor literal `recent accepted decisions` present.
+- Every agent present in `agents/*.md` has a byte-identical `copilot-agents/<name>.agent.md` counterpart.
+- No Copilot-only tool entry exists without its canonical twin.
 
 ## Error Handling
 
@@ -228,10 +250,10 @@ Three tracks that can coexist:
 
 An agent conforms to this specification if:
 
-1. It resides at `agents/<name>.md` with the correct frontmatter
-2. Its tool list matches the allowed tools exactly (per tool access matrix)
+1. It resides at `agents/<name>.md` with the correct frontmatter, and every format variant its hosts require exists: `agents/<name>.toml` for Codex, `copilot-agents/<name>.agent.md` for Copilot
+2. Its tool list matches the allowed tools exactly (per tool access matrix), under all three MCP namings
 3. Its system prompt covers the shared domain knowledge
 4. It follows the normative behavior for its role
 5. archcore-auditor produces no mutations; archcore-assistant produces structured output
 6. Its system prompt carries the `# First Step — Bootstrap Knowledge Tree` section per `subagent-knowledge-tree-bootstrap.adr`, including cross-references to that ADR and to `remove-skill-verify-mcp-preamble.cpat`, plus the synthesis directive whose anchor literal `recent accepted decisions` is grep-able in both files
-7. `test/structure/agents.bats` asserts the bootstrap preamble and the synthesis directive anchor are present in both agent files
+7. `test/structure/agents.bats` asserts the bootstrap preamble, the synthesis directive anchor, the three-way tool naming, and byte-identity of the Copilot copies