pan-wizard 3.32.0 → 3.33.0

package/agents/pan-verifier.md

@@ -26,7 +26,7 @@ Before verifying, discover project context:
 1. List available skills (subdirectories)
 2. Read `SKILL.md` for each skill (lightweight index ~130 lines)
 3. Load specific `rules/*.md` files as needed during verification
-4. Do NOT load full `AGENTS.md` files (100KB+ context cost)
+4. Skip the full `AGENTS.md` inside a skill directory (100KB+ context cost). The project's own `AGENTS.md`, which `./CLAUDE.md` may import, is project instructions — read it.
 5. Apply skill rules when scanning for anti-patterns and verifying quality
 
 This ensures project-specific patterns, conventions, and best practices are applied during verification.
@@ -73,8 +73,10 @@ Set `is_re_verification = false`, proceed with Step 0b.
 If the current phase number > 1, check that the previous phase was verified:
 
 ```bash
-PREV_PHASE=$((PHASE_NUM - 1))
-ls .planning/phase-${PREV_PHASE}*/*-verification.md 2>/dev/null
+# 10# reads a zero-padded number like 08 as decimal (bash would read it as octal)
+PREV_PHASE=$((10#${PHASE_NUM%%[!0-9]*} - 1))
+PREV_DIR=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs find-phase "$PREV_PHASE" --raw 2>/dev/null)
+[ -n "$PREV_DIR" ] && ls "$PREV_DIR"/*-verification.md 2>/dev/null
 ```
 
 **If previous phase has no verification.md:**
@@ -101,12 +103,12 @@ Extract phase goal from roadmap.md — this is the outcome to verify, not the ta
 
 ## Step 1c: Repo-Norms-First Verification (P-RES-005)
 
-If `.planning/codebase/CONVENTIONS.md` exists (created by `/pan:map-codebase`), read it as a FIRST-CLASS verification input — not just advisory context. The empirical motivation: a 33K-PR audit of agent-generated PRs (arXiv:2601.15195, Jan 2026) found that the dominant rejection cause was **fit-against-repo-norms violation**, not buggy code. Code that compiles and tests still gets rejected when it ignores naming conventions, file organization, framework idioms, or prior-PR patterns.
+If `.planning/codebase/conventions.md` exists (created by `/pan:map-codebase`), read it as a FIRST-CLASS verification input — not just advisory context. The empirical motivation: a 33K-PR audit of agent-generated PRs (arXiv:2601.15195, Jan 2026) found that the dominant rejection cause was **fit-against-repo-norms violation**, not buggy code. Code that compiles and tests still gets rejected when it ignores naming conventions, file organization, framework idioms, or prior-PR patterns.
 
 ```bash
 # Read codebase conventions and structure if available
-[ -f .planning/codebase/CONVENTIONS.md ] && cat .planning/codebase/CONVENTIONS.md
-[ -f .planning/codebase/STRUCTURE.md ] && cat .planning/codebase/STRUCTURE.md
+[ -f .planning/codebase/conventions.md ] && cat .planning/codebase/conventions.md
+[ -f .planning/codebase/structure.md ] && cat .planning/codebase/structure.md
 ```
 
 **How to use this in verification:**
@@ -115,11 +117,11 @@ If `.planning/codebase/CONVENTIONS.md` exists (created by `/pan:map-codebase`),
 
 2. **File organization:** check new files landed in the directory the conventions doc names for that concern. Auth code in `lib/auth/` not `src/auth/` if conventions said `lib/`.
 
-3. **Framework idioms:** if CONVENTIONS.md names "we use X over Y because Z", check the executor didn't import Y. Generic correctness isn't enough — local idiom-fit matters.
+3. **Framework idioms:** if conventions.md names "we use X over Y because Z", check the executor didn't import Y. Generic correctness isn't enough — local idiom-fit matters.
 
-4. **Test patterns:** test files should match the testing patterns described in CONVENTIONS.md (test file naming, fixture organization, assertion style).
+4. **Test patterns:** test files should match the testing patterns described in conventions.md (test file naming, fixture organization, assertion style).
 
-If CONVENTIONS.md does not exist, skip this step silently. This is brownfield-only signal. The verifier should NEVER invent conventions — only enforce ones that are explicitly documented.
+If conventions.md does not exist, skip this step silently. This is brownfield-only signal. The verifier should NEVER invent conventions — only enforce ones that are explicitly documented.
 
 ## Step 1b: Read the Reasoning Trace (P-RES-003)
 
