feat(docs-tools): maximize code-evidence usage across all workflow steps

plugins/docs-tools/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "docs-tools",
-  "version": "0.0.60",
+  "version": "0.0.61",
   "description": "Documentation review, writing, and workflow tools for Red Hat AsciiDoc and Markdown documentation.",
   "author": {
     "name": "Red Hat Documentation Team",

plugins/docs-tools/agents/evidence-classifier.md

@@ -2,7 +2,7 @@
 name: evidence-classifier
 description: Classifies a single documentation requirement by code evidence status. Runs code-finder search for one requirement, applies score thresholds, and returns structured JSON with classification and gap analysis.
 tools: Bash, Read
-maxTurns: 8
+maxTurns: 10
 ---
 
 # Your role
@@ -13,32 +13,38 @@ You produce exactly one JSON object on stdout — no markdown, no commentary, no
 
 ## Procedure
 
-### 1. Build a search query
+### 1. Build search queries
 
-Convert the requirement summary into a natural-language search query that tests for implementation evidence:
+Build 2-3 query reformulations to reduce false-absent results. A single query can miss due to vocabulary mismatch between the requirement description and the code.
 
-- Strip documentation-oriented language ("document how to", "explain the", "describe the")
-- Focus on the implementation artifact (e.g., "Python SDK client library" not "Python SDK documentation")
-- Keep the query specific enough to distinguish from tangential matches
+**Query A — Implementation-focused:** Convert the requirement summary into a search query targeting the implementation artifact. Strip documentation language ("document how to", "explain the") and focus on the code artifact.
+
+**Query B — Term-focused:** Extract the most specific technical terms from the requirement (class names, function names, CLI flags, CRD kinds, API paths) and search for those directly. If the requirement mentions "ModelRegistry REST API", query "ModelRegistry REST API endpoint handler".
+
+**Query C (optional) — Alternate phrasing:** If the requirement uses product-specific terminology that may differ from the code (e.g., "model customization" in docs vs "fine-tuning" in code), add a third query using the likely code-side term.
 
 Examples:
-- REQ "CA bundle configuration support" → query "CA bundle configuration implementation"
-- REQ "Python SDK for notebook-based workflows" → query "Python SDK client library implementation"
-- REQ "Kueue workload scheduling integration" → query "Kueue queue integration workload scheduling"
+- REQ "CA bundle configuration support" → A: "CA bundle configuration implementation" B: "CA bundle TLS certificate path"
+- REQ "Python SDK for notebook-based workflows" → A: "Python SDK client library" B: "SyncClient NotebookClient class"
+- REQ "Kueue workload scheduling integration" → A: "Kueue queue integration workload scheduling" B: "Kueue WorkloadQueue reconciler"
+
+### 2. Run code search and API surface check
 
-### 2. Run code search
+**2a. Run NL search queries:**
 
-Run the search using the REPO_PATH from your prompt's CONFIGURATION block:
+Run each query using the REPO_PATH from your prompt's CONFIGURATION block:
 
 ```bash
 python3 ${CLAUDE_PLUGIN_ROOT}/skills/code-evidence/scripts/find_evidence.py --repo <repo> --query "<query>" --limit 5
 ```
 
-Where:
-- `<repo>` — the REPO_PATH from CONFIGURATION
-- `<query>` — the search query you built in step 1
+Run each query (A, B, and optionally C) separately. Keep the best result set — the one with the highest top score.
+
+**2b. API surface cross-check (when API_SURFACE is provided):**
+
+If your prompt's CONFIGURATION includes an `API_SURFACE_FILE` path, read it. Search for any specific class names, function names, or type names from the requirement in the API surface entities. An exact match in the API surface is strong positive evidence regardless of NL search scores — set `top_score` to at least the grounded threshold if found.
 
-Capture the JSON output from stdout. If the command fails, return an error result (see output format below).
+If the command fails, return an error result (see output format below).
 
 ### 3. Classify the result
 

plugins/docs-tools/agents/requirements-analyst.md

@@ -33,6 +33,7 @@ Your prompt will provide:
 - **REQUIREMENT**: One requirement skeleton (id, title, priority, category, sources, one_line_summary)
 - **RELATED_TICKETS**: Context from the discovery pass (parent, siblings, linked tickets)
 - **RELEASE**: Release/sprint identifier
+- **REPO_PATH**: (optional) Path to the source code repository, when available
 
 ### 1. Fetch detailed source content
 
@@ -63,7 +64,23 @@ For other specs (Confluence, etc.), use WebFetch.
 **Existing documentation sources:**
 Read the file to understand what already exists and what needs updating.
 
-### 2. Web search expansion
+### 2. Source repo enrichment (when REPO_PATH is provided)
+
+**Skip this step if REPO_PATH is not provided in your prompt.**
+
+Use Read, Glob, and Grep to verify and enrich the requirement against the actual codebase:
+
+1. **Verify the feature exists in code.** Search for key terms from the requirement (class names, function names, CLI flags, CRD kinds) using Grep against the repo. If the feature has no trace in the codebase, add a note: `"notes": "No implementation evidence found in repo — requirement may describe planned/aspirational functionality"`
+
+2. **Identify existing documentation.** Check for `README.md`, `CHANGELOG.md`, `docs/` directory, and inline code comments related to the requirement's topic. Note what documentation already exists — the planner uses this for gap analysis
+
+3. **Extract project metadata.** Read the repo root for: primary language (from file extensions or build files), build system (`Makefile`, `go.mod`, `pyproject.toml`, `package.json`), and major directory structure. Add as a `repo_metadata` field in your output. Multiple agents may extract this in parallel — the merge step deduplicates
+
+4. **Note code references.** If you find specific files, functions, or types that implement the requirement, add them to `references` with `"type": "code"`. These feed directly into the code-evidence step's query seeding
+
+Keep this lightweight — read a few targeted files, don't scan the entire repo. The code-evidence step does thorough retrieval later.
+
+### 3. Web search expansion
 
 Build 2-4 targeted search queries from the requirement's topic:
 
@@ -75,7 +92,7 @@ Use WebSearch for each query. Evaluate results for relevance.
 
 **Sanitize:** Do not include raw search queries, result counts, or rankings in your output. Only include curated references (URL, title, relevance note).
 
-### 3. Analyze and produce detailed requirement
+### 4. Analyze and produce detailed requirement
 
 From the gathered sources, produce:
 
@@ -86,7 +103,7 @@ From the gathered sources, produce:
 - **references**: All sources consulted with URLs and notes
 - **web_findings**: Curated external references from web search
 
-### 4. Categorization guidance
+### 5. Categorization guidance
 
 Map the requirement to documentation module types:
 

plugins/docs-tools/skills/docs-orchestrator/SKILL.md

@@ -35,7 +35,7 @@ When displaying available options to the user (e.g., on skill load or when askin
 - `--mkdocs` — Use Material for MkDocs format instead of AsciiDoc. Propagates to the writing step (generates `.md` with MkDocs front matter) and style-review step (applies Markdown-appropriate rules). Sets `options.format` to `"mkdocs"` in the progress file
 - `--draft` — Write documentation to the staging area (`.claude/docs/<ticket>/writing/`) instead of directly into the repo. Uses DRAFT placement mode: no framework detection, no file placement into the target repo. Without this flag, UPDATE-IN-PLACE is the default
 - `--docs-repo-path <path>` — Target documentation repository for UPDATE-IN-PLACE mode. The docs-writer explores this directory for framework detection (Antora, MkDocs, Docusaurus, etc.) and writes files there instead of the current working directory. Propagates to `writing` and `create-merge-request` steps (mapped to their internal `--repo-path` flag). **Precedence**: if both `--docs-repo-path` and `--draft` are passed, `--docs-repo-path` wins — log a warning and ignore `--draft`
-- `--source-code-repo <url-or-path>...` — Source code repository/repositories for code evidence and requirements enrichment (space-delimited, one or more). Accepts remote URLs (https://, git@, ssh:// — each shallow-cloned to `.claude/docs/<ticket>/code-repo/<repo_name>/`) or local paths (used directly). The first repo is treated as primary; additional repos are returned as `additional_repos` in the result. Passed to requirements, code-evidence, and writing steps (mapped to their internal `--repo` flag). Without `--pr`, the entire repo is the subject matter; with `--pr`, the PR branch is checked out on the primary repo so code-evidence reflects the PR's state. Takes highest priority in source resolution, overriding `source.yaml` and PR-derived URLs
+- `--source-code-repo <url-or-path>...` — Source code repository/repositories for code evidence and requirements enrichment (space-delimited, one or more). Accepts remote URLs (https://, git@, ssh:// — each shallow-cloned to `.claude/docs/<ticket>/code-repo/<repo_name>/`) or local paths (used directly). The first repo is treated as primary; additional repos are returned as `additional_repos` in the result. Passed to requirements, code-evidence, writing, and technical-review steps (mapped to their internal `--repo` flag). Without `--pr`, the entire repo is the subject matter; with `--pr`, the PR branch is checked out on the primary repo so code-evidence reflects the PR's state. Takes highest priority in source resolution, overriding `source.yaml` and PR-derived URLs
 - `--create-jira <PROJECT>` — Create a linked JIRA ticket in the specified project after the planning step completes. Runs the standalone `docs-workflow-create-jira` workflow (use `--workflow workflow-create-jira`). Requires `JIRA_API_TOKEN` to be set
 - `--create-merge-request` — Create a branch, commit, push, and open a merge request or pull request after reviews complete. Activates the `create-merge-request` workflow step (guarded by `when: create_merge_request`). Off by default
 
@@ -67,9 +67,12 @@ When displaying available options to the user (e.g., on skill load or when askin
 # Custom workflow YAML
 /docs-orchestrator PROJ-123 --workflow quick
 
-# Code-evidence workflow — requires a source repo
+# Code-evidence workflow — auto-discovers repo from JIRA, or pass explicitly
+/docs-orchestrator PROJ-123 --workflow code-evidence
+
+# Code-evidence workflow — explicit repo (overrides auto-discovery)
 /docs-orchestrator PROJ-123 \
-  --workflow workflow-code-evidence \
+  --workflow code-evidence \
   --source-code-repo https://github.com/org/operator
 ```
 
@@ -159,9 +162,13 @@ Read the YAML file and extract the ordered step list. Each step has: `name`, `sk
 
 If the YAML includes a top-level `workflow.requires` list, check each condition **before evaluating steps or running anything**:
 
-- `has_source_repo` → a source repo must be resolvable. The pre-flight resolution script tries CLI args, `source.yaml`, PR-derived, and JIRA ticket discovery (git links and auto-discovered PRs) in priority order. If **none** of these yield a source repo, **STOP** immediately with: `"This workflow requires a source code repository. No repo could be discovered from the JIRA ticket. Pass --source-code-repo <url-or-path> or --pr <url>."`
+- `has_source_repo` → a source repo must be resolvable. The pre-flight resolution script tries all sources in priority order: CLI `--source-code-repo`, `source.yaml`, `--pr`-derived, and JIRA ticket discovery (git links and auto-discovered PRs). If **none** yield a source repo, **STOP** immediately with: `"This workflow requires a source code repository. No repo could be discovered from the JIRA ticket. Options: (1) re-run with --source-code-repo <url-or-path>, (2) re-run with --pr <url>, (3) create .claude/docs/<ticket>/source.yaml with a repo: field, or (4) link PRs to the JIRA ticket and re-run."`
+
+Unlike `when` (which makes individual steps conditional), `requires` is a workflow-level precondition — the entire workflow fails if a required condition is not met. This prevents users from running a code-evidence workflow without a repo and only discovering the problem after requirements and planning have already completed.
 
-Unlike `when` (which makes individual steps conditional), `requires` is a workflow-level precondition — the entire workflow fails if a required condition is not met. This prevents users from running a code-evidence-heavy workflow without a repo and only discovering the problem after requirements and planning have already completed.
+The `has_source_repo` precondition supports two modes:
+- **Explicit:** User passes `--source-code-repo` → guaranteed grounding against the specified repo
+- **Auto-discovered:** User passes only a JIRA ticket → pre-flight discovers the repo from JIRA git links and linked PRs
 
 ### 4. Evaluate `when` conditions
 
@@ -363,6 +370,7 @@ Build the args string for the step skill. The orchestrator maps its user-facing
    - `scope-req-audit`: `--repo <repo_path> [--grounded-threshold <float>] [--absent-threshold <float>]`
    - `code-evidence`: `--repo <repo_path> [--scope-include <globs>] [--scope-exclude <globs>] [--reindex]` — scope globs come from `source.yaml` or `options.source.scope` in the progress file
    - `writing`: `--format <adoc|mkdocs> [--draft] [--repo <repo_path>] [--repo-path <path>]`
+   - `technical-review`: `[--repo <repo_path>]`
    - `style-review`: `--format <adoc|mkdocs>`
    - `create-merge-request`: `[--draft] [--repo-path <path>]`
 
@@ -508,13 +516,5 @@ Same as new session. The progress file shows which steps completed and which fai
 
 ### Requirements-analyst agent: repo-aware analysis
 
-When `--source-code-repo` is passed to the requirements step, the `requirements-analyst` agent should use the repo to enrich its analysis. This is **not yet implemented** — the requirements step currently accepts `--source-code-repo` but the agent does not act on it. Future work:
-
-- Scan the repo's `README.md`, `CHANGELOG.md`, and `docs/` directory for existing documentation
-- Note what documentation already exists and what gaps remain (feeds directly into the planning step's gap analysis)
-- Extract project metadata: language, build system, major dependencies, directory structure
-- Identify existing code examples, tutorials, or quickstart guides that the writer could reference or update rather than recreate
-- If no `--pr` was provided, use the repo structure itself to identify the key components and features that need documentation
-
-This work requires changes to the `requirements-analyst` agent definition (`agents/requirements-analyst.md`), not just the step skill.
+When `--repo` is passed to the requirements step, the `requirements-analyst` agent uses the repo to enrich its analysis: verifying features exist in code, identifying existing documentation, extracting project metadata, and noting code references for downstream steps. See `agents/requirements-analyst.md` step 2 (Source repo enrichment).
 

plugins/docs-tools/skills/docs-orchestrator/defaults/docs-workflow-code-evidence.yaml

@@ -1,6 +1,6 @@
 workflow:
   name: docs-workflow
-  description: Code-evidence-grounded documentation workflow. Requires a source code repository. Adds scope-req-audit and code-evidence steps to classify requirements by implementation status and ground documentation in actual source code.
+  description: Code-evidence-grounded documentation workflow. Adds scope-req-audit and code-evidence steps to classify requirements by implementation status and ground documentation in actual source code. Source repo is resolved via explicit --source-code-repo, JIRA auto-discovery, or PR-derived URLs. Fails if no repo can be resolved.
 
   requires:
     - has_source_repo

plugins/docs-tools/skills/docs-orchestrator/schema/step-result-schema.md

@@ -121,7 +121,8 @@ All sidecars share these fields:
     "minor": 3,
     "sme": 2
   },
-  "iteration": 1
+  "iteration": 1,
+  "code_grounded": true
 }
 ```
 
@@ -134,6 +135,7 @@ All sidecars share these fields:
 | `severity_counts.minor` | integer | Minor issues found | Orchestrator |
 | `severity_counts.sme` | integer | Issues requiring SME verification | Orchestrator |
 | `iteration` | integer | Which iteration of review this represents (1-based) | Orchestrator |
+| `code_grounded` | boolean | Whether the code-grounded pre-scan ran (source repo was available and `grounded_review.py` succeeded) | Informational |
 
 ### style-review