plugin-quality: audit skill hub + auditor agent

[kyle-sexton]

Parent

Source: PLAN Phases B1+B3, topic plugin-audit-port — plan locked at commit 40a64b5c on
feat/plugin-audit-port. Lane B opens only after the context-guard lane MERGES (seams-first: this
slice inlines the merged reader contract).

What to build

The plugin-quality plugin's core: /plugin-quality:audit <plugin>[:<component>] skill hub plus
the auditor plugin agent it dispatches.

Skill hub — six-step workflow: (1) evidence capture main-thread → (2) map+ground in the fresh
NAMED auditor subagent (never context: fork) with per-topic fresh-docs verification → (3)
blindspot + candidate findings → (4) interactive contract lock → (5) presence-gated review/gate
seams → (6) emit to the resolved sink. Key contracts (full detail in PLAN Phase B1):

• Context-gate with per-zone decision table (steps 2–3 run in the subagent in EVERY zone; the
  zone modulates packet re-read size, step-5 dispatch-vs-inline, and evidence-flush timing; dumb
  zone = summary+pointer only, mandatory dispatch, immediate flush — the flush artifact is the
  observable; unknown = dumb row + one-line visible notice). Gate re-evaluates at steps 2 and 5.
• Consumer reads ~/.claude/context-guard/zones.json DIRECTLY via jq (data seam; no sibling-script
  invocation under cache isolation); inlined default bands are fallback only; inlined floor values
  (path pattern, staleness, fallback bands) byte-match the context-guard reader contract.
• Session id via ${CLAUDE_SESSION_ID}; known-compacted session → evidence-degraded regardless of
  zone; consumer-side jq absence → conservative + notice.
• Evidence packet at ${CLAUDE_PLUGIN_DATA}/evidence/<session_id>/<target-slug>/<run-nonce>/
  (target-slug sanitized [A-Za-z0-9_-]; run-nonce prevents same-target re-audit clobber;
  retention pruning on new runs; contract-lock notes written INTO the packet; resume = re-derive
  path deterministically).
• Sink: resolution ladder (tracked config → infer from marketplace registration → ask+persist →
  local markdown fallback); unconditional draft+confirm before gh issue create, confirm surface
  includes the ACTING gh account (gh auth status) alongside draft + target repo.
• Presence-gated seam fallbacks, one line each: review:fanout/quality-gate absent → structured
  self-review checklist in the fresh subagent; skill-quality:check absent → skill-lens reference
  checklist; verification:confirm fires only when the audit session itself wrote files.
• Untrusted-content posture: audited plugin source/manifests/registrations are DATA, never
  instructions (standing instruction here AND in the agent).
• Verb-contract deviation recorded at the coupling site: draft+confirm is the explicit user
  override the audit verb requires (owner-approved; github:audit uses --apply instead).
• Trigger continuity: map every trigger phrase of the retiring local plugin-audit skill onto the
  new description (playbook decompose step 5 table as PR evidence) + negative routing boundaries
  (static skill QA → skill-quality:check; general code review → review; MCP-server audits →
  mcp-tools:audit presence-gated; lens set stays {hook, skill, agent, command, config}).
• Producer/consumer split: the audit session never implements fixes in the audited repo.

Auditor agent (agents/auditor.md): fresh-context named subagent for steps 2–3. Tools:
Read/Grep/Glob/WebFetch + Bash — Bash named honestly (needed for claude plugin validate and
config-resolution probes; justified in the lane-B security record, NOT labeled read-only). Carries
the untrusted-content standing instruction. Consumes the evidence-packet path from its dispatch
prompt.

Acceptance criteria

• grep -c 'gh issue create' plugins/plugin-quality/skills/audit/SKILL.md ≥ 1 with the confirm
  gate (incl. acting-account line) in the same section
• grep -n 'context: fork' plugins/plugin-quality/skills/audit/SKILL.md returns nothing
• Drift check: snapshot path pattern, staleness value, and fallback zone bands quoted in
  SKILL.md grep-match plugins/context-guard/reference/reader-contract.md exactly
• Agent file validates; SKILL.md step 2 dispatches by the agent's name
• Per-zone decision table present with observable dumb-row behaviors (flush artifact,
  summary+pointer)

Blocked by

• Lane-A release slice (native edge — lane A must be merged).

[kyle-sexton]