Merge pull request #14 from nicopizar00/docs/decouple-punch-build-from-caveman

docs(ai.governance): decouple Punch Build from Caveman/cavecrew

Author: nicopizar00

.claude/commands/build.md

@@ -9,8 +9,6 @@ the canonical Copilot asset — do not re-author or paraphrase it:
 - Prompt: `.github/prompts/punch-build.prompt.md`
 - Dispatcher: `.github/agents/punch-builder.agent.md` → delegates (depth-1) to
   `punch-runtime-engineer` or `punch-performance-test-engineer`
-- Caveman: `ultra` (governance) / `wenyan` (execution sub-agents); canon:
-  `.github/skills/punch-build-caveman/SKILL.md`
 
 Requires an approved Plan task ID with allowed/read-only/forbidden paths. Follow
 that prompt exactly. Input: $ARGUMENTS

.claude/commands/document.md

@@ -9,9 +9,6 @@ obeying the canonical Copilot asset — do not re-author or paraphrase it:
 - Prompt: `.github/prompts/punch-document.prompt.md`
 - Persona + scope: `.github/agents/punch-ai-governance.agent.md` (admin over
   `.github/` + all `docs/`)
-- Caveman: `full` for wave working comms (diagnose / classify / plan); `lite` for
-  persisted docs and reports; Wenyan forbidden in docs. Emojis / ASCII emoticons
-  allowed in docs. Canon: `.github/skills/punch-build-caveman/SKILL.md`
 - Map with the **Global Graphify repository track** (`/graphify .` then
   `--update`); evidence only, never canonical.
 

.claude/commands/init.md

@@ -8,7 +8,6 @@ the canonical Copilot asset — do not re-author or paraphrase it:
 - Prompt: `.github/prompts/punch-init.prompt.md`
 - Persona + scope: `.github/agents/punch-ai-governance.agent.md` (**enforced** —
   complete admin over `.github/` + `docs/`; only this agent runs Init)
-- Caveman: `lite` (canon: `.github/skills/punch-build-caveman/SKILL.md`)
 
 Runs a read-only sweep of the GitHub Copilot asset set (prompts, agents, skills,
 instructions + the AI-Ingest Caveman/cavecrew vendor skills), reports

.claude/commands/plan.md

@@ -8,6 +8,5 @@ the canonical Copilot asset — do not re-author or paraphrase it:
 
 - Prompt: `.github/prompts/punch-plan.prompt.md`
 - Persona + scope: `.github/agents/punch-planner.agent.md`
-- Caveman: `full` (canon: `.github/skills/punch-build-caveman/SKILL.md`)
 
 Follow that prompt exactly. Input: $ARGUMENTS

.claude/commands/review.md

@@ -8,6 +8,5 @@ the canonical Copilot asset — do not re-author or paraphrase it:
 
 - Prompt: `.github/prompts/punch-review.prompt.md`
 - Persona + scope: `.github/agents/punch-reviewer.agent.md`
-- Caveman: `full` (canon: `.github/skills/punch-build-caveman/SKILL.md`)
 
 Read-only critique; no product edits. Follow that prompt exactly. Input: $ARGUMENTS

.claude/commands/ship.md

@@ -8,7 +8,6 @@ the canonical Copilot asset — do not re-author or paraphrase it:
 
 - Prompt: `.github/prompts/punch-ship.prompt.md`
 - Persona + scope: `.github/agents/punch-reviewer.agent.md`
-- Caveman: `full` (canon: `.github/skills/punch-build-caveman/SKILL.md`)
 
 Mechanical only (git/gh). Never merges, tags, or pushes to `main` — a human
 approves the merge. Follow that prompt exactly. Input: $ARGUMENTS

.claude/commands/spec.md

@@ -8,6 +8,5 @@ the canonical Copilot asset — do not re-author or paraphrase it:
 
 - Prompt: `.github/prompts/punch-spec.prompt.md`
 - Persona + scope: `.github/agents/punch-architect-readonly.agent.md`
-- Caveman: `lite` (canon: `.github/skills/punch-build-caveman/SKILL.md`)
 
 Follow that prompt exactly. Input: $ARGUMENTS

.claude/commands/test.md

@@ -8,8 +8,6 @@ loading and obeying the canonical Copilot asset — do not re-author or paraphra
 
 - Prompt: `.github/prompts/punch-test.prompt.md`
 - Persona + scope: `.github/agents/punch-test-engineer.agent.md`
-- Caveman: `ultra` (governance) / `wenyan` (execution); canon:
-  `.github/skills/punch-build-caveman/SKILL.md`
 
 Runs via `./bin/punch` only — never host k6 or raw docker. Follow that prompt
 exactly. Input: $ARGUMENTS

.claude/skills/guard/SKILL.md

