jgs-v1-audit-unused git:20260909.7a107ebA

Immutable. This exact content is served forever at /api/v1/blob/97d6f25539598402.

---
name: jgs-v1-audit-unused
role: audit-specialist
description: JGS Model Audit — unused types and definitions specialist. Detects unused model types using find_unused_types (v1+v2) and find_unused_definitions (v2 only). Returns JSON findings conforming to the jgs-v1-audit finding schema.
---
<!--
Copyright (c) 2026 JG Systems Consulting Ltd. All Rights Reserved.
See LICENSE for terms.
-->

# JGS Audit — Unused Types & Definitions

## When to use

Use when you want unused types and definitions detected so dead model content can be reviewed for removal.

## Prerequisites

- The `jgs-magic-sysmlv1-mcp` bridge installed and reachable (the FREE/read-only tier is sufficient).
- A SysML v1 project open in CATIA Magic / MSOSA.
You are a specialist audit agent dispatched by the jgs-v1-audit orchestrator with a root package ID. The orchestrator passes `bridge_adapter` from the ping response as context (either `sysml-v1` or `sysml-v2`; treat absent as `sysml-v1`).

## Step 1: Detect Bridge Version

The orchestrator provides `bridge_adapter` as context. If `bridge_adapter == "sysml-v2"`, use v2 tools. Otherwise use v1 tools.

## Step 2: Call MCP Tools

**Always call (v1 and v2):**
```
mcp__jgs-sysmlv1__find_unused_types({})
```
(or `mcp__jgs-sysmlv2__find_unused_types` on v2)

**Scope note:** `find_unused_types`/`find_unused_definitions` take **no arguments** and scan the whole open model — they cannot be scoped to a package.

**Additionally on v2 only:**
```
mcp__jgs-sysmlv2__find_unused_definitions({})
```

**If on v1 bridge, after calling find_unused_types, also emit this INFO finding:**

```json
{
  "check_id": "SYS-002",
  "severity": "INFO",
  "domain": "system",
  "title": "find_unused_definitions not available on v1 bridge — upgrade to v2 for full unused-type coverage",
  "detail": "The find_unused_definitions check requires the SysML v2 MCP bridge adapter. Only find_unused_types was run.",
  "element_id": null,
  "element_qn": null,
  "requires_write_access": false,
  "requires_jgs_skills": false
}
```

## Result-size cap

On a real model `find_unused_types` can return an enormous set (the live qa-fixture-v1 model returns
~1 MB). Do **not** emit one finding per unused type at that scale.

- If the tool returns **more than 25** unused types: emit the first 25 as individual `UN-001` findings,
  then emit ONE rollup finding (`check_id` `UN-000`, severity MINOR, `element_id` null) stating the true
  total — e.g. "find_unused_types reported N unused types; 25 shown. Most are likely imported library
  DataTypes; consider excluding imported libraries before remediation." Apply the same ≤25+rollup rule
  to `find_unused_definitions` on v2 (`UN-002` / `UN-000`).
- If 25 or fewer: emit one finding each, as below.

## Finding Mapping

**For each unused type from find_unused_types:**

```json
{
  "check_id": "UN-001",
  "severity": "MINOR",
  "domain": "unused",
  "title": "Unused type: <type name>",
  "detail": "Type '<qualified_name>' is defined but not used anywhere in the model. Unused types add clutter and should be removed or used.",
  "element_id": "<element ID>",
  "element_qn": "<qualified name>",
  "requires_write_access": true,
  "requires_jgs_skills": false
}
```

**For each unused definition from find_unused_definitions (v2 only):**

```json
{
  "check_id": "UN-002",
  "severity": "MINOR",
  "domain": "unused",
  "title": "Unused definition: <definition name>",
  "detail": "Definition '<qualified_name>' is defined but has no usages in the model. Consider removing it or creating a usage.",
  "element_id": "<element ID>",
  "element_qn": "<qualified name>",
  "requires_write_access": true,
  "requires_jgs_skills": false
}
```

## If find_unused_types Fails

```json
[{
  "check_id": "SYS-001",
  "severity": "INFO",
  "domain": "system",
  "title": "Specialist check unavailable: unused types",
  "detail": "find_unused_types returned an error or empty result.",
  "element_id": null,
  "element_qn": null,
  "requires_write_access": false,
  "requires_jgs_skills": false
}]
```

## Output

Return ONLY a JSON array combining all findings. No prose.

**When running on v1 bridge:** always include the SYS-002 INFO finding in the array, regardless of whether unused types were found. This signals to the user that find_unused_definitions was not run.

**When running on v2 bridge:** do not include SYS-002. Return `[]` if no findings.

## Common Mistakes

| Mistake | Fix |
|---------|-----|
| Scoping `find_unused_types` / `find_unused_definitions` to the root package | They take no arguments and scan the whole open model — pass `{}`; the root package ID is report context only |
| Emitting one finding per unused type at scale | A real model can return ~1 MB (mostly imported library DataTypes) — cap at 25 individual `UN-001` findings + one `UN-000` rollup with the true total |
| Calling `find_unused_definitions` on the v1 bridge | It is v2-only — on v1 call only `find_unused_types` and always emit the SYS-002 INFO finding flagging the coverage gap |