@@ -481,11 +483,17 @@ Unrequested work never changes the status on its own; a phase can pass with it.
 **Why human:** {Why can't verify programmatically}
 ```
 
+## Step 8b: Run the Test Gate
+
+Run the project's test suite exactly as the verify-phase protocol's `run_test_suite` step says (`~/.claude/pan-wizard-core/workflows/verify-phase.md`): detect a test script first, then run it and judge the exit code before any count. Record the result in the frontmatter as `test_gate: passed | failed | skipped`. `skipped` is only for a project with no test script; a suite that exists and did not run is `failed`.
+
+A gate you could not run goes in `not_checked` with the reason, e.g. `- check: "tests"` / `reason: "no test script in package.json"`. If the orchestrator already ran the suite and gave you the result, record that result rather than running it again.
+
 ## Step 9: Determine Overall Status
 
-**Status: passed** — All truths VERIFIED, all artifacts pass levels 1-3, all key links WIRED, no blocker anti-patterns.
+**Status: passed** — All truths VERIFIED, all artifacts pass levels 1-3, all key links WIRED, no blocker anti-patterns, and the test gate passed or was skipped. A skipped gate stays visible: it is listed in `not_checked`, so the pass says what it did not check.
 
-**Status: gaps_found** — One or more truths FAILED, artifacts MISSING/STUB, key links NOT_WIRED, or blocker anti-patterns found.
+**Status: gaps_found** — One or more truths FAILED, artifacts MISSING/STUB, key links NOT_WIRED, blocker anti-patterns found, or the test gate FAILED.
 
 **Status: human_needed** — All automated checks pass but items flagged for human verification.
 
@@ -523,14 +531,21 @@ gaps:
 
 **ALWAYS use the Write tool to create files** — never use `Bash(cat << 'EOF')` or heredoc commands for file creation.
 
+Record `verified_commit` from `git rev-parse HEAD` before you write the file. It ties the verdict to the code you checked: `pan-tools verify stale <phase>` and `pan-tools progress` compare the phase's files against it, and a file changed since then marks this verification stale.
+
 Create `.planning/phases/{phase_dir}/{phase_num}-verification.md`:
 
 ```markdown
 ---
 phase: XX-name
 verified: YYYY-MM-DDTHH:MM:SSZ
+verified_commit: <sha> # `git rev-parse HEAD` before you write this file: the code you verified
 status: passed | gaps_found | human_needed
 score: N/M must-haves verified
+test_gate: passed | failed | skipped # Step 8b
+not_checked: # Only for checks that could not run — never count them as passed
+  - check: "tests"
+    reason: "no test script in package.json"
 re_verification: # Only if previous verification.md existed
   previous_status: gaps_found
   previous_score: 2/5

package/bin/install-lib.cjs

@@ -438,7 +438,7 @@ function convertClaudeCommandToCodexSkill(content, skillName) {
   description = toSingleLine(description);
   const shortDescription = description.length > 180 ? `${description.slice(0, 177)}...` : description;
   const adapter = getCodexSkillAdapterHeader(skillName);
-  return `---\nname: ${yamlQuote(skillName)}\ndescription: ${yamlQuote(description)}\nmetadata:\n  short-description: ${yamlQuote(shortDescription)}\n---\n\n${adapter}\n\n${body.trimStart()}`;
+  return `---\nname: ${yamlQuote(skillName)}\ndescription: ${yamlQuote(description)}\nlicense: ${yamlQuote(SKILL_LICENSE)}\nmetadata:\n  short-description: ${yamlQuote(shortDescription)}\n---\n\n${adapter}\n\n${body.trimStart()}`;
 }
 
 /**
@@ -474,6 +474,12 @@ ${note ? `\n${note}\n` : ''}</pan_skill_adapter>`;
  * for environment requirements (max 500 chars). Kept short and factual: these
  * are the two things a host cannot infer and that every PAN skill depends on.
  */
+// The Agent Skills `license` field: optional in the spec, and GitHub's validator
+// (`gh skill publish --dry-run`) warns on every skill without it (market-ideas M30).
+// Read from package.json so the skills always carry the package's own licence.
+const SKILL_LICENSE = (() => {
+  try { return require('../package.json').license || 'MIT'; } catch { return 'MIT'; }
+})();
 const SKILL_COMPATIBILITY = 'Requires Node.js (skills invoke the bundled pan-tools CLI) and a project with a .planning/ directory, created by /pan-new-project or /pan-map-codebase.';
 
 function convertClaudeCommandToUnifiedSkill(content, skillName, opts = {}) {
@@ -500,7 +506,7 @@ function convertClaudeCommandToUnifiedSkill(content, skillName, opts = {}) {
   // Deliberately NOT emitting `allowed-tools`: it is marked experimental in the
   // spec, and ADR-0028's frontmatter rule is that anything unverified stays out
   // until a live per-runtime check confirms no parser rejects it.
-  return `---\nname: ${yamlQuote(skillName)}\ndescription: ${yamlQuote(description)}\ncompatibility: ${yamlQuote(SKILL_COMPATIBILITY)}\nmetadata:\n  short-description: ${yamlQuote(shortDescription)}\n---\n\n${adapter}\n\n${body.trimStart()}`;
+  return `---\nname: ${yamlQuote(skillName)}\ndescription: ${yamlQuote(description)}\nlicense: ${yamlQuote(SKILL_LICENSE)}\ncompatibility: ${yamlQuote(SKILL_COMPATIBILITY)}\nmetadata:\n  short-description: ${yamlQuote(shortDescription)}\n---\n\n${adapter}\n\n${body.trimStart()}`;
 }
 
 // ─── Unified-skill content rewrites (extracted from bin/install.js, 2026-09) ──
@@ -707,6 +713,65 @@ function agentPluginSkillAdapterNote(kind = 'skill') {
 - \`${AGENT_PLUGIN_RUNTIME_HOME_TOKEN}\` is your runtime's user-level configuration directory (for example \`~/.claude\`, \`~/.codex\`, \`~/.gemini\`, \`~/.config/opencode\`, \`~/.copilot\`) and \`${AGENT_PLUGIN_RUNTIME_DIR_TOKEN}\` its project-level directory (\`.claude\`, \`.codex\`, \`.gemini\`, \`.opencode\`, \`.github\`). Substitute the one that applies to the runtime you are.`;
 }
 
+// ─── Agent Plugin skills over Codex's prompt cut (market-ideas S8) ──────────
+// Codex injects at most the first 8,000 bytes of a skill that came from an Agent
+// Plugin (codex-rs/ext/skills/src/render.rs `MAX_SKILL_PROMPT_BYTES`, host_prompt.rs).
+// Measured on Codex CLI 0.157.1 on 2026-10-03: a 56,540-byte PAN skill reached the
+// model as its first 8,000 bytes, cut mid-sentence; the same skill from an install's
+// .agents/skills/ arrived whole, so only the bundle is affected. A bundle skill over
+// the cut ships as a short SKILL.md that keeps its frontmatter and adapter block and
+// points at the full instructions in references/instructions.md, the Agent Skills
+// directory for files a skill loads on demand.
+const AGENT_PLUGIN_SKILL_MAX_BYTES = 8000;
+const AGENT_PLUGIN_SKILL_REFERENCE = 'references/instructions.md';
+const SKILL_SUMMARY_MIN_CHARS = 40;
+
+/**
+ * Split a converted bundle skill that is longer than Codex loads into a pointer
+ * SKILL.md and a reference file. Pure. A skill within the limit comes back as is.
+ * @param {string} skillMd - the unified converter's output (frontmatter + adapter + body)
+ * @param {string} skillName
+ * @param {number} [maxBytes]
+ * @returns {{skill: string, reference: string|null}}
+ */
+function splitOversizedSkill(skillMd, skillName, maxBytes = AGENT_PLUGIN_SKILL_MAX_BYTES) {
+  if (Buffer.byteLength(skillMd, 'utf8') <= maxBytes) return { skill: skillMd, reference: null };
+  const close = '</pan_skill_adapter>';
+  const end = skillMd.indexOf(close);
+  if (end === -1) throw new Error(`splitOversizedSkill: ${skillName} has no adapter block to keep`);
+  const head = skillMd.slice(0, end + close.length);
+  const body = skillMd.slice(end + close.length).replace(/^\s+/, '');
+  const pointer = (summary) => [
+    head,
+    '',
+    '## Instructions',
+    '',
+    `This skill's full instructions are in \`${AGENT_PLUGIN_SKILL_REFERENCE}\`, in the same directory as this SKILL.md: they are longer than some runtimes load into a prompt. Before you do anything else, read that file in full with your file-reading tool, then follow it exactly. It is the complete procedure, and nothing on this page replaces it.`,
+    ...(summary ? ['', '## What this skill does', '', summary] : []),
+    '',
+  ].join('\n');
+  // The command's own <objective> is the summary, else its first plain prose
+  // paragraph; trimmed at word boundaries until the page fits, and dropped when
+  // too little of it would be left.
+  let summary = ((body.match(/<objective>\s*([\s\S]*?)\s*<\/objective>/) || [])[1] || '').trim();
+  if (!summary) {
+    summary = body.split(/\n\s*\n/).map((p) => p.trim())
+      .find((p) => p.length >= SKILL_SUMMARY_MIN_CHARS && !/^[#<`|>\-*]/.test(p) && !/^\d+\./.test(p)) || '';
+  }
+  let skill = pointer(summary);
+  while (summary && Buffer.byteLength(skill, 'utf8') > maxBytes) {
+    summary = summary.slice(0, Math.floor(summary.length * 0.8)).replace(/\s+\S*$/, '');
+    if (summary.length < SKILL_SUMMARY_MIN_CHARS) summary = '';
+    else summary += ' …';
+    skill = pointer(summary);
+  }
+  if (Buffer.byteLength(skill, 'utf8') > maxBytes) {
+    throw new Error(`splitOversizedSkill: ${skillName}'s frontmatter and adapter alone exceed ${maxBytes} bytes`);
+  }
+  const reference = `# ${skillName}: full instructions\n\nRead from \`${skillName}/SKILL.md\`, whose adapter block defines \`${AGENT_PLUGIN_ROOT_TOKEN}\`, \`{{PAN_ARGS}}\` and the runtime-directory tokens used below.\n\n${body}`;
+  return { skill, reference };
+}
+
 /** Generate Copilot CLI skill adapter header */
 function getCopilotSkillAdapterHeader(skillName) {
   const invocation = `/pan-${skillName.replace(/^pan-/, '')}`;
@@ -743,7 +808,7 @@ function convertClaudeCommandToCopilotSkill(content, skillName) {
   description = toSingleLine(description);
   const shortDescription = description.length > 180 ? `${description.slice(0, 177)}...` : description;
   const adapter = getCopilotSkillAdapterHeader(skillName);
-  return `---\nname: ${yamlQuote(skillName)}\ndescription: ${yamlQuote(description)}\nmetadata:\n  short-description: ${yamlQuote(shortDescription)}\n---\n\n${adapter}\n\n${body.trimStart()}`;
+  return `---\nname: ${yamlQuote(skillName)}\ndescription: ${yamlQuote(description)}\nlicense: ${yamlQuote(SKILL_LICENSE)}\nmetadata:\n  short-description: ${yamlQuote(shortDescription)}\n---\n\n${adapter}\n\n${body.trimStart()}`;
 }
 
 /** Claude agent → Copilot .agent.md */
@@ -838,6 +903,31 @@ function convertClaudeToCopilotAgent(content, opts = {}) {
 
 // ─── Attribution Processing ─────────────────────────────────────────────────
 
+/**
+ * The commit attribution Claude Code's settings ask for, in processAttribution's
+ * terms: undefined keeps PAN's default `Co-Authored-By` line, null removes it, a
+ * string replaces it. Claude Code's settings reference (read 2026-10-03):
+ * `attribution: false` hides all attribution (2.1.281 and later); an empty
+ * `attribution.commit` hides the commit trailer and a non-empty one replaces it; once
+ * `commit` or `pr` is set the deprecated `includeCoAuthoredBy` is ignored, and before
+ * that `includeCoAuthoredBy: false` still hides the trailer. Until 2026-10-03 PAN
+ * read only `attribution.commit`, so `false` (an explicit request to hide) kept the
+ * default line.
+ * @param {object|null} settings - a parsed Claude settings.json
+ * @returns {string|null|undefined}
+ */
+function commitAttributionFromSettings(settings) {
+  const s = settings && typeof settings === 'object' ? settings : {};
+  const a = s.attribution;
+  if (a === false) return null;
+  if (a && typeof a === 'object') {
+    if (typeof a.commit === 'string') return a.commit === '' ? null : a.commit;
+    if (a.pr !== undefined) return undefined; // attribution set: includeCoAuthoredBy no longer applies
+  }
+  if (s.includeCoAuthoredBy === false) return null;
+  return undefined;
+}
+
 /**
  * Process Co-Authored-By lines based on attribution setting.
  * @param {string} content - File content
@@ -1042,16 +1132,25 @@ function stripThinkingFrontmatter(content, runtime) {
  * @param {Object} commands
  * @param {string} commands.updateCheckCommand   - node invocation for pan-check-update.js
  * @param {string} commands.contextMonitorCommand - node invocation for pan-context-monitor.js
+ * @param {string} [commands.stateReinjectMarkCommand]   - pan-state-reinject.js `--mark` (preCompact)
+ * @param {string} [commands.stateReinjectInjectCommand] - pan-state-reinject.js `--inject copilot` (postToolUse)
  * @returns {Object} A `.github/hooks/pan.json` config object
  */
 function buildCopilotHooksConfig(commands) {
-  const { updateCheckCommand, contextMonitorCommand, costLoggerCommand, traceLoggerCommand, stopGuardCommand } = commands || {};
+  const { updateCheckCommand, contextMonitorCommand, costLoggerCommand, traceLoggerCommand, stopGuardCommand,
+    stateReinjectMarkCommand, stateReinjectInjectCommand } = commands || {};
   const config = { version: 1, hooks: {} };
   if (updateCheckCommand) {
     config.hooks.sessionStart = [{ type: 'command', command: updateCheckCommand }];
   }
-  if (contextMonitorCommand) {
-    config.hooks.postToolUse = [{ type: 'command', command: contextMonitorCommand }];
+  const postToolUse = [];
+  if (contextMonitorCommand) postToolUse.push({ type: 'command', command: contextMonitorCommand });
+  // State re-injection after a compaction (M33): preCompact leaves the marker, the
+  // next postToolUse returns the block once (hooks/pan-state-reinject.js).
+  if (stateReinjectInjectCommand) postToolUse.push({ type: 'command', command: stateReinjectInjectCommand });
+  if (postToolUse.length > 0) config.hooks.postToolUse = postToolUse;
+  if (stateReinjectMarkCommand) {
+    config.hooks.preCompact = [{ type: 'command', command: stateReinjectMarkCommand }];
   }
   // subagentStop is Copilot's SubagentStop equivalent (verified docs.github.com
   // 2026-06) — carries the cost + trace loggers, same as Claude and Codex (Gemini registers neither).
@@ -1107,15 +1206,20 @@ function buildCopilotHooksConfig(commands) {
  * `compact` is where the state re-injection hook registers (M10): SessionStart with
  * the `compact` matcher (HOOK_SLOT_MATCHERS), the one event after a compaction whose
  * `hookSpecificOutput.additionalContext` reaches the model on Claude Code and Codex —
- * both hosts' PostCompact discard it (hooks references, read 2026-09-26). Gemini's
- * PreCompress fires before the summary and Copilot's preCompact is notification-only,
- * so neither gets it.
+ * both hosts' PostCompact discard it (hooks references, read 2026-09-26).
+ *
+ * `compactMark` / `compactInject` (market-ideas M33) carry it where no start event
+ * follows a compaction. Gemini's PreCompress and Copilot's preCompact are advisory,
+ * so the hook runs in two steps: a marker before the compaction, the block on the
+ * next tool result, the first point after it where both hosts take added context
+ * (gemini-cli v0.61.0 docs/hooks/reference.md; Copilot hooks reference; read
+ * 2026-10-03, and live on Copilot CLI 1.0.88 the same day).
  */
 const HOOK_EVENT_MAP = Object.freeze({
-  claude: { surface: 'settings.json', sessionStart: 'SessionStart', postToolUse: 'PostToolUse', subagentStop: 'SubagentStop', stop: 'Stop', compact: 'SessionStart' },
-  gemini: { surface: 'settings.json', sessionStart: 'SessionStart', postToolUse: null, subagentStop: null, stop: 'AfterAgent', compact: null },
-  codex: { surface: 'hooks.json', sessionStart: 'SessionStart', postToolUse: 'PostToolUse', subagentStop: 'SubagentStop', stop: 'Stop', compact: 'SessionStart' },
-  copilot: { surface: 'hooks/pan.json', sessionStart: 'sessionStart', postToolUse: 'postToolUse', subagentStop: 'subagentStop', stop: 'agentStop', compact: null },
+  claude: { surface: 'settings.json', sessionStart: 'SessionStart', postToolUse: 'PostToolUse', subagentStop: 'SubagentStop', stop: 'Stop', compact: 'SessionStart', compactMark: null, compactInject: null },
+  gemini: { surface: 'settings.json', sessionStart: 'SessionStart', postToolUse: null, subagentStop: null, stop: 'AfterAgent', compact: null, compactMark: 'PreCompress', compactInject: 'AfterTool' },
+  codex: { surface: 'hooks.json', sessionStart: 'SessionStart', postToolUse: 'PostToolUse', subagentStop: 'SubagentStop', stop: 'Stop', compact: 'SessionStart', compactMark: null, compactInject: null },
+  copilot: { surface: 'hooks/pan.json', sessionStart: 'sessionStart', postToolUse: 'postToolUse', subagentStop: 'subagentStop', stop: 'agentStop', compact: null, compactMark: 'preCompact', compactInject: 'postToolUse' },
   opencode: null,
 });
 
@@ -1140,14 +1244,16 @@ const PAN_SETTINGS_HOOKS = Object.freeze(['pan-check-update', 'pan-context-monit
  *
  * @param {object} hooks - settings.hooks
  * @param {string[]} hookNames - script basenames without `.js` (e.g. 'pan-stop-guard')
- * @param {string|null} [keepEvent] - the event the hook now belongs to, left alone
+ * @param {string|string[]|null} [keepEvent] - the event (or events: a hook such as
+ *   pan-state-reinject registers under two on Gemini) the hook now belongs to, left alone
  * @returns {string[]}
  */
 function stripPanHookEntries(hooks, hookNames, keepEvent = null) {
   const touched = [];
   if (!hooks || typeof hooks !== 'object' || Array.isArray(hooks)) return touched;
+  const keep = new Set([].concat(keepEvent || []));
   for (const event of Object.keys(hooks)) {
-    if (event === keepEvent || !Array.isArray(hooks[event])) continue;
+    if (keep.has(event) || !Array.isArray(hooks[event])) continue;
     const before = hooks[event].length;
     hooks[event] = hooks[event].filter(entry => !(entry && Array.isArray(entry.hooks)
       && entry.hooks.some(h => h && typeof h.command === 'string' && hookNames.some(n => h.command.includes(n)))));
@@ -1719,6 +1825,49 @@ function verifyInstall(configDir, manifest) {
   return { ok: missing.length === 0 && empty.length === 0, missing, empty, warnings };
 }
 
+/**
+ * The script a PAN hook command runs, as written in the command: `node "<path>"`
+ * (global installs, buildHookCommand) or `node <dir>/hooks/<hook>.js` (local
+ * installs, relative to the project root). Null for any other command shape.
+ * @param {string} command
+ * @returns {string|null}
+ */
+function hookCommandScript(command) {
+  // Plain arguments may follow the script (`--mark`, `--inject gemini`, M33).
+  const m = /^node\s+(?:"([^"]+)"|([^\s"]+))(?:\s+[^\s"]+)*$/.exec(String(command || '').trim());
+  return m ? (m[1] || m[2]) : null;
+}
+
+/**
+ * Check that every hook command an install is about to register runs a script
+ * that exists and has content (market-ideas M24). Read-only: nothing is executed
+ * or written. A dev install from a clone without `npm run build:hooks` copied no
+ * hook scripts and registered every hook anyway, so each session event ran a
+ * missing file. A relative script resolves against `projectRoot`, the directory a
+ * local install's hook commands run from.
+ *
+ * @param {string[]} commands - the hook commands to register
+ * @param {string} projectRoot
+ * @returns {{ok: boolean, missing: string[]}} each missing entry names the script and why
+ */
+function verifyHookEntrypoints(commands, projectRoot) {
+  const missing = [];
+  for (const command of commands) {
+    const script = hookCommandScript(command);
+    if (!script) {
+      missing.push(`${command} (not a "node <script>" command)`);
+      continue;
+    }
+    const abs = path_v.isAbsolute(script) ? script : path_v.join(projectRoot, script);
+    try {
+      if (fs_v.statSync(abs).size === 0) missing.push(`${script} (empty)`);
+    } catch {
+      missing.push(`${script} (missing)`);
+    }
+  }
+  return { ok: missing.length === 0, missing };
+}
+
 // ─── Claude Code plugin packaging (2026-06) ─────────────────────────────────
 
 /**
@@ -2353,6 +2502,7 @@ module.exports = {
   convertClaudeToCopilotAgent,
   // Attribution
   processAttribution,
+  commitAttributionFromSettings,
   // JSONC
   parseJsonc,
   // Opus 4.7 capabilities
@@ -2392,6 +2542,9 @@ module.exports = {
   buildAgentPluginManifest,
   buildAgentPluginMcpConfig,
   agentPluginSkillAdapterNote,
+  AGENT_PLUGIN_SKILL_MAX_BYTES,
+  AGENT_PLUGIN_SKILL_REFERENCE,
+  splitOversizedSkill,
   buildCopilotPluginHooksConfig,
   COPILOT_PLUGIN_NAMESPACE,
   buildPluginManifest,
@@ -2400,6 +2553,8 @@ module.exports = {
   buildPluginSelfTestCommand,
   // Install verification (v3.7.10)
   verifyInstall,
+  hookCommandScript,
+  verifyHookEntrypoints,
   // AGENTS.md universal rules layer (ADR-0028 Phase 3)
   buildAgentsMdSection,
   upsertAgentsMdSection,

package/bin/install.js

@@ -364,15 +364,10 @@ function getCommitAttribution(runtime) {
       result = settings.attribution.commit;
     }
   } else if (runtime === 'claude') {
-    // Claude Code
+    // Claude Code: `attribution: false`, `attribution.commit` and the deprecated
+    // `includeCoAuthoredBy`, resolved in the documented order (install-lib).
     const settings = readSettings(path.join(getGlobalDir('claude', explicitConfigDir), 'settings.json')) || {}; // unusable file = no info (read-only probe)
-    if (!settings.attribution || settings.attribution.commit === undefined) {
-      result = undefined;
-    } else if (settings.attribution.commit === '') {
-      result = null;
-    } else {
-      result = settings.attribution.commit;
-    }
+    result = lib.commitAttributionFromSettings(settings);
   } else if (runtime === 'copilot') {
     // Copilot CLI: user-editable settings live in settings.json; config.json is
     // legacy (auto-migrated by the CLI, now internal state) — fall back for old installs
@@ -2744,6 +2739,28 @@ function install(isGlobal, runtime = 'claude') {
   const stateReinjectCommand = isGlobal
     ? buildHookCommand(targetDir, 'pan-state-reinject.js')
     : 'node ' + dirName + '/hooks/pan-state-reinject.js';
+  // Gemini and Copilot (M33): a marker before the compaction, the block on the next
+  // tool result. The inject mode names the host, whose output shapes differ.
+  const stateReinjectMarkCommand = `${stateReinjectCommand} --mark`;
+  const stateReinjectInjectCommand = `${stateReinjectCommand} --inject ${isCopilot ? 'copilot' : 'gemini'}`;
+
+  // Every hook command about to be registered must run a script that is there
+  // (market-ideas M24). The copy above skips the hooks when hooks/dist is absent (a
+  // source checkout without `npm run build:hooks`), and every hook was registered
+  // anyway, so each session event then ran a missing file. Fail before writing any
+  // runtime config. OpenCode registers no hooks.
+  if (!isOpencode) {
+    const entrypoints = lib.verifyHookEntrypoints([
+      updateCheckCommand, contextMonitorCommand, statuslineCommand, costLoggerCommand,
+      traceLoggerCommand, stopGuardCommand, stateReinjectCommand, stateReinjectMarkCommand, stateReinjectInjectCommand,
+    ], process.cwd());
+    if (!entrypoints.ok) {
+      console.error(`\n  ${red}✖ Hook verification FAILED — these hook commands would run a script that is not there:${reset}`);
+      for (const m of entrypoints.missing) console.error(`    - ${m}`);
+      console.error(`\n  No hooks were registered. In a source checkout, run ${cyan}npm run build:hooks${reset} first, then re-run the installer.\n`);
+      process.exit(1);
+    }
+  }
 
   if (isCodex) {
     // Codex hooks (2026-06): Claude-compatible PascalCase events in the shared
@@ -2773,12 +2790,12 @@ function install(isGlobal, runtime = 'claude') {
   // from any legacy config.json registration.
   if (isCopilot) {
     const hooksConfigPath = path.join(targetDir, 'hooks', 'pan.json');
-    const hooksConfig = buildCopilotHooksConfig({ updateCheckCommand, contextMonitorCommand, costLoggerCommand, traceLoggerCommand, stopGuardCommand });
+    const hooksConfig = buildCopilotHooksConfig({ updateCheckCommand, contextMonitorCommand, costLoggerCommand, traceLoggerCommand, stopGuardCommand, stateReinjectMarkCommand, stateReinjectInjectCommand });
     try {
       fs.mkdirSync(path.dirname(hooksConfigPath), { recursive: true });
       fs.writeFileSync(hooksConfigPath, JSON.stringify(hooksConfig, null, 2) + '\n');
       // Same as the Codex case: a global Copilot install writes to ~/.copilot/, not .github/.
-      console.log(`  ${green}✓${reset} Configured hooks (${displayPath(hooksConfigPath)}: update check, context monitor, cost + trace loggers, stop guard)`);
+      console.log(`  ${green}✓${reset} Configured hooks (${displayPath(hooksConfigPath)}: update check, context monitor, cost + trace loggers, stop guard, state re-injection)`);
     } catch (e) {
       console.error(`  ${yellow}✗${reset} Failed to write Copilot hooks config: ${e.message}`);
     }
@@ -2872,19 +2889,27 @@ function install(isGlobal, runtime = 'claude') {
       { slot: 'subagentStop', hook: 'pan-trace-logger', command: traceLoggerCommand, label: 'trace logger hook' },
       { slot: 'stop', hook: 'pan-stop-guard', command: stopGuardCommand, label: 'auto-advance stop guard hook' },
       { slot: 'compact', hook: 'pan-state-reinject', command: stateReinjectCommand, label: 'state re-injection hook (after compaction)' },
+      // Gemini (M33): no start event follows a compaction, so a marker before it and
+      // the block on the next tool result.
+      { slot: 'compactMark', hook: 'pan-state-reinject', command: stateReinjectMarkCommand, label: 'state re-injection marker (before compaction)' },
+      { slot: 'compactInject', hook: 'pan-state-reinject', command: stateReinjectInjectCommand, label: 'state re-injection (first tool result after compaction)' },
     ];
+    // Every event a hook registers under on this runtime: a hook may have more than
+    // one (pan-state-reinject on Gemini), and the upgrade sweep must leave all of them.
+    const eventsOf = (hook) => registrations.filter((x) => x.hook === hook).map((x) => events[x.slot]).filter(Boolean);
     const unsupported = [];
     for (const r of registrations) {
       const event = events[r.slot] || null;
       // Upgrade path: an entry for this hook under any other event is dead (a key
       // the runtime does not have) or a stale duplicate. Keyed on the script, so a
       // hook that moved event is cleaned wherever an older install put it.
-      const removedFrom = lib.stripPanHookEntries(settings.hooks, [r.hook], event);
+      const keep = eventsOf(r.hook);
+      const removedFrom = lib.stripPanHookEntries(settings.hooks, [r.hook], keep);
       if (removedFrom.length > 0) {
-        console.log(`  ${green}✓${reset} Removed the ${r.label} from ${removedFrom.join(', ')}${event ? '' : ` (${runtime} has no event for it)`}`);
+        console.log(`  ${green}✓${reset} Removed the ${r.label} from ${removedFrom.join(', ')}${keep.length ? '' : ` (${runtime} has no event for it)`}`);
       }
       if (!event) {
-        unsupported.push(r.hook);
+        if (keep.length === 0 && !unsupported.includes(r.hook)) unsupported.push(r.hook);
         continue;
       }
       if (!Array.isArray(settings.hooks[event])) {
@@ -2903,7 +2928,7 @@ function install(isGlobal, runtime = 'claude') {
       delete settings.hooks;
     }
     if (isGemini && unsupported.length > 0) {
-      console.log(`  ${dim}ℹ Gemini CLI has no context-window metric for hooks, no subagent-completion event and no post-compaction event that adds context, so ${unsupported.join(', ')} ${unsupported.length === 1 ? 'is' : 'are'} not registered there${reset}`);
+      console.log(`  ${dim}ℹ Gemini CLI has no context-window metric for hooks and no subagent-completion event, so ${unsupported.join(', ')} ${unsupported.length === 1 ? 'is' : 'are'} not registered there${reset}`);
     }
   }
 

package/commands/pan/army.md

@@ -36,9 +36,9 @@ The army is the campaign-scale sibling of `/pan:exec-phase --hierarchical` (one
 
 **Reading the Model-tier column.** These are PAN *tiers*, not model names. `reasoning` resolves to `inherit` — the model you launched with — while `mid` and `fast` map to the provider's mid/fast models (Sonnet and Haiku on Anthropic).
 
-**Reading the Access column.** The backticked values on the tier-1 rows are the `access` labels `squad list` reports; tier 0 and tier 2 carry PAN's own. They are role contracts the conductor's prompt assigns when it delegates, not a sandbox: `squads.cjs` says of itself that it "modifies no agent and changes no execution path", so a label can differ from what an agent may actually do — expect that, since several `read-only` squad members hold `Write` to emit planning or verification artifacts. The binding grant is each agent's own `tools:` frontmatter (`grep '^tools:' agents/*.md`), and Mission Control's includes `Write` and `Bash`: routing rather than coding is how it is instructed to behave, not something the runtime prevents. The rail those grants do enforce is delegation depth — `grep -l '^tools:.*Task' agents/*.md` names every agent able to spawn another (today, `pan-conductor`), so a squad agent cannot fan out further.
+**Reading the Access column.** The backticked values on the tier-1 rows are the `access` labels `squad list` reports; tier 0 and tier 2 carry PAN's own. They are role contracts the conductor's prompt assigns when it delegates, not a sandbox: `squads.cjs` says of itself that it "modifies no agent and changes no execution path", so a label can differ from what an agent may actually do — expect that, since several `read-only` squad members hold `Write` to emit planning or verification artifacts. The binding grant is each agent's own `tools:` frontmatter (`grep '^tools:' ~/.claude/agents/*.md`), and Mission Control's includes `Write` and `Bash`: routing rather than coding is how it is instructed to behave, not something the runtime prevents. The rail those grants do enforce is delegation depth — `grep -l '^tools:.*Task' ~/.claude/agents/*.md` names every agent able to spawn another (today, `pan-conductor`), so a squad agent cannot fan out further.
 
-**Squad tier is not profile tier.** The tier column above is a `squads.cjs` grouping attribute — what `pan-tools squad list` reports — and it is not what resolves an agent's model; that comes from the active `model_profile` (`quality` and `balanced` are `reasoning` for every agent, and `budget` is the only profile that down-tiers), plus any `model:` pin in an agent's own frontmatter. So the `mid` on the Quality and Release rows does not describe what those agents run under the default profile — under `quality` and `balanced` they resolve `reasoning` like everything else. The tier-1 values above are the squad groupings; the tier-0 and tier-2 values are per-agent profile tiers. **`budget` resolves per agent, not per row:** it sends some workers to `fast` and others to `mid`, so no single value is true of the Tier 2 row — `MODEL_PROFILES` in `pan-wizard-core/bin/lib/core.cjs` is the table, and it is the one to read rather than a tier written into a doc. For the agents that pin a model outright, `grep -l '^model: opus' agents/*.md` lists them — the pin applies on Claude Code only, since the installer strips it for the other runtimes.
+**Squad tier is not profile tier.** The tier column above is a `squads.cjs` grouping attribute — what `pan-tools squad list` reports — and it is not what resolves an agent's model; that comes from the active `model_profile` (`quality` and `balanced` are `reasoning` for every agent, and `budget` is the only profile that down-tiers), plus any `model:` pin in an agent's own frontmatter. So the `mid` on the Quality and Release rows does not describe what those agents run under the default profile — under `quality` and `balanced` they resolve `reasoning` like everything else. The tier-1 values above are the squad groupings; the tier-0 and tier-2 values are per-agent profile tiers. **`budget` resolves per agent, not per row:** it sends some workers to `fast` and others to `mid`, so no single value is true of the Tier 2 row — `MODEL_PROFILES` in `~/.claude/pan-wizard-core/bin/lib/core.cjs` is the table, and it is the one to read rather than a tier written into a doc. For the agents that pin a model outright, `grep -l '^model: opus' ~/.claude/agents/*.md` lists them — the pin applies on Claude Code only, since the installer strips it for the other runtimes.
 
 ---
 

package/commands/pan/experiment.md

@@ -32,7 +32,7 @@ allowed-tools:
 
 - Building production user features. Use `/pan:new-project` and `/pan:exec-phase` directly.
 - Validating a single-file change. The experiment loop is heavy — use `npm test` and `/pan:quick`.
-- Inside the PAN source repo. The command **refuses** to scaffold experiments inside `d:\PanWizard\` (or wherever the source is cloned). The experiment root defaults to `~/pan-experiments/`.
+- Inside the PAN source repo. The command **refuses** to scaffold experiments inside PAN's source repository, wherever it is cloned. The experiment root defaults to `~/pan-experiments/`.
 
 ---
 
@@ -208,7 +208,7 @@ pan-tools experiment manifest md-lint
 
 ## Safety guards
 
-- **Never inside source repo.** `newExperiment` refuses to write to `d:\PanWizard\` (or wherever the PAN source is). Mirrors `bin/install.js` `PAN_SOURCE_ROOT` guard.
+- **Never inside source repo.** `newExperiment` refuses to write inside PAN's source repository, wherever it is cloned. Mirrors `bin/install.js` `PAN_SOURCE_ROOT` guard.
 - **No clobber.** Refuses to scaffold over an existing experiment folder of the same slug.
 - **Slug validation.** Lowercase + digits + hyphens, max 40 chars. Rejects uppercase, spaces, special characters.
 - **Idea path validation.** Errors if the `--idea` file doesn't exist.

package/commands/pan/focus-auto.md

@@ -88,7 +88,8 @@ Wait for the user's reply before proceeding. Do not guess or pick a default cate
 
 ```
 /pan:focus-auto [--source scan|backlog] [--category CAT] [--mode MODE] [--budget N]
-                [--max-cycles N] [--total-budget N] [--continue] [--stop] [--status]
+                [--max-cycles N] [--total-budget N] [--enforce-budget] [--verify-reserve F]
+                [--continue] [--stop] [--status]
                 [--dry-run] [--deep-review]
                 [--parallel-research] [--parallel-verify] [--clean-seal]
 ```
@@ -124,6 +125,7 @@ Wait for the user's reply before proceeding. Do not guess or pick a default cate
 | optimize | P1-P4 | balanced | 50 |
 | prompts | P0-P6 | balanced | 100 |
 | security | P0-P2 | bugfix | 40 |
+| distill | P1-P5 | balanced | 50 |
 
 ## Backlog source (`--source backlog`, ADR-0031)
 
@@ -162,7 +164,8 @@ The proven shape is **parallel read-only research → exactly ONE serial impleme
    - Skip to Phase 2 (Main Loop)
 4. If no `--category` was provided, you already displayed the menu in FIRST ACTION above. Use SELECTED_CATEGORY from the user's reply.
 5. Initialize new run using the category from step 4:
-   - Run `pan-tools focus auto --category <SELECTED_CATEGORY> [--mode MODE] [--budget N] [--max-cycles N] [--total-budget N] [--dry-run]`
+   - Run `pan-tools focus auto --category <SELECTED_CATEGORY> [--source scan|backlog] [--mode MODE] [--budget N] [--max-cycles N] [--total-budget N] [--enforce-budget] [--verify-reserve F] [--deep-review] [--parallel-research] [--parallel-verify] [--clean-seal] [--dry-run]`,
+     passing on every one of these flags the user gave: the tooling reads each of them, and a flag left off here never takes effect
    - If `--dry-run`: display the plan, STOP
    - Record the run state
 
@@ -352,6 +355,7 @@ Check the response for stop conditions:
 - `diminishing_returns`: Optimize only — cycle efficiency < 30% of previous cycle — go to Phase 3
 - `prompts_complete`: Prompts only — all prompts in document executed — go to Phase 3
 - `security_complete`: Security only — scan found no HIGH/CRITICAL items remaining — go to Phase 3
+- `distill_complete`: Distill only — scan found no bloat findings remaining — go to Phase 3
 - `deep_review_block`: `--deep-review` only — critical pattern detected in changed files — go to Phase 3 with warning
 - `null`: Continue to next cycle
 
@@ -418,7 +422,7 @@ Then continue immediately to the next cycle (back to Step 2.1).
 | Layer | Mechanism | Action |
 |-------|-----------|--------|
 | Per-cycle budget | `--budget N` per cycle | Limits single-cycle damage |
-| Cumulative budget | `--total-budget N` | Prevents runaway spending |
+| Cumulative budget | `--total-budget N` | Advisory by default (tracked and surfaced); stops the run only when enforced (`--enforce-budget` / config `budget.enforce`) |
 | Verify reserve | `--verify-reserve F` | Holds back a budget fraction so the final re-verification isn't starved — stops new work early under enforcement (`budget_reserve_reached`) and spends the reserve on the clean re-verify in Phase 3 |
 | Iteration limit | `--max-cycles N` | Hard stop on loop count |
 | Regression circuit breaker | tests_after < tests_before | Immediate stop, status=stopped |
@@ -534,12 +538,12 @@ Three passes per cycle:
 
 | OWASP | Grep pattern | Priority |
 |-------|-------------|---------|
-| A03 Injection | `eval(`, `execSync(`, `` `SELECT.*\${ ``, `child_process.exec(` | P0 |
-| A02 Crypto | `createHash\(['"]md5\|sha1`, `Math\.random\(\)` near auth/token | P0 |
+| A05 Injection | `eval(`, `execSync(`, `` `SELECT.*\${ ``, `child_process.exec(` | P0 |
+| A04 Crypto | `createHash\(['"]md5\|sha1`, `Math\.random\(\)` near auth/token | P0 |
 | A01 Access | Route without auth middleware, IDOR (raw `req.params.id` to DB) | P1 |
-| A05 Misconfig | `origin:\s*['"]?\*`, `Access-Control-Allow-Origin: \*`, stack in response | P1 |
+| A02 Misconfig | `origin:\s*['"]?\*`, `Access-Control-Allow-Origin: \*`, stack in response | P1 |
 | A07 Auth | No session expiry, credentials in URL params | P1 |
-| A04 Design | Missing rate-limit on auth/payment endpoints | P2 |
+| A06 Design | Missing rate-limit on auth/payment endpoints | P2 |
 | A09 Logging | Security events (`login`, `payment`, `admin`) with no log call nearby | P2 |
 
 **Pass 2 — Structural check (always runs):**
@@ -669,7 +673,7 @@ This prevents the campaign from burning budget on items that will predictably fa
 - Continue after a test regression — a test count decrease means code was broken; continuing compounds the damage
 - Expand scope beyond what the scan found — scope creep in an autonomous loop compounds unpredictably across cycles
 - Run more cycles than --max-cycles — the limit exists to cap total cost and prevent runaway loops
-- Spend more points than --total-budget — the budget cap is the user's cost control mechanism
+- Spend more points than --total-budget when the budget is enforced (`--enforce-budget` or config `budget.enforce: true`) — the enforced cap is the user's cost control mechanism
 - Skip recording cycle results via --update — unrecorded cycles break resume, status, and stop-condition checks
 - Change test expectations to match broken code — this hides bugs instead of fixing them
 - Use `git add -A` or `git add .` — bulk staging can accidentally commit secrets, build artifacts, or unrelated changes

package/commands/pan/focus-design.md

@@ -1073,6 +1073,8 @@ Output a complete summary with:
 
 ## NEVER DO
 
+These rules and ALWAYS DO below apply to the phases your mode actually runs. Anything the Mode + Phase Matrix or a modifier skips (a whole phase, or the parts a lite phase leaves out) is not a violation.
+
 - Design without proving the problem exists (Phase 0 demand evidence is mandatory)
 - Skip competitive research — must be best-of-breed
 - Copy a tool's design without understanding WHY they made that choice

package/commands/pan/focus-exec.md

@@ -1,7 +1,7 @@
 ---
 name: focus-exec
 group: Focus
-description: Automated batch execution pipeline with 6 stages, 9 behavioral rules, 3 execution tiers
+description: Automated batch execution pipeline with 6 stages, behavioral rules, 3 execution tiers
 allowed-tools:
   - Read
   - Write