docs(ai.governance): align repo AI config to VS Code GitHub Copilot Chat only

Re-pin Addy Osmani/Graphify/Caveman to reviewed stable releases, add the
.vscode/settings.json discovery boundary so Chat reads only .github/**, and
reconcile prompts/skills/docs that had drifted from the current six-phase
lifecycle. Implements docs/architecture/specs/plan-vscode-github-copilot-chat-alignment.md
(VC-01 through VC-16).

Author: nicopizar00

.github/agents/punch-ai-governance.agent.md

@@ -48,16 +48,21 @@ absence from every `agents:` allowlist keep it out of `punch-builder`'s reach.
 ```
 Allowed:    .github/** (ALL configs — skills, prompts, agents, instructions,
             copilot-instructions; complete admin), docs/** (all documentation,
-            incl. docs/ai/**), README.md
+            incl. docs/ai/**), README.md, .vscode/settings.json (VS Code
+            GitHub Copilot Chat discovery boundary only — narrowly this one
+            file, not broader .vscode/**)
 Read-only:  source / runtime, for context only — src/**, docker/**,
             docker-compose.yml, reports/**, graphify-out/** (read, never edit)
-Forbidden:  .ai-upstream/** (frozen upstream provenance — never edit)
+Forbidden:  .ai-upstream/** (frozen upstream provenance — never edit);
+            .agents/**, .claude/**, and their workspace-root markdown
+            counterparts (dismissed external-host config — never touched,
+            never canon)
 Handle with care (admin allowed; convention, not an access block):
-            .agents/skills/** and .github/skills/graphify/** (adopted
-            upstream — prefer refresh from upstream over hand-edit; only
-            `user-invocable`/`disable-model-invocation` frontmatter fields
-            are Punch additions to `graphify`); docs/ai/history/** (frozen
-            record — append, don't rewrite).
+            .github/skills/caveman/** and .github/skills/graphify/**
+            (adopted upstream — prefer refresh from upstream over
+            hand-edit; only `user-invocable`/`disable-model-invocation`
+            frontmatter fields are Punch additions); docs/ai/history/**
+            (frozen record — append, don't rewrite).
 ```
 
 Complete admin over **all configs under `.github/`** and **all docs under

.github/assets/README.md

@@ -35,8 +35,6 @@ mirror set covers every out-of-bundle link (see the resolve gate in
 |--------------------|------------------------|
 | `docs/architecture/punch-boundaries.md` (7) | `resolve/docs/architecture/punch-boundaries.md` |
 | `docs/workflows/validation.md` (2) | `resolve/docs/workflows/validation.md` |
-| `CLAUDE.md` (2 · repo-root rule source) | `resolve/CLAUDE.md` |
-| `AGENTS.md` (1 · AI agent guide) | `resolve/AGENTS.md` |
 
 ## Hub-Spoke
 

.github/assets/prompts/punch-init.prompt.md

@@ -22,7 +22,7 @@ description: 'AI 治理代理 · 啟引：掃 .github/ 與倉碼、安掃,certif
 2. **安掃（security scan · 須過方續）**：掃步 1 之入,查秘鑰、私 URL、內務脈絡(中樞戒律五)。
    - **PASS** = 淨,方續。
    - **FAIL** = 見洩 → 阻 certify,先報洩處,人除方再掃。
-3. **解 gate（resolve · self-resolutive check）**：驗 bundle(`.github/` + `docs/ai/`)之出域文鏈皆有 `resolve/` 鏡照覆之,使 bundle 自解、不外伸(唯 `.github/` · `docs/ai/` · `.ai-upstream/` · `resolve/`)。對 `.github/assets/README.md` 之 resolve 表(`punch-boundaries`、`validation`、`CLAUDE.md`、`AGENTS.md`)逐一核：鏡照在否、覆全引處否。
+3. **解 gate（resolve · self-resolutive check）**：驗 bundle(`.github/` + `docs/ai/`)之出域文鏈皆有 `resolve/` 鏡照覆之,使 bundle 自解、不外伸(唯 `.github/` · `docs/ai/` · `.ai-upstream/` · `resolve/`)。對 `.github/assets/README.md` 之 resolve 表(`punch-boundaries`、`validation`)逐一核：鏡照在否、覆全引處否。
    - 鏡照**缺**某出域鏈(範圍外類除外) → 解軌 **WARN**,薦補 caveman-wenyan 鏡照 snapshot 於 `resolve/`。
 4. **繪備度（map）**：對範本 `.github/assets/**` 每檔 + 解軌,定備度閘(下)。
 5. **certify**：判本倉 + Copilot 配置是否 **document_ready**(可用 `/punch-document`)。

.github/assets/resolve/AGENTS.md

@@ -16,6 +16,15 @@ before bending.
    *WHY:* irreversible + externally visible. PR boundary = where human judgment enters.
 5. **No secrets, no private URLs, no internal business context** in source, docs, prompts, or test inputs. Use env vars for any external base URL.
 
+## Discovery boundary (this workspace)
+
+VS Code Copilot Chat discovers repository customizations from
+`.github/instructions`, `.github/prompts`, `.github/agents`, and
+`.github/skills` only — [`.vscode/settings.json`](../.vscode/settings.json) is
+the enforced guard. Root `AGENTS.md`, `CLAUDE.md`, `.agents/**`, and
+`.claude/**` are disabled for this workspace and are not Punch Chat canon;
+they may still serve other hosts untouched.
+
 ## Architecture ownership
 
 Each layer owns one decision domain; Build prompts refuse cross-layer without

.github/assets/resolve/CLAUDE.md

@@ -1,13 +1,13 @@
 ---
-applyTo: "src/tests/support/**,src/punch/**,reports/**,docs/validation/**"
+applyTo: "src/tests/support/**,src/punch/**,reports/**,docs/workflows/validation.md"
 description: Contract for artifacts, logs, summaries, and reports produced by Punch.
 ---
 # Artifacts & Reporting — Path Instructions
 
 Scope: producer side of every artifact Punch emit (`src/tests/support/`,
 reporting/state code in `src/punch/`), artifact dir
 (`reports/`), validation docs explain it
-(`docs/validation/`).
+(`docs/workflows/validation.md`).
 
 ## What counts as an artifact
 

.github/copilot-instructions.md

@@ -38,7 +38,6 @@ Trigger-only — load only when the named condition is actually present, not by
 - [`punch-planning-and-task-breakdown`](../skills/punch-planning-and-task-breakdown/SKILL.md) — only on `/build auto` with no task list, to derive ordered tasks.
 - [`punch-debugging-and-error-recovery`](../skills/punch-debugging-and-error-recovery/SKILL.md) — only after a test or build actually fails.
 - [`punch-doubt-driven-development`](../skills/punch-doubt-driven-development/SKILL.md) — only for a high-risk or ambiguous decision.
-- [`graphify`](../skills/graphify/SKILL.md) — when a repo dependency map helps locate the change surface (native, explicit-only; never invoked automatically).
 
 ## Modes
 

.github/instructions/artifacts-reporting.instructions.md

@@ -33,7 +33,8 @@ This prompt (via `punch-ai-governance`, holds complete admin over `.github/`
 and `docs/`) owns and reconciles **entire** documentation surface:
 
 - **All human docs** — `README.md`, `docs/**` (incl. `docs/architecture/**`,
-  `docs/workflows/**`, `docs/validation/**`, top-level `docs/*.md`), ADRs.
+  `docs/workflows/**` [covers `docs/workflows/validation.md`], top-level
+  `docs/*.md`), ADRs.
 - **All AI-facing docs** — `docs/ai/**` and
   `.github/` instructions / prompts / skills / agents + registries.
 - **AI working artifacts** — `docs/architecture/specs/**` (prior specs / plans),

.github/prompts/punch-build.prompt.md

@@ -1,6 +1,6 @@
 ---
 agent: punch-ai-governance
-description: Init — on-demand, read-only asset enablement sweep that certifies the Punch GitHub Copilot asset set (prompts, agents, skills, instructions) is present, punch-prefixed, and Copilot-compatible before the lifecycle runs, plus an informational capability check for the optional AI-Ingest vendor skills Caveman/cavecrew. Re-runnable anytime. Reports PASS / WARN / BLOCKED. Never reconciles docs, never runs a runtime.
+description: Init — on-demand, read-only asset enablement sweep that certifies the Punch GitHub Copilot asset set (prompts, agents, skills, instructions) is present, punch-prefixed, and Copilot-compatible before the lifecycle runs, plus an informational capability check for the optional AI-Ingest vendor skill Caveman and the workspace's VS Code discovery boundary. Re-runnable anytime. Reports PASS / WARN / BLOCKED. Never reconciles docs, never runs a runtime.
 ---
 # Punch — Init (GitHub Copilot asset enablement sweep)
 
@@ -49,24 +49,25 @@ registries ([`prompt-registry.md`](../../docs/ai/prompt-registry.md),
    `/punch-document`). Missing required skill → **BLOCKED**.
 4. **Instructions.** Every `.github/instructions/*.instructions.md` has
    `applyTo:` + `description:`. Missing required instruction or bad frontmatter → **BLOCKED**.
-5. **AI Skills (Caveman + cavecrew — optional vendor capabilities; graphify — adopted upstream skill).**
-   Caveman/cavecrew presence is an **informational capability check only** —
-   never a Punch prerequisite:
+5. **AI Skills (Caveman — optional vendor capability; graphify — adopted upstream skill).**
+   Caveman presence is an **informational capability check only** — never a
+   Punch prerequisite:
    - Caveman's default-`lite` rule for VS Code GitHub Copilot Chat lives directly
      in [`copilot-instructions.md`](../copilot-instructions.md) — no separate
      Punch presentation-adapter skill. Every phase runs entirely in normal
      prose when Caveman is absent or inactive; not a gap.
-   - The vendor skills `caveman` + `cavecrew` are installed via the **accepted
-     AI-Ingest path** ([`.github/.ai-upstream/README.md`](../.ai-upstream/README.md)),
-     scoped to `github-copilot`. `caveman` is relocated once to
-     `.github/skills/caveman/` (the Copilot project-skill location — installer
-     default is `.agents/skills/caveman/`, which must not remain populated);
-     `cavecrew` stays at its installer-default `.agents/skills/cavecrew/`, with
-     the optional `punch-cavecrew-investigator` / `punch-cavecrew-reviewer`
-     Copilot personas in `.github/agents/`. Not installed →
-     **WARN** (user installs manually; purely optional — Build never depends on
-     cavecrew, and Review/Test/Security lose only the optional bounded-worker
-     assist).
+   - The vendor skill `caveman` is installed via the **accepted AI-Ingest path**
+     ([`.github/.ai-upstream/README.md`](../.ai-upstream/README.md)), scoped to
+     `github-copilot`, relocated once to `.github/skills/caveman/` (the Copilot
+     project-skill location — installer default `.agents/skills/caveman/` must
+     not remain populated). Not installed → **WARN** (user installs manually;
+     purely optional — Build never depends on it).
+   - The optional `punch-cavecrew-investigator` / `punch-cavecrew-reviewer`
+     Copilot custom agents in `.github/agents/` (see check 2) are
+     self-contained and certified on their own frontmatter — they require no
+     `.agents/**` vendor skill to be present. `.agents/**` is outside this
+     workspace's VS Code Chat discovery boundary and is never a Punch
+     capability, prerequisite, resolver target, or canon.
    - The native upstream skill [`graphify`](../skills/graphify/SKILL.md) exists,
      adopted verbatim (only `user-invocable:` / `disable-model-invocation:` host
      metadata added — no Punch-authored fork; native skills stay agnostic per
@@ -98,6 +99,14 @@ registries ([`prompt-registry.md`](../../docs/ai/prompt-registry.md),
    must not misdirect Copilot away from Punch's GitHub-Copilot-first design (e.g.
    telling Copilot the runtime or an external tool is the entry point for Punch
    asset work). Misdirection → **WARN** (fix via `/punch-document`).
+10. **VS Code discovery boundary.** [`.vscode/settings.json`](../../.vscode/settings.json)
+    exists and is valid JSON; `chat.useAgentsMdFile`, `chat.useNestedAgentsMdFiles`,
+    and `chat.useClaudeMdFile` are `false`; `chat.instructionsFilesLocations`,
+    `chat.promptFilesLocations`, `chat.agentFilesLocations`, and
+    `chat.agentSkillsLocations` each enable their `.github/*` root
+    (`.github/instructions`, `.github/prompts`, `.github/agents`,
+    `.github/skills`). Missing file, invalid JSON, or a required key set to the
+    wrong value → **BLOCKED**.
 
 ## Grading
 
@@ -136,9 +145,10 @@ one-line reason — then:
   broad fixer. Scripts under the repo are **not** mutable Init assets — Init does
   not embed or edit Python, shell, `setup.py`, or launchers.
 - **Copilot-first.** Checks only the assets Punch needs to operate through VS Code
-  GitHub Copilot. Vendor tools (graphify, the Caveman/cavecrew pack) are in scope
-  **only** via the accepted AI-Ingest path; non-Copilot agent runtimes (Claude
-  Code, Cloud Code) are out of scope entirely.
+  GitHub Copilot. Vendor tools (graphify, Caveman) are in scope **only** via the
+  accepted AI-Ingest path; `.agents/**` vendor skills (e.g. `cavecrew`) and
+  non-Copilot agent runtimes (Claude Code, Cloud Code) are out of scope
+  entirely.
 - **Lifecycle preserved.** Init certifies; it does not alter the Spec → Plan →
   Build → Test → Review → Ship → Document lifecycle it gates.