@@ -28,25 +28,24 @@ When a lifecycle / governance / documentation request arrives in Claude Code:
 2. **Load + obey** that `.github/prompts/punch-*.prompt.md`, adopting the persona,
    scope, and guards of its declared `.github/agents/*.agent.md`, and activating
    the skills that prompt names.
-3. **Apply the Caveman canon** (`.github/skills/punch-build-caveman/SKILL.md`) and
-   the runtime guards (`docs/ai/agent-guards.md`) exactly as Copilot would.
+3. **Apply the runtime guards** (`docs/ai/agent-guards.md`) exactly as Copilot would.
 4. **Report** back; for delegated work, sub-agent reports stay `wenyan`-compatible
    with evidence verbatim.
 
 ## Wiring map (Claude Code command → canonical Copilot asset)
 
 The `.claude/commands/*` wraps are **thin pointers**; this table is the contract.
 
-| Claude command | Canonical prompt | Persona (agent) | Caveman level |
-|---|---|---|---|
-| `/spec`     | `.github/prompts/punch-spec.prompt.md`     | `punch-architect-readonly` | `lite` |
-| `/plan`     | `.github/prompts/punch-plan.prompt.md`     | `punch-planner`            | `full` |
-| `/build`    | `.github/prompts/punch-build.prompt.md`    | `punch-builder` → engineer | `full` (sub: `wenyan-lite`) |
-| `/test`     | `.github/prompts/punch-test.prompt.md`     | `punch-test-engineer`      | `ultra` (sub: `wenyan`) |
-| `/review`   | `.github/prompts/punch-review.prompt.md`   | `punch-reviewer`           | `full` |
-| `/ship`     | `.github/prompts/punch-ship.prompt.md`     | `punch-reviewer`           | `full` |
-| `/document` | `.github/prompts/punch-document.prompt.md` | `punch-ai-governance`      | `lite` persisted (`full` working) |
-| `/init`     | `.github/prompts/punch-init.prompt.md`     | `punch-ai-governance` (enforced) | `lite` |
+| Claude command | Canonical prompt | Persona (agent) |
+|---|---|---|
+| `/spec`     | `.github/prompts/punch-spec.prompt.md`     | `punch-architect-readonly` |
+| `/plan`     | `.github/prompts/punch-plan.prompt.md`     | `punch-planner`            |
+| `/build`    | `.github/prompts/punch-build.prompt.md`    | `punch-builder` → engineer |
+| `/test`     | `.github/prompts/punch-test.prompt.md`     | `punch-test-engineer`      |
+| `/review`   | `.github/prompts/punch-review.prompt.md`   | `punch-reviewer`           |
+| `/ship`     | `.github/prompts/punch-ship.prompt.md`     | `punch-reviewer`           |
+| `/document` | `.github/prompts/punch-document.prompt.md` | `punch-ai-governance`      |
+| `/init`     | `.github/prompts/punch-init.prompt.md`     | `punch-ai-governance` (enforced) |
 
 `@punch-ai-governance` audits are reachable the same way — load the prompt/agent
 and obey it; a dedicated command wrap is optional.
