agent-afk 3.102.1 → 3.104.0

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

@@ -1,23 +1,33 @@
 ---
 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>"
+description: "Grounds capability claims with file-read evidence. Default mode answers meta-capability questions ('what does X enable') with path:line citations. Pass mode: runtime-wiring with a claims list to trace actual runtime execution paths — call sites, DI registration, middleware — and get CONFIRMED/UNVERIFIED/REFUTED verdicts per claim. Blocks sign-off on any non-CONFIRMED claim."
+argument-hint: "<capability question> | mode: runtime-wiring claims: [...]"
 context: load
+failure_modes:
+  - static_artifact_substitution
+  - routing_ambiguity
 ---
 
 ## Trigger
 
-Self-referential meta-capability questions about the current repository, framework, or system. Examples:
-
+**Mode: capability** (default) — Self-referential meta-capability questions about the current repository, framework, or system:
 - "What does this repo enable?"
 - "What are the orchestration patterns available?"
 - "List the available skills."
 - "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.
+**Mode: runtime-wiring** — Claims that require tracing actual execution paths, not static structure:
+- "Verify that middleware Y intercepts all requests."
+- "Confirm plugin Z is loaded on startup."
+- "Validate that feature X is active in production."
+
+Skip both modes for: usage questions ("how do I use X?"), bug reports, feature requests.
+
+---
+
+## Mode: capability (default)
 
-## Procedure
+### 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.
 
@@ -26,30 +36,113 @@ Skip: usage questions ("how do I use X?"), bug reports, feature requests, techni
    - 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: `skills/mint/SKILL.md:5—the mint skill orchestrates end-to-end feature delivery`.
