docs: improve CCG skill routing and contracts

Author: tae2089

internal/adapters/inbound/cli/skills_contract_test.go

@@ -176,11 +176,17 @@ func TestProjectSkillsAvoidKnownMisleadingContracts(t *testing.T) {
 		"do not overwrite existing annotations",
 		"requires `ccg build .` first",
 		"refresh flows, communities, or fts",
+		"unknown tags are reported by the parser",
 	}
-	paths, err := filepath.Glob(filepath.Join("..", "..", "..", "..", "skills", "*", "SKILL.md"))
+	paths, err := filepath.Glob(filepath.Join("..", "..", "..", "..", "skills", "*", "**", "*.md"))
 	if err != nil {
 		t.Fatal(err)
 	}
+	topLevelPaths, err := filepath.Glob(filepath.Join("..", "..", "..", "..", "skills", "*", "SKILL.md"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	paths = append(paths, topLevelPaths...)
 	for _, path := range paths {
 		raw, err := os.ReadFile(path)
 		if err != nil {
@@ -195,6 +201,135 @@ func TestProjectSkillsAvoidKnownMisleadingContracts(t *testing.T) {
 	}
 }
 
+func TestProjectSkillsCoverOperationalHazards(t *testing.T) {
+	skillsRoot := filepath.Join("..", "..", "..", "..", "skills")
+	required := map[string][]string{
+		"ccg": {
+			"`replace=false`",
+			"out-of-scope",
+		},
+		"ccg-analyze": {
+			"`max_depth`",
+			"`truncated`",
+			"server-visible",
+		},
+		"ccg-annotate": {
+			"ingestion discards",
+			"unknown-tag",
+		},
+		"ccg-docs": {
+			"`rag.index_dir`",
+			"does not make those files readable",
+		},
+		"ccg-namespace": {
+			"single-namespace",
+		},
+	}
+
+	for name, phrases := range required {
+		t.Run(name, func(t *testing.T) {
+			raw, err := os.ReadFile(filepath.Join(skillsRoot, name, "SKILL.md"))
+			if err != nil {
+				t.Fatal(err)
+			}
+			text := strings.ToLower(string(raw))
+			for _, phrase := range phrases {
+				if !strings.Contains(text, strings.ToLower(phrase)) {
+					t.Errorf("missing operational contract %q", phrase)
+				}
+			}
+		})
+	}
+}
+
+func TestProjectSkillsCentralizeSharedOperationalGuidance(t *testing.T) {
+	skillsRoot := filepath.Join("..", "..", "..", "..", "skills")
+	required := map[string][]string{
+		"ccg": {
+			"## Task Routing and Entry",
+			"## Graph Freshness",
+			"## Scoped Update Safety",
+			"## Response Budget Rule",
+		},
+		"ccg-analyze": {
+			"`ccg` skill's Response Budget Rule",
+		},
+		"ccg-annotate": {
+			"`ccg` skill's Graph Freshness workflow",
+		},
+		"ccg-docs": {
+			"`ccg` skill's Graph Freshness workflow",
+		},
+		"ccg-namespace": {
+			"`ccg` skill's Scoped Update Safety",
+		},
+	}
+	forbidden := map[string][]string{
+		"ccg-analyze": {
+			"## Pagination Defaults",
+		},
+		"ccg-namespace": {
+			"## Safe Scoped Updates",
+			"`replace=false`",
+		},
+	}
+
+	for name, phrases := range required {
+		t.Run(name, func(t *testing.T) {
+			raw, err := os.ReadFile(filepath.Join(skillsRoot, name, "SKILL.md"))
+			if err != nil {
+				t.Fatal(err)
+			}
+			text := string(raw)
+			for _, phrase := range phrases {
+				if !strings.Contains(text, phrase) {
+					t.Errorf("missing centralized-guidance contract %q", phrase)
+				}
+			}
+			for _, phrase := range forbidden[name] {
+				if strings.Contains(text, phrase) {
+					t.Errorf("duplicates core-owned guidance %q", phrase)
+				}
+			}
+		})
+	}
+}
+
+func TestProjectSkillsRoutePipelineAnalysisBeforeSourceVerification(t *testing.T) {
+	skillsRoot := filepath.Join("..", "..", "..", "..", "skills")
+	required := map[string][]string{
+		"ccg": {
+			"algorithm",
+			"feature pipeline",
+			"graph-first",
+		},
+		"ccg-analyze": {
+			"pipeline analysis workflow",
+			"candidate discovery",
+			"symbol identity",
+			"relationship and structure evidence",
+			"call-chain evidence",
+			"runtime semantics",
+			"does not prove runtime order",
+		},
+	}
+
+	for name, phrases := range required {
+		t.Run(name, func(t *testing.T) {
+			raw, err := os.ReadFile(filepath.Join(skillsRoot, name, "SKILL.md"))
+			if err != nil {
+				t.Fatal(err)
+			}
+			text := strings.ToLower(strings.Join(strings.Fields(string(raw)), " "))
+			for _, phrase := range phrases {
+				if !strings.Contains(text, phrase) {
+					t.Errorf("missing pipeline-analysis contract %q", phrase)
+				}
+			}
+		})
+	}
+}
+
 func parseSkillContract(t *testing.T, raw []byte) skillContract {
 	t.Helper()
 	text := string(raw)

skills/ccg-analyze/SKILL.md

@@ -1,8 +1,8 @@
 ---
 name: ccg-analyze
-description: "Analyze code relationships with CCG impact radius, flow tracing, callers/callees, git-diff risk, and affected stored flows. Use when a task asks what a change affects, how a call path flows, who calls a symbol, or which flows recent changes touch. Do not use for simple text lookup, documentation generation, or annotation authoring."
+description: "Analyze algorithms, feature pipelines, and code relationships with CCG impact radius, bounded flow tracing, callers/callees, git-diff risk, affected stored flows, and cross-namespace references. Use when a task asks how a feature or algorithm works, how a pipeline flows, what a change affects, who calls a symbol, whether results were truncated, or which flows recent changes touch. Do not use for simple text lookup, documentation generation, or annotation authoring."
 metadata:
-  version: 1.1.0
+  version: 1.3.1
   openclaw:
     category: "code-intelligence"
     domain: "analysis"
@@ -21,14 +21,33 @@ Graph-based analysis for **change impact, call flow, and recent-change risk**.
 
 | User intent                          | Tool                                             | Notes                                         |
 | ------------------------------------ | ------------------------------------------------ | --------------------------------------------- |
-| "Impact of changing this function?"  | `get_impact_radius` (start with depth 3)         | Widen to depth 5 if too narrow                |
+| "Impact of changing this function?"  | `get_impact_radius` (`depth=3`, `max_depth=3`)   | Raise both bounds to widen                    |
+| "How does this algorithm or feature pipeline work?" | Pipeline workflow below | Graph-first, then source-verified |
 | "Trace call flow from this function" | `trace_flow`                                     | If unexpectedly thin, verify the causes below |
 | "Who calls this function?"           | `query_graph` (callers_of)                       |                                               |
 | "What does this function call?"      | `query_graph` (callees_of)                       |                                               |
 | "Risk of this change"                | `detect_changes` + `get_affected_flows`          | git diff-based                                |
 | "Which repos depend on this one?"    | `list_cross_refs` (direction inbound)            | Annotation `ccg://` refs, materialized        |
 | "Impact across repos?"               | `get_impact_radius` with `cross_namespace: true` | Crosses resolved `ccg://` refs both ways      |
 
+## Pipeline Analysis Workflow
+
+1. **Candidate discovery**: use `search_docs` for a broad module question or
+   `search` for focused symbol and annotation candidates.
+2. **Symbol identity**: confirm each entry point or major stage with `get_node`;
+   continue with qualified names rather than display labels.
+3. **Relationship and structure evidence**: use `query_graph` with
+   `callers_of`/`callees_of` for direct call relations, `children_of` for
+   ownership, and `file_summary` for file composition. This evidence does not
+   prove runtime order.
+4. **Call-chain evidence**: use `trace_flow` from a verified entry point and
+   inspect truncation plus fallback-edge metadata. Treat the result as a bounded
+   static chain, not a runtime trace.
+5. **Runtime semantics**: read the narrowed source files to verify branch
+   conditions, loops, callbacks, data transformations, error paths, and actual
+   ordering. If graph and source disagree, report staleness, unresolved dynamic
+   behavior, or the remaining uncertainty instead of silently choosing one.
+
 ## Thin `trace_flow` Results
 
 One or two returned nodes do not prove an interface-dispatch failure. The start
@@ -48,30 +67,27 @@ Verify in this order:
 Report which explanation is supported; do not label a thin trace as an
 interface boundary without source or edge evidence.
 
-## get_impact_radius Tips
+## `get_impact_radius` Bounds
 
-- **depth 1–2**: direct impact (immediate callers/callees)
-- **depth 3**: recommended default — covers most tasks
-- **depth 5+**: large monorepo propagation. Watch for noise.
+- `depth` requests the BFS hop count; its default is 1.
+- `max_depth` caps `depth`; its default is 3. Setting only `depth=5` still
+  returns at most three hops, so raise both values when widening.
+- Start with `depth=3`, `max_depth=3`, and a bounded `max_nodes`.
+- Inspect response metadata `truncated`, `max_depth`, `max_nodes`, and
+  `returned_nodes` before interpreting the radius as complete.
 
 If results are huge, narrow by namespace, starting symbol, depth, or edge mode
 before concluding the implementation change itself is too broad. High-fanout
 entry points can legitimately have a large radius.
 
-## Pagination Defaults
-
-Use explicit budgets for graph browsing tools when the namespace may be large:
+## Analysis Result Bounds
 
-| Tool | Parameters | Default starting point |
-| ---- | ---------- | ---------------------- |
-| `query_graph` | `limit`, `offset` | `limit=50`, `offset=0` |
-| `list_flows` | `limit`, `offset` | `limit=50`, `offset=0` |
-| `detect_changes` | `limit`, `offset` | `limit=50`, `offset=0` |
-| `get_affected_flows` | `limit`, `offset` | `limit=50`, `offset=0` |
+Use the `ccg` skill's Response Budget Rule for paginated graph tools. Preserve
+per-page namespace labels and errors when accumulating federated results.
 
-Paginated responses include `has_more`. If true, call again with `next_offset`.
-Do not request the max page size first for LLM analysis; use 50 or 100 unless
-the user specifically needs a bulk export.
+`get_impact_radius` and `trace_flow` are bounded rather than paginated. Follow
+their `truncated` metadata by narrowing the start/scope or deliberately raising
+`max_nodes`; do not call a truncated response complete.
 
 ## Accuracy Limits (use with awareness)
 
@@ -80,13 +96,17 @@ the user specifically needs a bulk export.
 - Build-tag-split files → both registered (noise)
 - Fallback call edges improve recall but may add false positives; use strict mode when evidence quality matters more than coverage
 - Treat graph results as a static approximation; cross-check important conclusions against source.
+- `repo_root` for `detect_changes` and `get_affected_flows` must be a
+  server-visible, allowed path. If the MCP server cannot see the client path,
+  report that constraint and use local git/source evidence instead.
 
 ## Boundary
 
 - Start from a verified qualified name; do not infer a symbol from a display label alone.
 - Scope namespace, path, traversal depth, and result limits before widening a query.
 - Separate strict call edges from fallback edges when evidence quality matters.
 - Do not treat missing graph edges as proof that runtime behavior is impossible.
+- Do not hide per-namespace errors or truncation when federated/cross-namespace evidence is partial.
 
 ## Analysis MCP Tools
 
@@ -103,12 +123,14 @@ For detailed parameters, see MCP schema.
 
 ## Prerequisites
 
-Confirm that the selected namespace contains a current graph. Build only when
-the graph is missing or a full rebuild is intentional; after ordinary code
-changes, prefer `ccg update .`. Stored-flow tools also require flow
-postprocessing; an empty flow list is not evidence of no flow until that state
-has been checked. Use the `ccg` skill for freshness and postprocessing guidance.
+Use the `ccg` skill's Graph Freshness workflow before interpreting graph or
+stored-flow results. Stored-flow tools require flow postprocessing; an empty
+flow list is not evidence of no flow until that state has been checked.
 
 ## Completion
 
-Report the analyzed qualified name, namespace, depth/limits, included edge modes, returned impact or flow evidence, and any source-level cross-check used for an important conclusion.
+Report the analyzed qualified names, namespace, discovery query, `query_graph`
+patterns, `trace_flow` bounds and truncation, included edge modes,
+fallback-edge counts, source files used to verify runtime semantics, any
+graph/source disagreement or server-visible path limitation, and the evidence
+supporting important conclusions.

skills/ccg-annotate/SKILL.md

@@ -1,8 +1,8 @@
 ---
 name: ccg-annotate
-description: "Author and refine CCG annotations such as @intent, @domainRule, @sideEffect, @mutates, @index, and @see. Use when adding business meaning to code, improving annotation-aware code or documentation retrieval, fixing annotation lint findings, or documenting operational contracts. Do not use for generated Markdown editing or annotations that merely restate symbol names."
+description: "Author, refine, and verify CCG annotations such as @intent, @domainRule, @sideEffect, @mutates, @index, and @see. Use when adding business meaning to code, improving annotation-aware code or documentation retrieval, fixing annotation lint findings, checking supported tag syntax, or documenting operational contracts. Do not use for generated Markdown editing or annotations that merely restate symbol names."
 metadata:
-  version: 1.1.0
+  version: 1.2.1
   openclaw:
     category: "code-intelligence"
     domain: "annotation"
@@ -18,24 +18,6 @@ metadata:
 Add structured business metadata to source comments so graph search and
 generated documentation can retrieve intent and operational contracts.
 
-## Why Annotations Matter
-
-- Lets full-text retrieval match domain terms recorded in annotations even when symbol names differ
-- Enriches generated docs and DB-backed documentation evidence
-
-## Core Tags
-
-| Tag           | WHAT vs WHY                         | Example                                  |
-| ------------- | ----------------------------------- | ---------------------------------------- |
-| `@intent`     | **WHY this function exists**        | `verify identity before granting access` |
-| `@domainRule` | Specific business rule              | `lock account after 5 failures`          |
-| `@sideEffect` | Real side effects (DB/network/file) | `writes to audit_log`                    |
-| `@mutates`    | Receiver or argument state changes  | `user.FailedAttempts, session.Token`     |
-| `@requires`   | Precondition                        | `user.IsActive == true`                  |
-| `@ensures`    | Postcondition                       | `returns valid JWT with 24h expiry`      |
-| `@index`      | One-line file/package summary       | `User authentication service`            |
-| `@see`        | Related function or CCG ref         | `SessionManager.Create`, `ccg://auth-svc/internal/auth/token.go#ValidateToken` |
-
 ## Retrieval-Aware Tag Selection
 
 Annotations are retrieval features, but they must stay truthful. Use the
@@ -59,8 +41,8 @@ and `node focus` in the appropriate `@index`/`@intent`. Do not add unrelated
 terms just to raise score; broad terms make the wrong files rank higher.
 
 Read [`references/annotation-reference.md`](references/annotation-reference.md)
-when checking the complete tag contract, aliases, multiline behavior, or
-language-specific comment syntax.
+before using less-common tags, aliases, multiline values, typed JSDoc/YARD
+forms, cross-namespace refs, or language-specific comment syntax.
 
 ## Annotation Workflow
 
@@ -105,15 +87,16 @@ For cross-namespace behavior, explain the reason in the semantic tag and put the
 
 ### Step 4: Refresh and verify
 
-```bash
-ccg update .  # ordinary source edits: re-index changed files
-ccg lint      # verify annotation quality and references
-```
+Use the `ccg` skill's Graph Freshness workflow to re-index changed source, then
+run `ccg lint` to verify annotation quality and references.
 
-Use `ccg build .` instead when the graph does not exist, a full rebuild is
-intentional, or incremental recovery is required.
+For representative changed symbols, call `get_annotation` and confirm the
+expected tags and values were actually stored. The parser returns unknown-tag
+warnings to direct callers, but the current ingestion discards that warning
+list and `ccg lint` does not surface it. Treat the reference tag list as an
+allowlist; a green lint result alone does not prove an unknown tag was indexed.
 
-## Quality Rules (this is what really matters)
+## Quality Example
 
 ❌ **Bad annotation**:
 
@@ -164,11 +147,12 @@ expected file is missing, prefer improving the precise `@index`, `@intent`,
 
 | Tool             | Use                                  |
 | ---------------- | ------------------------------------ |
-| `get_annotation` | Fetch annotation/doc tags for a node |
+| `get_annotation` | Verify stored annotation/doc tags for a qualified node |
 
 ## Completion
 
 List annotated files and meaningful tags added or deliberately revised, report
-any existing rationale changed, refresh the graph with update or build as
-appropriate, run retrieval probes for the affected concepts, and report
-`ccg lint` results without claiming unrelated findings were fixed.
+any existing rationale changed, apply the `ccg` Graph Freshness workflow,
+verify representative nodes with `get_annotation`, run retrieval probes for
+affected concepts, and report lint plus any unknown-tag risk or unrelated
+finding without claiming it was fixed.

skills/ccg-annotate/references/annotation-reference.md

@@ -66,4 +66,8 @@ Text before the first tag becomes the summary and context paragraphs. A tag valu
 // @return the authorization decision and audit identifier
 ```
 
-Unknown tags are reported by the parser and are not stored. Keep annotations truthful and omit tags that merely repeat the declaration name.
+Unknown tags are not stored. Direct parser callers receive their names as
+warnings, but the normal ingestion binding currently discards those warnings,
+and `ccg lint` does not report them. Use the table above as an allowlist, verify
+representative stored tags with `get_annotation`, and omit tags that merely
+repeat the declaration name.