@@ -61,8 +60,6 @@ exactly two cases:
 - **B — human-facing output would be in `wenyan`** (wenyan is sub-agent-only;
   leaking it to a human is a violation — stop, don't emit it).
 
-Do not hard-overwrite the global caveman config to handle either case.
-
 ## No-break rules (preserve Copilot First)
 
 - **`.github/` is read-authoritative.** Guard and the `.claude/commands/*` wraps
@@ -76,7 +73,6 @@ Do not hard-overwrite the global caveman config to handle either case.
   Claude Code here.
 - **Respect agent boundaries.** Adopt the target agent's allowed/read-only/
   forbidden scope, tool surface, depth-1 delegation, and approval-before-write.
-  Caveman is output style only — it never widens tools or access.
 - **Governance owns this bridge.** `punch-ai-governance` (which holds admin over
   `.github/` and `docs/`) maintains the wiring map; changes to it are a governance
   edit. Claude Code never edits `.github/` to "make reuse work" without that.

.github/.ai-upstream/README.md

@@ -1,23 +1,31 @@
-# `.github/.ai-upstream/` — required vendor skill manifest
+# `.github/.ai-upstream/` — optional vendor skill manifest
 
-Staging + provenance for the **vendor** skills Punch reuses **as-is** for VS Code
-GitHub Copilot. Punch does **not** fork these — install them, keep them verbatim.
-This README (the manifest) is tracked; the installed vendor skill folders are
-gitignored (see `.gitignore`).
+Staging + provenance for **optional vendor** skills Punch may reuse **as-is** for
+VS Code GitHub Copilot. Neither is a Punch prerequisite — Punch runs the full
+lifecycle without them. Punch does **not** fork these — if installed, keep them
+verbatim. This README (the manifest) is tracked; the installed vendor skill
+folders are gitignored (see `.gitignore`).
 
-> **User manual action required.** Punch cannot run the network installer for you.
-> Install only the assets listed below, scoped to GitHub Copilot.
+> **User manual action, optional.** Punch cannot run the network installer for
+> you, and does not require you to. If you want these capabilities, install
+> only the assets listed below, scoped to GitHub Copilot.
 
-## Required by Punch (install these only)
+## Optional capabilities (install only if you want them)
 
-| Asset | Why Punch needs it |
+| Asset | What it adds |
 |---|---|
-| `caveman` | Concise assistant-prose comms (per-phase voice; canon in [`punch-build-caveman`](../skills/punch-build-caveman/SKILL.md)) |
-| `cavecrew` | Bounded leaf workers spawned by a phase **coordinator** (`punch-builder` / `punch-reviewer` / `punch-test-engineer`) at depth-1, with caveman-compressed output. Punch's Copilot adaptation are the `.github/agents/punch-cavecrew-*.agent.md` personas (vendor skill defines no Copilot `tools`) |
+| `caveman` | Concise assistant-prose comms, VS Code GitHub Copilot Chat only; default `lite` rule lives in [`copilot-instructions.md`](../copilot-instructions.md) |
+| `cavecrew` | Bounded read-only leaf workers spawned by an explicitly authorized non-Build phase **coordinator** (`punch-code-reviewer` / `punch-test-engineer` / `punch-security-auditor`) at depth-1, with caveman-compressed output. Punch's Copilot adaptation is the `.github/agents/punch-cavecrew-{investigator,reviewer}.agent.md` personas (vendor skill defines no Copilot `tools`). Build never spawns cavecrew |
 
 The installer places both in the Copilot skills dir (`.agents/skills/caveman/`,
-`.agents/skills/cavecrew/`). Keep an optional verbatim provenance snapshot under
-`.github/.ai-upstream/<skill>/` for drift diffing (untracked).
+`.agents/skills/cavecrew/`) — it has no notion of `.github/skills/`. Immediately
+after install, relocate `caveman` only: move `.agents/skills/caveman/` to
+`.github/skills/caveman/` (the Copilot project-skill location Punch registers)
+and add `user-invocable: true` + `disable-model-invocation: true` to its
+frontmatter — no other change to the upstream body. Leave `cavecrew` at its
+installer-default location; it is not relocated. Keep an optional verbatim
+provenance snapshot under `.github/.ai-upstream/<skill>/` for drift diffing
+(untracked).
 
 **Do not install** the rest of the upstream pack (`caveman-compress` ships host
 Python scripts vs Punch Docker-First; `caveman-commit`/`-help`/`-review`/`-stats`
@@ -40,21 +48,19 @@ any such artifacts if the installer created them.
 
 ## Sub-agent setting
 
-cavecrew is spawned **either** by an engineer (nested: `punch-builder` → engineer
-→ cavecrew) **or** directly by a phase coordinator (`punch-builder` /
-`punch-reviewer` / `punch-test-engineer` → cavecrew). The nested path needs
-`chat.subagents.allowInvocationsFromSubagents: true` in VS Code settings (lazy
-default); `/punch-init` warns when off. Markdown cannot set it. Depth is
-**roster-bounded**, not setting-bounded: cavecrew workers carry no `agents:`, so
-they never spawn a further level (max chain `builder → engineer → cavecrew`). A
-worker inherits its spawner's scope — by **lineage** when an engineer spawns it,
-by **injected brief** when a coordinator does (VS Code custom agents have no
-skills field) — and its `tools` are a subset of that spawner. Canon:
-[`agent-guards.md`](../../docs/ai/agent-guards.md).
+cavecrew is spawned directly by an explicitly authorized non-Build phase
+coordinator (`punch-code-reviewer` / `punch-test-engineer` /
+`punch-security-auditor` → cavecrew). Build never spawns it — no nested path,
+no `chat.subagents.allowInvocationsFromSubagents` dependency. Depth is
+**roster-bounded**: cavecrew workers carry no `agents:`, so they never spawn a
+further level. A worker inherits its coordinator's scope by **injected brief**
+(VS Code custom agents have no skills field), and its `tools` are a subset of
+that coordinator. Canon: [`agent-guards.md`](../../docs/ai/agent-guards.md).
 
 ## Rules
 
-- **Keep vendor files verbatim.** Punch's adaptation lives in
-  `.github/skills/punch-build-caveman/`, never here.
-- `punch-ai-governance` excludes installed vendor folders from naming /
+- **Keep vendor files verbatim.** The one-time `caveman` relocate step (above)
+  adds only two frontmatter fields — no other hand-edit, ever.
+- `punch-ai-governance` excludes installed/relocated vendor folders
+  (`.agents/skills/cavecrew/`, `.github/skills/caveman/`) from naming /
   duplication / stale-asset checks.