+3. **Build the answer inline.** Embed citations **within claims**, not in a separate appendix. Format: `path/to/file.md:line—<claim context>`.
 
 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`, `hooks/hooks.json`").
+5. **Declare sources read.** Explicitly name which files you read in the response.
 
-## Hard rules
+### 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.
+- Every capability claim must point to a source. Do not summarize without citation.
 - 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
+### 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).
+- Response explicitly lists which files were read.
 - No claims rest on model recall or default knowledge.
 
+---
+
+## Mode: runtime-wiring
+
+Activated when the caller provides a `claims:` list and `mode: runtime-wiring`. Validates capability claims by tracing **actual runtime wiring** — call sites, DI registration, middleware registration, config manifests — not type signatures or import presence.
+
+### Inputs
+
+```
+mode:        runtime-wiring
+claims:      string[]   # natural-language claims to verify (≤20 per batch; see batching)
+entrypoints: string[]   # known runtime entry files (e.g. main.ts, server.ts)
+max_depth:   number     # max call-graph hops per chain (default: 8)
+```
+
+**Pre-flight gate:** If `entrypoints` is empty, abort immediately with `entrypoints_required` — do not dispatch any sub-agents. If `claims` exceeds 20 items, split into batches of 10 and run sequentially; the Qualifier aggregates across batches.
+
+### WireTracer sub-agent (one per claim, run in parallel)
+
+For each claim:
+
+1. Identify the claimed behavior's implementation symbol (function, class, middleware, plugin).
+2. Search for **registration or injection sites** — not import statements. Targets: DI container bindings, `app.use(...)`, `router.register(...)`, config manifests, plugin loaders, factory calls.
+3. Trace forward from the entrypoint, documenting each hop: `{ file, line, symbol, role }`.
+4. If a hop is missing or conditional on an env var / feature flag, record the condition and stop the chain.
+5. Return:
+   - `chain`: ordered `{ file, line, symbol, role }` list
+   - `last_confirmed`: deepest confirmed hop
+   - `gap`: missing-link description, or `null` if complete
+   - `verdict`: `CONFIRMED` | `UNVERIFIED` | `REFUTED`
+
+**Prohibited reasoning — these are NOT evidence of runtime wiring:**
+- "The type implements the interface, therefore it is active."
+- "The import exists, therefore it is called."
+- "The function is exported, therefore it is used."
+
+If no chain can be constructed, return `UNVERIFIED` with `gap: "no_entry_found"`. Max **3 retries** per claim (narrowing search scope each time) before final escalation to `UNVERIFIED`.
+
+### Qualifier sub-agent
+
+Reviews all WireTracer reports. Applies:
+
+- **CONFIRMED** — unbroken chain from entrypoint to invocation site; no conditional gaps left unresolved.
+- **UNVERIFIED** — chain breaks at an identifiable gap; return gap location and a resolution hint.
+- **REFUTED** — positive evidence the symbol is excluded, overridden, or dead-code eliminated at runtime.
+
+If Qualifier verdict disagrees with WireTracer verdict, **Qualifier wins**; discrepancy is logged.
+
+Emits a machine-readable verdict table:
+
+```
+| Claim | Verdict | Last Confirmed Hop | Gap / Evidence |
+|-------|---------|-------------------|----------------|
+| ...   | ...     | ...               | ...            |
+```
+
+### Sign-off gate
+
+Any `UNVERIFIED` or `REFUTED` verdict **blocks downstream review sign-off** and is returned to the caller with the gap location. Only an all-`CONFIRMED` table clears sign-off.
+
+### Orchestration flow
+
+```
+entrypoints_required check → abort if empty
+        │
+claims (batched ≤10 if >20)
+        │
+        ▼
+ [WireTracer × N]  ── parallel, one per claim
+   (≤3 retries per claim, narrowing scope)
+        │
+        ▼
+   [Qualifier]     ── reviews all reports, assigns verdicts
+        │
+   ┌────┴────────┐
+CONFIRMED    UNVERIFIED / REFUTED
+   │                │
+sign-off OK    return gaps, block sign-off
+```
+
+---
+
 ## 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

@@ -1,8 +1,12 @@
 ---
 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."
+description: "Before starting any non-trivial implementation, dispatch a parallel pre-flight reconnaissance wave to triangulate git state, project infrastructure, and prior-session memory. Wave 4 auto-assembles a verified grounding preamble — a session-scoped artifact the orchestrator pastes verbatim into every subsequent sub-agent brief — eliminating stale-worktree reads and silent wrong-path errors before the first edit."
 read-only: true
 context: fork
+failure_modes:
+  - stale_worktree_read
+  - wrong_branch_assumption
+  - path_drift_across_briefs
 ---
 
 ## Sub-agent contract
@@ -10,7 +14,7 @@ context: fork
 
 **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.
+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 and the preamble artifact. 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:
 
@@ -49,5 +53,33 @@ Grep the user's auto-memory store (`~/.claude/projects/-<cwd-slug>/memory/`) + a
 
 Surface the snapshot and stop. The orchestrator then uses these verified facts — not assumptions — to decide the next step. This skill never edits files.
 
+## Wave 4 — Brief Anchor (auto-runs after synthesis)
+
+After the 6-line snapshot is assembled, run a fourth step inline (no additional sub-agent dispatch required): construct the **Brief Anchor** — a path-verified grounding preamble the orchestrator pastes verbatim into every subsequent sub-agent brief.
+
+**Construction procedure:**
+
+1. From the state surveyor output, extract the verified `cwd` (absolute path from `pwd`), `branch` (from `git symbolic-ref --short HEAD`), and `HEAD` SHA (from `git rev-parse HEAD`).
+2. From the infrastructure surveyor output, extract the 2–4 canonical file paths most relevant to the task (primary config file, main entry point, test root, etc.). For each, run `stat <path>` — include the path only if `stat` exits 0. Paths that fail `stat` are omitted; if zero paths survive, set the list to `(none verified)`.
+3. Assemble the preamble block:
+
+```
+## Orchestrator grounding — read this first
+- **cwd**: <absolute path>
+- **branch**: <branch name>
+- **HEAD**: <full SHA>
+- **canonical paths** (stat each on entry; emit GROUNDING_FAILED:<path> and abort if missing):
+  - <verified_path_1>
+  - <verified_path_2>  ← omit line if not applicable
+```
+
+4. Append to the snapshot output under the heading **`## Brief Anchor`** so the orchestrator can copy it directly.
+
+**Orchestrator usage contract:**
+
+- Prepend the Brief Anchor verbatim to every sub-agent brief that reads files, runs `git`/`gh` commands, or references explicit paths. Skip for pure-reasoning tasks (no filesystem reads, no path references).
+- Sub-agents receiving the anchor `stat` each listed path on entry. A missing path returns `GROUNDING_FAILED:<path>` — the orchestrator re-dispatches once with the corrected path. If the retry also returns `GROUNDING_FAILED`, emit `BRIEF_GROUND_ABORT` with both the expected and actual paths **plus the corrective command** the operator should run — `git worktree list` to find the intended checkout, then `cd <correct-worktree>` (or re-invoke the orchestrator from it) — and halt the wave so the operator resolves the worktree mismatch.
+- The anchor is session-scoped: one construction pass per `ground-state` invocation. Do not re-invoke `ground-state` mid-session to refresh it; instead pass the existing anchor through.
+
 **Skip when:**
 Task is Q&A only; single-line fix on an already-identified file; user says "skip pre-flight".