agent-afk 3.80.3 → 3.80.5

package/dist/bundled-plugins/awa-bundled/bundled.test.ts

@@ -0,0 +1,403 @@
+import { describe, it, expect } from 'vitest';
+import { readFileSync, readdirSync, statSync, existsSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// Pinned hashes for the 12 bundled skills shipped under awa-bundled/. These
+// files mirror — but are NOT byte-equal to — corresponding skills in the
+// upstream awa-private repo. Permanent intentional differences include:
+//
+//   - Namespace prefixes (`/awa-dev:contract` upstream → `/contract` here)
+//   - Sub-agent dispatch identifiers (`awa-private:research-agent` → `research-agent`)
+//   - Occasional wording divergence between maintainers
+//
+// Because byte-equality is a false invariant, this file enforces only the
+// pinned-hash snapshot: any unauthored edit to a bundled SKILL.md fails the
+// test until the developer explicitly bumps the hash here. That bump is the
+// forcing function for cross-repo discipline:
+//
+//   *** Workflow when bumping a pinned hash ***
+//   1. Identify what changed in the bundled SKILL.md.
+//   2. Check whether the same change applies upstream in
+//      awa-private/plugins/{awa-dev,awa-private}/skills/<name>/SKILL.md.
+//   3. If yes → open a parallel PR in awa-private. Land both before either
+//      is released.
+//   4. If no → document why the change is bundled-only in the PR description.
+//   5. Only then update the hash below.
+//
+// This convention exists because in November 2026 a critical /ship guardrail
+// (the "Branch lock" + "Never push to main" Hard Rules in commit 63f3ed3)
+// was added to the bundled mirror but never back-ported to awa-private. The
+// deployed plugin therefore lacked the guardrail until the next sync. This
+// test cannot prevent that on its own — but the hash-bump moment forces the
+// developer to look at both copies.
+const PINNED_HASHES = {
+  contract: '2c8a3779f225902f2a8b0af74bfc66c1cdbae58f863d1205c66ce44a14e275b5',
+  'devils-advocate':
+    '84275b097fa3ed270b0b71c87e2dad0366794fd7efc7a47d29abaa85da97f974',
+  gather: 'ec2964fb1f47970fffba6bafacb4dc4f0c76291a7cc0da92ff069a0a986decb4',
+  'ground-claim':
+    '64a4fa0b63467a9a7ae6e61afd68813ff59bfb46a8c5e072feafa15473e36f2a',
+  'ground-state':
+    'ae4c167296e96b640a54cd4cd317e5810894cffff6dac3c022b1433dff003105',
+  // intent-lock is bundled-only (not present in upstream awa-private or
+  // awa-dev). Hash bumps need no parallel PR — document the change in the
+  // commit message instead.
+  'intent-lock':
+    '7a466075e5a64c1145b97aa24b9a6990a3ee1dc818b93c158433e53d7416aef0',
+  parallelize:
+    '74b1a7cf866d630dce0d33323663a8b818f149b5f4d4ef60feba1aeb3472e49b',
+  // refactor is bundled-only (no upstream awa-private counterpart); verbatim
+  // copy of the user-scope /refactor at ~/.afk/skills/.
+  refactor: '23ab4836653159deeafbca45e516af8d43e8c5275535613e36f7bcb2d77de64e',
+  research: '0d04d0a05891ed1b63679e5a0237b743364a6165731a8f694c5584ed7661505f',
+  review: '816ea27cf665be23c67cf887d639d40e1435954f80ceeb43740bcd7f39c205e7',
+  'shadow-verify':
+    '8bce741e55be049a196ed6c71efd0acd271f272a8e2202917c3f1243b875eb33',
+  ship: '4b9a0e40372c36f953ad6d37347e1682950c9825ca5e312fae4e9b320cde975f',
+  // simplify is bundled-only (no upstream awa-private counterpart).
+  simplify:
+    'b863890eead7011c90d4f93b65e5a1533c8f88292728ec771f8b128e9535d996',
+  spec: 'c08f3b4fbe1f585b1e8354a000e0d2d3a48455ad322c7a27112d509aa9698fe7',
+} as const;
+
+type SkillName = keyof typeof PINNED_HASHES;
+
+const SKILLS = Object.keys(PINNED_HASHES) as SkillName[];
+
+// ── Namespace-normalized drift detection ──────────────────────────────────────
+//
+// Workspace root is four levels above __dirname (src/bundled-plugins/awa-bundled).
+// awa-private is a sibling of agent-afk at the workspace root level.
+// This mirrors the pattern used in src/skills/_agents/vendored.test.ts.
+const WORKSPACE_ROOT = join(__dirname, '../../../..');
+
+// Upstream source paths relative to WORKSPACE_ROOT.
+// intent-lock is bundled-only — no upstream comparison row.
+const UPSTREAM_PATHS: Partial<Record<SkillName, string>> = {
+  contract: 'awa-private/plugins/awa-dev/skills/contract/SKILL.md',
+  gather: 'awa-private/plugins/awa-dev/skills/gather/SKILL.md',
+  'ground-claim': 'awa-private/plugins/awa-dev/skills/ground-claim/SKILL.md',
+  'ground-state': 'awa-private/plugins/awa-dev/skills/ground-state/SKILL.md',
+  research: 'awa-private/plugins/awa-dev/skills/research/SKILL.md',
+  ship: 'awa-private/plugins/awa-dev/skills/ship/SKILL.md',
+  spec: 'awa-private/plugins/awa-dev/skills/spec/SKILL.md',
+  'devils-advocate':
+    'awa-private/plugins/awa-private/skills/devils-advocate/SKILL.md',
+  parallelize: 'awa-private/plugins/awa-private/skills/parallelize/SKILL.md',
+  review: 'awa-private/plugins/awa-private/skills/review/SKILL.md',
+  'shadow-verify':
+    'awa-private/plugins/awa-private/skills/shadow-verify/SKILL.md',
+};
+
+// Normalize both copies before comparing, removing all permanent intentional
+// namespace shifts:
+//
+//   /awa-dev:contract  → /contract
+//   /awa-private:ship  → /ship
+//   `awa-dev:ground-state`  → `ground-state`
+//   "awa-private:research-agent" → "research-agent"
+//
+// After normalization, any remaining diff is either real drift (a change
+// landed in one mirror but not the other) or an explicitly allowlisted
+// intentional divergence documented in INTENTIONAL_DIFFS below.
+function normalize(content: string): string {
+  return content
+    .replace(/\/awa-dev:/g, '/')
+    .replace(/\/awa-private:/g, '/')
+    .replace(/`awa-dev:/g, '`')
+    .replace(/`awa-private:/g, '`')
+    .replace(/"awa-dev:/g, '"')
+    .replace(/"awa-private:/g, '"');
+}
+
+// INTENTIONAL_DIFFS: per-skill array of RegExp patterns.  A normalized diff
+// line matching any pattern for that skill is silently accepted — the line is
+// removed from BOTH sides before comparison (each pattern is applied to both
+// the bundled and upstream line arrays independently).
+//
+// *** Adding an entry here requires an inline comment justifying why the
+// divergence is intentional.  "It seems fine" is NOT sufficient — if you
+// cannot defensibly justify it, surface it as unclassified drift in the PR
+// body instead. ***
+const INTENTIONAL_DIFFS: Partial<Record<SkillName, RegExp[]>> = {
+  // devils-advocate, parallelize, shadow-verify:
+  //   Both sides contain a "Sub-agent contract" invocation line immediately
+  //   after the frontmatter block, but they use different plugin namespaces:
+  //
+  //     Bundled:  /contract          (resolves to the co-bundled contract skill)
+  //     Upstream: /agent-workflow-amplifiers:contract  (third-party plugin ns)
+  //
+  //   The `normalize()` function only strips `awa-dev:` and `awa-private:`
+  //   prefixes; it intentionally does NOT touch `agent-workflow-amplifiers:`
+  //   because that is a distinct third-party plugin, not a namespace shift of
+  //   the same plugin.  Both copies invoke the same logical skill — the
+  //   difference is which plugin registry entry resolves the name.  This is
+  //   intentional structural divergence: bundled uses self-contained routing;
+  //   upstream relies on the agent-workflow-amplifiers plugin being installed.
+  //
+  //   Pattern rationale: we match both the bare `/contract` line (bundled side)
+  //   and the namespaced `/agent-workflow-amplifiers:contract` line (upstream
+  //   side) so both are removed before the equality check.
+  'devils-advocate': [
+    // Bundled side: bare /contract invocation (no plugin prefix).
+    /^\/contract$/,
+    // Upstream side: /agent-workflow-amplifiers:contract invocation.
+    /\/agent-workflow-amplifiers:contract/,
+  ],
+  parallelize: [
+    // Same structural divergence as devils-advocate — different contract
+    // skill namespace on bundled vs upstream.
+    /^\/contract$/,
+    /\/agent-workflow-amplifiers:contract/,
+  ],
+  'shadow-verify': [
+    // Same structural divergence as devils-advocate.
+    /^\/contract$/,
+    /\/agent-workflow-amplifiers:contract/,
+  ],
+
+  // research — 1-line divergence, #441 back-port gap:
+  //   "if the research-agent is not available" (bundled) vs
+  //   "if the private plugin is not installed" (upstream).
+  //   Bundled users have no concept of "private plugin" — the research-agent
+  //   IS bundled, so "not available" is the correct user-facing phrase.  The
+  //   upstream wording assumed plugin-based deployment context.  This divergence
+  //   is intentional for bundled context; upstream should ideally adopt a
+  //   context-neutral phrasing.  Flagged for #441 reconciliation.
+  research: [
+    /if the research-agent is not available/,
+    /if the private plugin is not installed/,
+  ],
+
+  // ship — 3 divergences, all #441 back-port gaps:
+  //
+  //   1. Phase 3 heading:
+  //        Bundled: "Phase 3 — Draft commit message."
+  //        Upstream: "Phase 3 — Draft commit message (user-approval gate)."
+  //      The "(user-approval gate)" annotation was added in upstream but not
+  //      back-ported to bundled.  Both copies have the same behavior (no
+  //      approval gate); the annotation is a clarifying label.  Real drift,
+  //      flagged for #441 back-port.
+  //
+  //   2. Phase 3 body prose:
+  //        Bundled: "Print the draft message + file list to the user as
+  //          info-only output, then **immediately** invoke Phase 4.
+  //          **This is not a gate. Do not ask "does this look good?" Do not
+  //          wait for approval.** The user surface is one continuous turn:
+  //          draft → commit → push → PR URL."
+  //        Upstream: "Surface the draft message + file list to the user for
+  //          visibility, then proceed immediately to commit. Do not wait for
+  //          approval."
+  //      Upstream simplified the prose; semantics are identical.  Real drift
+  //      (editorial improvement in upstream not back-ported).  Flagged for #441.
+  //
+  //   3. Phase 5 Never-push-main bullet order:
+  //        Bundled: bullet appears after "Non-fast-forward rejection" bullet.
+  //        Upstream: bullet appears before "Upstream unset" bullet (earlier).
+  //      Same safety rule, different list position.  Real drift (harmless
+  //      reordering).  Flagged for #441 back-port.
+  ship: [
+    // Heading divergence (1 above).
+    /Phase 3 — Draft commit message\./,
+    /Phase 3 — Draft commit message \(user-approval gate\)\./,
+    // Prose divergence (2 above) — match the diverging body paragraph.
+    /Print the draft message \+ file list to the user as info-only output/,
+    /then \*\*immediately\*\* invoke Phase 4\./,
+    /\*\*This is not a gate\. Do not ask "does this look good\?" Do not wait for approval\.\*\*/,
+    /The user surface is one continuous turn: draft → commit → push → PR URL\./,
+    /Surface the draft message \+ file list to the user for visibility/,
+    /then proceed immediately to commit\. Do not wait for approval\./,
+    // Bullet ordering divergence (3 above).
+    /\*\*Never\*\* `git push origin main` \(or `master`\)\. Pushing the feature branch is the only allowed form\./,
+  ],
+
+  // review — namespace-only divergence (back-port landed; #441 closed):
+  //   The bundled review is now the de-namespaced mirror of upstream
+  //   awa-private review. The previously-allowlisted #441 drift —
+  //   Wave 1.5 (citation + absence-claim verification), reviewed-ref
+  //   capture / SHA pinning, the citation-requirement block, the severity
+  //   sort-order block, epistemic scope disclosure, and the ref:<sha>
+  //   finding-schema fields — has been back-ported into bundled; and the
+  //   api-compat reachability + absence-claim grounding gates were ported
+  //   the other way into upstream (griffinwork40/awa-private#40). Both
+  //   copies now carry the full superset, so the only remaining divergence
+  //   is the same contract-namespace shift as devils-advocate / parallelize
+  //   / shadow-verify: bundled uses /contract (self-contained routing),
+  //   upstream uses /agent-workflow-amplifiers:contract (third-party ns).
+  review: [
+    // Bundled side: bare /contract invocation (no plugin prefix).
+    /^\/contract$/,
+    // Upstream side: /agent-workflow-amplifiers:contract invocation.
+    /\/agent-workflow-amplifiers:contract/,
+  ],
+};
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+function computeHash(content: string): string {
+  return createHash('sha256').update(content).digest('hex');
+}
+
+function bundledPath(name: SkillName): string {
+  return join(__dirname, 'skills', name, 'SKILL.md');
+}
+
+function readBundled(name: SkillName): string {
+  return readFileSync(bundledPath(name), 'utf8');
+}
+
+function upstreamAbsPath(name: SkillName): string | null {
+  const rel = UPSTREAM_PATHS[name];
+  if (!rel) return null;
+  return join(WORKSPACE_ROOT, rel);
+}
+
+function upstreamAvailable(name: SkillName): boolean {
+  const abs = upstreamAbsPath(name);
+  return abs !== null && existsSync(abs);
+}
+
+// isAllowlisted returns true if the given line matches any pattern in the
+// skill's INTENTIONAL_DIFFS entry.
+function isAllowlisted(line: string, name: SkillName): boolean {
+  const patterns = INTENTIONAL_DIFFS[name] ?? [];
+  return patterns.some((re) => re.test(line));
+}
+
+// diffLines computes the symmetric difference between two ordered line arrays:
+// lines that are in `aLines` but not `bLines` (bundled-only), and lines that
+// are in `bLines` but not `aLines` (upstream-only).  Returns the two sets.
+// This is intentionally set-based (not position-sensitive) to avoid false
+// positives from harmless reorderings of identical content.
+function diffLines(
+  aLines: string[],
+  bLines: string[],
+): { bundledOnly: string[]; upstreamOnly: string[] } {
+  const aCount = new Map<string, number>();
+  const bCount = new Map<string, number>();
+  for (const l of aLines) aCount.set(l, (aCount.get(l) ?? 0) + 1);
+  for (const l of bLines) bCount.set(l, (bCount.get(l) ?? 0) + 1);
+
+  const bundledOnly: string[] = [];
+  const upstreamOnly: string[] = [];
+
+  for (const [l, cnt] of aCount) {
+    const excess = cnt - (bCount.get(l) ?? 0);
+    for (let i = 0; i < excess; i++) bundledOnly.push(l);
+  }
+  for (const [l, cnt] of bCount) {
+    const excess = cnt - (aCount.get(l) ?? 0);
+    for (let i = 0; i < excess; i++) upstreamOnly.push(l);
+  }
+
+  return { bundledOnly, upstreamOnly };
+}
+
+// ── Test suites ───────────────────────────────────────────────────────────────
+
+describe('bundled skills', () => {
+  describe('pinned-hash snapshot tests', () => {
+    for (const name of SKILLS) {
+      it(`${name} bundled copy matches pinned hash`, () => {
+        const content = readBundled(name);
+        const hash = computeHash(content);
+        expect(hash).toBe(PINNED_HASHES[name]);
+      });
+    }
+  });
+
+  describe('skill inventory invariants', () => {
+    it('covers every bundled skill directory', () => {
+      // Sentinel: if a new skill is added to awa-bundled/skills/ but not
+      // PINNED_HASHES, this test fails — forcing the author to register it.
+      const skillsDir = join(__dirname, 'skills');
+      const entries = readdirSync(skillsDir)
+        .filter((name) => statSync(join(skillsDir, name)).isDirectory())
+        .sort();
+      const registered = [...SKILLS].sort();
+      expect(entries).toEqual(registered);
+    });
+  });
+
+  // ── Namespace-normalized drift comparison ──────────────────────────────────
+  //
+  // Each test below compares a bundled SKILL.md against its upstream
+  // counterpart after normalization (namespace prefixes stripped) and
+  // allowlisting (known intentional divergences removed).
+  //
+  // The test is skipped — NOT failed — when awa-private is not co-located
+  // (e.g. standalone CI clone).  The pinned-hash tests above still guard
+  // against local-only edits.  These tests guard against the cross-repo case:
+  // a change landing in one mirror without being back-ported to the other.
+  //
+  // Workflow when a test fails here:
+  //   1. Is the diff intentional?  Add a justified entry to INTENTIONAL_DIFFS.
+  //   2. Is it real drift?  Land the back-port and re-run.  Then bump the hash.
+  //   3. Is it unclassifiable?  Surface it as unclassified drift in the PR body.
+  describe('namespace-normalized drift comparison (skipped if awa-private not co-located)', () => {
+    // Invariant: for every mirrorable skill, after normalize() and after
+    // removing allowlisted lines, the bundled and upstream copies must be
+    // line-for-line identical.  Any remaining difference is a back-port gap.
+
+    const mirrorableSkills = SKILLS.filter(
+      (s) => s !== 'intent-lock' && s !== 'simplify' && s !== 'refactor',
+    );
+
+    for (const name of mirrorableSkills) {
+      it.skipIf(!upstreamAvailable(name))(
+        `${name}: normalized bundled matches normalized upstream (after allowlist)`,
+        () => {
+          // Contract: upstreamAbsPath is non-null when upstreamAvailable() is true.
+          const abs = upstreamAbsPath(name) as string;
+          const bundledRaw = readBundled(name);
+          const upstreamRaw = readFileSync(abs, 'utf8');
+
+          const bundledLines = normalize(bundledRaw).split('\n');
+          const upstreamLines = normalize(upstreamRaw).split('\n');
+
+          // Compute symmetric difference: lines unique to each side.
+          // Context lines (identical on both sides) are ignored — we only care
+          // about lines that changed.
+          const { bundledOnly, upstreamOnly } = diffLines(
+            bundledLines,
+            upstreamLines,
+          );
+
+          // Remove allowlisted divergences from each side.
+          const unexpectedBundledOnly = bundledOnly.filter(
+            (l) => !isAllowlisted(l, name),
+          );
+          const unexpectedUpstreamOnly = upstreamOnly.filter(
+            (l) => !isAllowlisted(l, name),
+          );
+
+          if (
+            unexpectedBundledOnly.length > 0 ||
+            unexpectedUpstreamOnly.length > 0
+          ) {
+            const lines: string[] = [
+              `--- bundled (normalized, non-allowlisted unique lines)`,
+              `+++ upstream (normalized, non-allowlisted unique lines)`,
+            ];
+            for (const l of unexpectedBundledOnly) lines.push(`-${l}`);
+            for (const l of unexpectedUpstreamOnly) lines.push(`+${l}`);
+
+            throw new Error(
+              `Namespace-normalized drift detected in ${name}.\n` +
+                `  Bundled:  ${bundledPath(name)}\n` +
+                `  Upstream: ${abs}\n` +
+                `  If the diff is intentional, add a justified entry to INTENTIONAL_DIFFS['${name}'].\n` +
+                `  If it is real drift, back-port the change and bump the pinned hash.\n\n` +
+                lines.join('\n'),
+            );
+          }
+        },
+      );
+    }
+  });
+});

package/dist/bundled-plugins/awa-bundled/skills/contract/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: contract
+description: "Reference convention for sub-agent I/O schemas. Loaded by orchestrator skills via /contract and into agents (e.g., qualify) via the `skills:` field."
+---
+
+# Contract
+
+For each sub-agent you plan to dispatch, define a schema before the call:
+
+- `goal` — one-sentence objective
+- `inputs` — data/context the sub-agent receives
+- `artifacts` — named structured fields expected back (not freeform prose)
+- `non_goals` — what the sub-agent must NOT do
+- `failure_modes` — how to report blocked or partial work
+- `domain` *(optional)* — the knowledge domain for this task. Guides how research, specification, and verification adapt. Common values: `software`, `research`, `design`, `business` — but any freeform string works (e.g., `healthcare`, `legal`, `education`). When omitted, infer from context: git repo present → `software`; PDFs/papers/citations in working directory → `research`; design files/brand assets → `design`; financial models/strategy docs → `business`. Default fallback: `software`.
+
+Embed the schema at the top of every sub-agent's prompt and require results in that exact shape. Instruct each sub-agent explicitly: "Return ONLY the schema fields. No preamble, no analysis prose, no explanation — begin your response with the first schema field." When sub-agents return, validate field-by-field. If any artifact is missing, malformed, or wrapped in prose, re-dispatch only the failing sub-agent with the gap cited. Merge only schema-valid responses.
+
+## Epistemic confidence
+
+Recommended for all sub-agents. Add to your return schema:
+
+- `confidence` — low / medium / high — how confident is the sub-agent in the completeness and accuracy of its findings?
+- `coverage_gaps` — what the sub-agent couldn't access, verify, or search (e.g., proprietary databases, paywalled sources, unpublished practitioner knowledge, subjective judgment areas)
+- `boundary_flag` — if the sub-agent hit an epistemic boundary, name it: `non-falsifiable` (claim can't be tested), `low-coverage` (search was limited), `tacit-knowledge` (unwritten knowledge required), `unprecedented` (genuinely novel, no baseline), `time-sensitive` (answer depends on current state), or `none`
+- `recommended_action` — what should happen next: `proceed` (findings solid, move ahead), `human-gate` (pause for human judgment before acting), `re-retrieve` (try different search strategy or sources), `elicit` (generate prompts to validate with domain experts)
+
+This is NOT required — skills that don't return it continue to work. But when present, coverage gaps and boundary flags surface automatically during merge, preventing silent failures.
+
+## Skip if
+
+- Single-agent dispatch
+- Sub-agents returning freeform prose where structure doesn't help merge
+- Exploratory tasks where the output shape isn't known yet

package/dist/bundled-plugins/awa-bundled/skills/devils-advocate/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: devils-advocate
+description: "Adversarially critique a proposal by generating alternatives. Dispatches 3 parallel critics (pragmatist, paranoid, architect lenses) — each invents one alternative approach — then a synthesis step ranks all 4 options and recommends the top choice. Use when a plan, fix, scoping, decomposition, or named recommendation will drive decisions and you want structured alternative-generation before committing. Complements /shadow-verify — that skill re-derives factual claims; this one critiques whether the chosen approach itself is best."
+---
+
+## Sub-agent contract
+/contract
+
+When a proposal — a plan, fix, decomposition, scoping, or named recommendation — will drive user decisions, file edits, or commits, do NOT act on it as-given. Run a devils-advocate critique wave **before** acting, and use the recommendation as input to the decision.
+
+**Wave 2 — Parallel critics (3 fixed lenses, independent):**
+1. Extract the **proposal** (the approach being critiqued) and the **goal** (what the proposal is trying to accomplish). Both should be plain prose. Do NOT include the original proposer's reasoning or evidence — critics must invent alternatives without anchoring on the chosen path.
+2. Dispatch 3 critics in parallel. **Default `subagent_type: "research-agent"`** (mechanically locked to Read/Grep/Glob/WebFetch/WebSearch — cannot Edit/Write/commit). Each critic receives ONLY the proposal + goal + ONE lens:
+   - **pragmatist** — cheapest-path. "What is the cheapest approach that solves the goal? Argue why the proposal may be over-engineered."
+   - **paranoid** — safest-path. "What could go wrong with the proposal? Propose a safer alternative with narrower blast radius."
+   - **architect** — right-level. "Is the proposal addressing the right abstraction level? Propose an alternative one level up (systemic fix) or down (targeted fix)."
+3. Each critic returns `{lens, alternative, tradeoff, strength}` where `strength ∈ {weak, medium, strong}` reflects the critic's confidence that its alternative beats the original.
+
+**Wave 3 — Synthesis (sequential, single agent):**
+1. Dispatch one synthesis agent (same research-agent base). Input: original proposal + goal + all 3 critic outputs.
+2. Rank all 4 options (original + 3 alternatives) along: **cost** (implementation + ongoing), **risk** (blast radius + reversibility), **scope-fit** (how cleanly it solves the stated goal, no more), **goal-fit** (how well it addresses the underlying intent, not just the surface goal).
+3. Recommend ONE top choice with a one-paragraph rationale.
+4. Flag `dissent = true` when ≥2 critics returned `strong` alternatives disagreeing with the recommendation — signals the synthesizer is overruling well-argued dissent, so confidence is low. Include a `dissent_note` summarizing the strongest counter-argument.
+
+**Merge + surface:**
+- Recommendation = `original` → the proposal survived critique; proceed with it.
+- Recommendation ≠ `original`, `dissent = false` → synthesis found a better path; surface the alternative with rationale before acting.
+- `dissent = true` → present the matrix to the user; do not act. Confidence is low.
+
+**When to invoke:**
+Any time a proposal, plan, root-cause + fix, decomposition, or named recommendation will drive user decisions, file edits, commits, or external side-effects. Especially useful when the proposal "feels right" — that's when alternative-generation has the highest value.
+
+**Skip when:**
+- Single-line edits or trivial fixes where alternative space is empty.
+- User explicitly named the chosen approach by name (critiquing a directly-requested action is friction, not signal).
+- An upstream orchestrator already produced comparative output on the same claim-space (`/diagnose`'s hypothesis ranking does not need a second opinion on its hypotheses — though the *final fix* it produces can still benefit).
+
+## Appendix: lens selection (non-binding)
+
+V1 ships three fixed lenses; domain-specific lens packs (software-perf, research-methodology, business-risk) are V2 work. When the proposal's domain is clear, the synthesis agent may weight dimensions accordingly — but the critic lenses themselves remain fixed.
+
+| Lens | Typical alternatives it surfaces |
+|------|----------------------------------|
+| pragmatist | narrower scope, simpler implementation, reuse-over-build |
+| paranoid | smaller blast radius, reversibility, guardrails, staged rollout |
+| architect | systemic fix one level up, targeted fix one level down, different subsystem ownership |

package/dist/bundled-plugins/awa-bundled/skills/gather/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: gather
+description: "Parallel context-gathering for a code area. Use when you need to understand a module, feature, or subsystem and would otherwise read 3+ files sequentially — dispatches two agents in parallel to map structure and test coverage in one wave."
+---
+
+## Dispatch protocol
+
+You MUST emit **exactly two** `agent` tool_use blocks in a **single response turn** — both calls in the same assistant message, before either result arrives. Do not dispatch the second agent in a later turn after seeing the first agent's reply. Do not dispatch three agents. Do not dispatch one.
+
+Correct shape of your next response:
+
+```
+<assistant turn>
+  <tool_use name="agent" id="…"> Structure Agent prompt </tool_use>
+  <tool_use name="agent" id="…"> Test Agent prompt </tool_use>
+</assistant turn>
+```
+
+If you find yourself about to send a single `agent` call and wait, stop — that is the failure mode this skill exists to prevent.
+
+## The two agents
+
+When understanding a task requires reading multiple related files (imports, callers, tests, configs, types), dispatch these two — concurrently, per the protocol above:
+
+1. **Structure Agent** (Explore, thoroughness matched to scope) — Find and read the target file(s), all direct imports, callers, and config references. Return:
+   - `files_read`: absolute paths examined
+   - `call_graph`: how components connect (one paragraph)
+   - `public_interfaces`: function signatures, types, or contracts that govern the area
+   - `entry_points`: where control flow enters
+
+2. **Test Agent** (Explore, "medium") — Find test files that exercise the target area, read them, identify what paths are covered and what's missing. Return:
+   - `test_files`: absolute paths of relevant tests
+   - `coverage_summary`: what behaviors/branches tests exercise
+   - `untested_paths`: code paths with no test coverage
+
+When both return, merge into a unified context map. If either agent's output has gaps (e.g., Structure Agent missed config, Test Agent found no tests), issue one targeted follow-up Read — do not re-dispatch.
+
+### When NOT to use
+
+- You already know exactly which 1–2 files to read — just read them directly.
+- The task is a simple grep or symbol lookup — use Grep or Glob.
+- You're mid-edit and need to check one adjacent file — a single Read is fine.

package/dist/bundled-plugins/awa-bundled/skills/ground-claim/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: ground-claim
+description: "Use when the user asks a meta-capability question about a system/framework/repo ('what does X enable', 'what can this do', 'list the capabilities'). Forces file-read grounding with path:line citations before answering; tags any unverifiable claim as [UNVERIFIED]."
+argument-hint: "<the meta-capability question>"
+---
+
+## Trigger
+
+Self-referential meta-capability questions about the current repository, framework, or system. Examples:
+
+- "What does this repo enable?"
+- "What are the orchestration patterns available?"
+- "List the skills in agent-framework-private."
+- "What capabilities does the plugin provide?"
+- "Show me what the framework can do."
+
+Skip: usage questions ("how do I use X?"), bug reports, feature requests, technical implementation questions.
+
+## Procedure
+
+1. **Extract capability nouns.** From the user's question, identify 2–5 concrete capability categories (e.g., skills, hooks, agents, orchestration patterns, CLI commands, verification methods). Write them down.
+
+2. **Locate and read evidence.** For each capability noun:
+   - Use Glob or Grep to locate source files (e.g., `skills/*/SKILL.md` for skills, `hooks/` for hooks, `agents/` for agents).
+   - Read at least one concrete source file per capability. Record the file path and specific line numbers.
+   - Do not rely on training data, model recall, or session-listing attachments. Evidence must come from Read tool output.
+
+3. **Build the answer inline.** As you write the response, embed citations **within claims**, not in a separate appendix. Format: `path/to/file.md:line—<claim context>`. Example: `agents/qualify.md:5—the qualify agent enforces a force-multiplier rubric`.
+
+4. **Tag ungrounded claims.** If a capability claim cannot be traced to a file read, prefix it with `[UNVERIFIED: what would be needed to verify this]`. Never present an unverified claim without the tag.
+
+5. **Declare sources read.** Explicitly name which files you read in the response (e.g., "Read: `skills/mint/SKILL.md`, `agents/qualify.md`, `hooks/hooks.json`").
+
+## Hard rules
+
+- Do not answer from model recall alone.
+- Do not answer from session-listing attachments without reading the underlying SKILL.md or manifest files.
+- Do not summarize without citation. Every capability claim must point to a source.
+- Do not bury unverified claims. Use the `[UNVERIFIED]` prefix and state the evidence gap.
+- At least one `path:line` citation per named capability.
+
+## Exit criteria
+
+- Response contains ≥1 `path:line` citation per capability mentioned.
+- Every unverified claim is explicitly tagged with `[UNVERIFIED: …]`.
+- Response explicitly lists which files were read (not just quoted).
+- No claims rest on model recall or default knowledge.
+
+## Out of scope
+
+- Usage questions ("how do I use library X?") → normal research.
+- Bug reports → `/diagnose`.
+- Building new capability → `/mint`.
+- Verification of sub-agent findings → `/shadow-verify`.

package/dist/bundled-plugins/awa-bundled/skills/ground-state/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: ground-state
+description: "Before starting any non-trivial implementation (multi-file edits, new features, config changes, anything that writes), dispatch a parallel pre-flight reconnaissance wave to triangulate git state, project infrastructure, and prior-session memory. Produces a 5-line ground-truth snapshot that grounds the implementation and catches wrong-branch edits, assumed-no-CI, stale origin, and missed memory context before the first edit."
+---
+
+## Sub-agent contract
+/contract
+
+**Constraint: read-only reconnaissance.** Surveyors and the synthesizer MUST NOT call `edit_file`, `write_file`, or any mutating bash command (no `git commit`, `git push`, `git checkout`, `mv`, `rm`, file redirection, package installs, etc.). Read-only tools only: `read_file`, `grep`, `glob`, `list_directory`, and read-only bash (`git status`, `git log`, `git diff`, `cat`, `ls`, `find`, etc.).
+
+If the survey reveals a fix that's tempting to apply, **return it as a recommendation in the snapshot** — the orchestrator decides whether to act. Even if the invoking brief sounds prescriptive ("draft the edit", "apply the change"), this skill stops at the snapshot. The orchestrator dispatches a separate implementation step afterward.
+
+Before any multi-step implementation (not single-file fixes, not pure Q&A), dispatch three parallel reconnaissance sub-agents, each with a narrow target. Adapt the first two surveyors to the domain:
+
+**State surveyor** *(domain-aware)*
+
+| Domain | What to survey |
+|--------|---------------|
+| `software` | Current branch, `git log --oneline -5`, `git status -s`, diff-summary vs `origin/<default-branch>`, stash list. Flag: diverged, uncommitted changes, stale upstream. |
+| `research` | Bibliography state (how many papers collected, citation manager in use), data pipeline status (raw data present? processed?), draft status (outline? partial draft? submitted?), publication target and deadline if known. |
+| `design` | Design system state (component library version, Figma project structure), brand guidelines version, current design phase (research? wireframes? high-fidelity? handoff?), recent design changes. |
+| `business` | Financial data freshness (last updated dates on models/reports), market data recency, stakeholder map (who's involved, who decides), current phase (research? proposal? execution?). |
+| *(other)* | Scan for version-controlled artifacts, recent changes, current project phase, and any state that could cause conflicts. |
+
+**Infrastructure surveyor** *(domain-aware)*
+
+| Domain | What to scan |
+|--------|-------------|
+| `software` | CI configs (`.github/workflows/`, `.gitlab-ci.yml`, `Jenkinsfile`), package scripts (`package.json`, `Makefile`, `pyproject.toml`), existing linters/formatters, authoritative config file locations relevant to the task. Return 5-bullet inventory. |
+| `research` | Reference manager (Zotero, Mendeley, .bib files), LaTeX setup (template, build system), data analysis tools (Jupyter, R, Python scripts), collaboration tools (Overleaf, shared drives), submission system requirements. Return 5-bullet inventory. |
+| `design` | Design tools (Figma, Sketch, Adobe), prototyping tools (Framer, Principle), handoff tools (Zeplin, Storybook), asset pipeline (export scripts, optimization), accessibility testing tools. Return 5-bullet inventory. |
+| `business` | Modeling tools (Excel, Google Sheets, financial software), presentation tools (PowerPoint, Google Slides, Pitch), data sources (CRM, analytics platforms), collaboration tools (Notion, Confluence), approval workflows. Return 5-bullet inventory. |
+| *(other)* | Scan for tooling, build/export pipelines, collaboration infrastructure, and config files relevant to the stated domain. Return 5-bullet inventory. |
+
+When domain is unspecified, infer from the working directory contents.
+
+**Memory surveyor**
+Grep the user's auto-memory store (`~/.claude/projects/-<cwd-slug>/memory/`) + any project CLAUDE.md for keywords from the user's current request. Return relevant memory file pointers with 1-line summaries, or "no relevant memory found."
+
+**Synthesize** into a 6-line ground-truth snapshot:
+- Branch: `<current>`, `<clean|diverged>`, upstream: `<fresh|stale>`
+- Recent work: last 3 commits or stash items
+- Infrastructure: CI present? package scripts? authoritative configs for this task
+- Memory hits: file refs or "none"
+- Implementation risks: e.g. "branch is `main`, don't edit directly"; "CI runs on push"; "memory says prior attempt used approach X"
+- Epistemic confidence: `<high|medium|low>` — based on how much state could be verified. Flag if working directory is sparse, if domain is unfamiliar, or if key artifacts may be missing.
+
+Surface the snapshot and stop. The orchestrator then uses these verified facts — not assumptions — to decide the next step. This skill never edits files.
+
+**Skip when:**
+Task is Q&A only; single-line fix on an already-identified file; user says "skip pre-flight".