Sync ia skill with upstream (v1.0.2)

.agents/plugins/marketplace.json

@@ -8,7 +8,7 @@
   "plugins": [
     {
       "name": "ia",
-      "version": "1.0.1",
+      "version": "1.0.2",
       "description": "IBM i Impact Analysis — dependency tracing, field impact, call hierarchy, program documentation.",
       "source": "./"
     }

.claude-plugin/marketplace.json

@@ -8,7 +8,7 @@
   "plugins": [
     {
       "name": "ia",
-      "version": "1.0.1",
+      "version": "1.0.2",
       "description": "IBM i Impact Analysis — dependency tracing, field impact, call hierarchy, program documentation.",
       "source": "./"
     }

.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "ia",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "IBM i Impact Analysis — dependency tracing, field impact, call hierarchy, program documentation.",
   "homepage": "https://github.com/programmersio-ibmi/skills",
   "license": "MIT",

.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "ia",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "IBM i Impact Analysis for coding agents.",
   "homepage": "https://github.com/programmersio-ibmi/skills",
   "license": "MIT",

.cursor-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "ia",
   "displayName": "iA — IBM i Impact Analysis",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "IBM i Impact Analysis — dependency tracing, field impact, call hierarchy, program documentation.",
   "publisher": "programmersio",
   "homepage": "https://github.com/programmersio-ibmi/skills",

.github/plugin/marketplace.json

@@ -8,7 +8,7 @@
   "plugins": [
     {
       "name": "ia",
-      "version": "1.0.1",
+      "version": "1.0.2",
       "description": "IBM i Impact Analysis — dependency tracing, field impact, call hierarchy, program documentation.",
       "source": "./"
     }

CHANGELOG.md

@@ -5,6 +5,14 @@ All notable changes to this project are documented here.
 The format is loosely based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and the project uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.0.2] — 2026-06-02
+
+### Changed
+
+- Synced the `ia` skill with the latest upstream guidance. Adds **Rule Zero** (always query iA, never the workspace), **Rule One** (uppercase every name), **Rule Two** (empty result = not found, never substitute), and a **Routing Pitfalls** table that steers each kind of ask to the right tool the first time.
+- Added SQL long↔short name guidance (`ia_sql_table_names`) so field-impact and where-used queries resolve long table/column names to their 10-char system names before lookup.
+- Documented the new `ia_circular_deps` tool (SELF + MUTUAL cycle detection) and refreshed the program-documentation workflow, playbooks, and query flows to match the current tool set (now 51 tools).
+
 ## [1.0.1] — 2026-06-02
 
 ### Removed

gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "ia",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "IBM i Impact Analysis — dependency tracing, field impact, call hierarchy, program documentation.",
   "contextFileName": "GEMINI.md"
 }

package.json

@@ -1,6 +1,6 @@
 {
   "name": "ia-tools-skill",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "IBM i Impact Analysis — dependency tracing, field impact, call hierarchy, program documentation.",
   "license": "MIT",
   "type": "module",

plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "ia",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "IBM i Impact Analysis — dependency tracing, field impact, call hierarchy, program documentation.",
   "publisher": "programmersio",
   "homepage": "https://github.com/programmersio-ibmi/skills",

skills/ia/SKILL.md

@@ -7,7 +7,40 @@ description: Guide for using iA by programmers.io MCP tools to analyze IBM i pro
 
 iA by [programmers.io](https://programmers.io/ia/) pre-parses IBM i source (RPG, CL, COBOL, DDS) into a queryable repository accessed through the `ia_*` MCP tools.
 
-**Goal:** Answer most questions in 1-2 tool calls. Consult [quick-reference.md](references/quick-reference.md) for tool selection, [tool-catalog.md](references/tool-catalog.md) for the full 50-tool list.
+**Goal:** Answer most questions in 1-2 tool calls. Consult [quick-reference.md](references/quick-reference.md) for tool selection, [tool-catalog.md](references/tool-catalog.md) for the full 51-tool list.
+
+## Rule Zero — Always Query iA, Never the Workspace
+
+Never search the local workspace or filesystem for IBM i members, objects, or source. The programs you are asked about do **not** live in the editor's files — they live in the iA repository. For any "show me / find / specs for `<member>`" request, resolve through the `ia_*` tools (`ia_member_lookup` / `ia_object_lookup`, then `ia_rpg_source` / `ia_cl_source`). Do not grep the workspace and do not report "not found" until iA itself returns nothing.
+
+## Rule One — Always UPPERCASE Object/Member/File Names
+
+IBM i stores every object, member, file, field, program, and procedure name in **UPPERCASE**. Always upper-case names before calling any `ia_*` tool, no matter how the user typed them (`iAdepRpt` → `IADEPRPT`, `custmast` → `CUSTMAST`). The tools now also upper-case name parameters in SQL as a safety net, but normalize on your side too — a lower/mixed-case name that slips through matches nothing.
+
+## Rule Two — Empty Means Not Found; Never Substitute
+
+If a tool returns zero rows for a name you passed, the object/file/field **does not exist** in the repository (under that name). Report the negative plainly ("`ITMMAST` / `ITEMNO` was not found"). Do **not** silently swap in a similarly-named file and present its results as if they answered the question — that produces the wrong analysis. If you suspect a typo, use `ia_object_lookup`/`ia_member_lookup` with `%` wildcards to suggest close matches, and let the user confirm.
+
+## Routing Pitfalls (pick the right tool the first time)
+
+| Ask | Use | Not |
+|-----|-----|-----|
+| Calculation / F / D specs for member X | `ia_rpg_source(member_name=X, source_spec=C/F/D)` | workspace search; `ia_program_files` |
+| File declarations (F-specs) in X | `ia_rpg_source(member_name=X, source_spec='F')` | `ia_program_files` — that's the resolved file-access map, not source lines |
+| Find a BIF like `%CHECK` / `%SCAN` | `ia_rpg_source_search(search_text='%CHECK')` — pass the literal `%`; it now matches the BIF exactly | `ia_find_object_usages` (object cross-ref, not source text) |
+| Join logical files over file X | `ia_join_logical_files(file_name=X)` | `ia_file_dependencies` — lists dependents but not the join structure |
+| Lifecycle / when modified for X (library unknown) | `ia_object_lifecycle(object_name=X)` — library & type are optional | passing the iA repo library as the object library |
+| List **all** display files in the repo | `ia_object_list(object_type='*FILE', object_attribute='DSPF')` | `ia_find_object_usages` — it's where-used for ONE object, not an inventory; there is no `*DSPF` type |
+| Every program a menu launches (e.g. CASEMNU) | `ia_call_hierarchy(program_name=MENU, direction='CALLEES')` — now follows `*MENU`→`*PGM` | assuming menus aren't tracked |
+| List the subroutines in program X | `ia_subroutines(member_name=X)` — adds usage_count + line_number (dead-sub detection) | `ia_program_detail` SUBROUTINES section — omits usage count and line number |
+| Parameters passed by program X | `ia_call_parameters(member_name=X)` — one row per parameter per call site; same callee on different `call_line`s = multiple call sites, not duplicates | reading repeated rows as dupes |
+| Where-used / field impact for a SQL **long** name (e.g. `CUSTOMER_MASTER`, column `ERROR_MESSAGE`) | `ia_sql_table_names(name_pattern=X)` → take `system_short_name`, then `ia_find_object_usages` / `ia_file_field_impact_analysis` on that 10-char name | passing the long name straight to where-used — it matches only the 10-char system name and caps input at 10 chars, so it silently returns nothing |
+| Long↔short name of a SQL table/column vs a procedure/function | `ia_sql_table_names` (tables + columns) | `ia_sql_names` — that one covers routines (procedures/functions) only |
+| Which library / type is **object** X | `ia_object_lookup(object_name=X)` — compiled objects (`*PGM`/`*FILE`/`*SRVPGM`…). If empty, X may be a source-only member → fall back to `ia_member_lookup(member_name=X)` | `ia_member_lookup` first for a compiled object |
+| Member X "not found" by `ia_member_lookup` | pass the **bare** name (`IORDV11`) — exact names now resolve; only add `%` for prefix/substring search | concluding it's missing — a name shorter than 10 chars used to fail silently |
+| `ia_rpg_source` returns nothing | confirm `MEMBER_TYPE` first (`ia_member_lookup`): CL/CLLE/CLP → `ia_cl_source`; COBOL isn't in the RPG tables. Empty ≠ missing | assuming the source doesn't exist |
+| "Obsolete / unreferenced objects" | `ia_unused_objects` — source physical files (QRPGLESRC, QCLSRC…) are already excluded; remaining `*FILE` rows show `OBJECT_ATTRIBUTE` | treating every unreferenced `*FILE` as dead — DSPF/PRTF and SQL-only tables can be false positives |
+| Data files vs source files in a library | `ia_object_list(object_attribute='PF-DATA')` for data files, `'PF-SRC'` for source files; plain `PF` returns both with a `pf_kind` label | assuming a source library (QRPGLESRC etc.) has data files — it usually has none |
 
 ## Top 10 Tools (80% of Queries)
 
@@ -38,7 +71,9 @@ iA by [programmers.io](https://programmers.io/ia/) pre-parses IBM i source (RPG,
 
 ### Field Impact Analysis (3-4 calls, synthesize into one response)
 
-1. `ia_file_field_impact_analysis(file_name=X, field_name=Y)` → Direct PF references
+> If `X`/`Y` is a SQL **long** name (a `CREATE TABLE`/column long name, often >10 chars), resolve it first: `ia_sql_table_names(name_pattern=X)` → use the returned `system_short_name`/`column_short_name`. The PF and field cross-references are keyed by the 10-char system name.
+
+1. `ia_file_field_impact_analysis(file_name=X, field_name=Y)` → Direct PF references. **If this returns empty, the file/field doesn't exist — say so (Rule Two), don't analyze a different file.**
 2. `ia_file_dependencies(file_name=X)` → LFs/indexes/views over PF
 3. `ia_find_object_usages` on every STRUCTURAL `*FILE` from step 1 (parallel)
 4. `ia_find_object_usages(object_name=<each_LF>)` from step 2 (parallel)
@@ -47,14 +82,14 @@ Present as four sections: **Direct (NEEDS_CHANGE)**, **Direct (NEEDS_RECOMPILE)*
 
 ## When to Chain
 
-**DO chain:** `*SRVPGM` in results (amplifier — check what binds to it), field impact (run all steps).
+**DO chain:** `*SRVPGM` in results (amplifier — check what binds to it), field impact (run all steps), a **SQL long name** before any system-name tool (resolve via `ia_sql_table_names` → use the `system_short_name`).
 
 **DON'T chain:** Simple counts (count your results), every `*PGM` (only critical ones), `ia_member_lookup` just for location.
 
 ## Parameter Rules
 
-- Object/member names: **10-char uppercase** (`'CUSTMAST'`)
-- `object_type`: Star-prefixed (`*PGM`, `*SRVPGM`, `*FILE`, `*DSPF`)
+- Object/member/file/field names: **uppercase** (`'CUSTMAST'`) — see Rule One
+- `object_type`: Star-prefixed (`*PGM`, `*SRVPGM`, `*FILE`, `*CMD`, `*MENU`). **Display files are `*FILE` + attribute `DSPF`** — there is no `*DSPF` object type
 - Wildcard `*ALL` = no filter (default for optional params)
 - Only `ia_object_lookup` supports `%` wildcards in names
 
@@ -63,8 +98,8 @@ Present as four sections: **Direct (NEEDS_CHANGE)**, **Direct (NEEDS_RECOMPILE)*
 | Value | Meaning |
 |-------|---------|
 | `*SRVPGM` in results | Amplifier — always check dependents |
-| `*DSPF` in results | User-facing screen — flag prominently |
-| Empty results | May be scheduler-invoked or external |
+| `DSPF` attribute on a `*FILE` row | User-facing display file — flag prominently (it is a `*FILE`, not a `*DSPF` type) |
+| Empty results | Object/file not found under that name (Rule Two), or scheduler-invoked / external |
 | `REFERENCE_SOURCE = O` | Detected from compiled object |
 | `REFERENCE_SOURCE = S` | Detected from source code |
 | `REFERENCE_USAGE = I` | Implicit (via binding directory) |
@@ -102,7 +137,7 @@ Do not attempt to diagnose server-side issues or retry indefinitely.
 | Need | Load |
 |------|------|
 | Tool selection unclear | [quick-reference.md](references/quick-reference.md) |
-| Full 50-tool list | [tool-catalog.md](references/tool-catalog.md) |
+| Full 51-tool list | [tool-catalog.md](references/tool-catalog.md) |
 | Complex analysis chains | [query-flows.md](references/query-flows.md) |
 | Analysis playbooks | [playbook.md](references/playbook.md) |
 | Program documentation | [program-documentation.md](references/program-documentation.md) |

skills/ia/references/index.md

@@ -8,7 +8,7 @@ This index guides progressive loading of skill references. Load only what you ne
 |------------|-----------|-----------------|
 | **Simple lookup** ("what uses X?", "find object") | SKILL.md only | — |
 | **Tool selection unclear** | + [quick-reference.md](quick-reference.md) | Decision tree + intent mapping |
-| **Need full tool list** | + [tool-catalog.md](tool-catalog.md) | All 50 tools by category |
+| **Need full tool list** | + [tool-catalog.md](tool-catalog.md) | All 51 tools by category |
 | **Complex analysis** (field impact, call chains) | + [query-flows.md](query-flows.md) | Optimal tool sequences |
 | **Troubleshooting / edge cases** | + [playbook.md](playbook.md) | Analysis playbooks |
 | **Program documentation** | + [program-documentation.md](program-documentation.md) | 8-step workflow |
@@ -18,7 +18,7 @@ This index guides progressive loading of skill references. Load only what you ne
 | File | Purpose | Load When |
 |------|---------|-----------|
 | [quick-reference.md](quick-reference.md) | Tool selection by user intent | Tool choice unclear |
-| [tool-catalog.md](tool-catalog.md) | Full 50-tool inventory | Need specific tool details |
+| [tool-catalog.md](tool-catalog.md) | Full 51-tool inventory | Need specific tool details |
 | [query-flows.md](query-flows.md) | Optimal tool chains | Complex multi-step analysis |
 | [playbook.md](playbook.md) | Playbooks + chaining rules | Edge cases, troubleshooting |
 | [program-documentation.md](program-documentation.md) | Spec generation workflow | "Document program X" |

skills/ia/references/playbook.md

@@ -27,7 +27,7 @@
 | Suspect file routing | `ia_file_overrides`, `ia_override_chain` | Detect OVRDBF redirection |
 | Stale / stale-looking object | `ia_object_lifecycle` | Check last-used date and days-used count |
 | Large or rarely-used objects (capacity/cleanup) | `ia_obj_size` | Rank by size, filter by usage_category (Never/Rare) |
-| High-risk program to refactor | `ia_code_complexity` | Get IF/DO/SQL/GOTO counts and line totals |
+| High-risk program to refactor | `ia_code_complexity` | Rank by weighted score (`GOTO×5 + CAB×5 + IF×1 + SQL×0.5`), not TOTAL_LINES — large+linear is healthier than small+spaghetti |
 | Circular call suspicion | `ia_circular_deps` | Detect two-way call pairs |
 | Cleanup candidates | `ia_unused_objects` | Objects with zero references |
 
@@ -84,14 +84,22 @@ Call `ia_program_variables` → Group: standalone fields, DS subfields (likely D
 `ia_file_dependencies(file_name=X)` → Returns LFs, indexes, views, MQTs over the physical, bifurcated by `SQL_OBJECT_TYPE` (INDEX/VIEW/TABLE/MQT/DDS_LF). Use `dependent_kind` to filter → Chain `ia_find_object_usages` on each logical of interest to find programs referencing it.
 
 ### P8: "Find dead code"
-**Compiled objects:** `ia_unused_objects` for objects with zero refs → `ia_object_lifecycle` to confirm last-used date → `ia_dashboard` to cross-check category → Always flag members that may be scheduler-invoked.
+**Compiled objects (5-step chain — don't stop at step 1):**
+1. `ia_unused_objects(object_type='*PGM')` — baseline zero-reference candidates.
+2. `ia_cl_jobs(call_type='SBMJOB')` — every CL-side scheduled program. **Subtract** these `called_program` names from step 1.
+3. `ia_rpg_source_search(search_text='SBMJOB')` — RPGs that submit jobs (less common but real). Subtract any matches.
+4. `ia_object_lifecycle` on the survivors — confirm `LASTUSED_DATE` is old.
+5. `ia_find_object_usages` as a final sanity check before recommending DELETE — `LASTUSED_DATE` can lag for cold-stored objects and `ia_unused_objects` misses QCMDEXC dynamic calls.
+
+**Why the chain:** Step 2 typically removes ~40-50% of step 1's candidates — they ARE used, just scheduler-invoked. Never recommend DELETE on lifecycle or unused-objects alone; always surface the QCMDEXC caveat as an unresolved residual risk.
+
 **Orphaned sources:** `ia_uncompiled_sources` for source members never compiled into objects → Check LAST_CHANGED date to identify abandoned development.
 
 ### P9: "Where does this program actually write?"
 `ia_file_overrides` for the member → If overrides exist, also run `ia_override_chain` → Combine with `ia_find_object_usages` on each resolved target file to confirm downstream impact.
 
 ### P10: "What programs include this copybook?" (Copybook Impact)
-`ia_copybook_impact(copybook_name="CUSTDS")` → Returns all members with /COPY directive + line numbers → Group by member_type (RPGLE, SQLRPGLE, CBLLE) → Flag: high count = high-risk copybook change.
+`ia_copybook_impact(copybook_name="CUSTDS")` → Returns all members with /COPY directive + line numbers → Group by member_type (RPGLE, SQLRPGLE, CBLLE) → **Present the result as an explicit recompile list** (one member per line) so the user can pipe it into their build. Flag SQLRPGLE consumers highest risk (embedded SQL may shift behavior on field-layout change); high total count = phased recompile.
 
 ### P11: "What does this service program export?" (API Surface)
 `ia_srvpgm_exports(object_name="MYSRVPGM", procedure_type="EXPORT")` → Lists all exported procedures → Chain `ia_procedure_xref` on specific procedures to find callers → For parameter signatures, use `ia_procedure_params`.
@@ -111,6 +119,9 @@ Call `ia_program_variables` → Group: standalone fields, DS subfields (likely D
 ### P16: "Resolve SQL long name to system name"
 `ia_sql_names(name_pattern="STORE%")` → Maps SQL long names ↔ 10-char system names → Essential for SQL procedure/function analysis.
 
+### P16b: "Resolve a SQL long table/column name (and trace its usage)"
+`ia_sql_table_names(name_pattern="AI_AUDIT_LOG")` → object + column long↔short map (datatype/length, source member) for `CREATE TABLE ... FOR SYSTEM NAME` tables → To trace usage of a long-named table, take `system_short_name` and chain to `ia_find_object_usages` / `ia_file_field_impact_analysis` — the cross-reference only knows the 10-char system name. Complements `ia_sql_names` (routines).
+
 ### P17: "What happens if I change this service program?" (SRVPGM Impact)
 Service programs are **cascade amplifiers** — changes affect all binding programs.
 
@@ -130,6 +141,20 @@ Service programs are **cascade amplifiers** — changes affect all binding progr
 
 **Signature changes** (adding/removing/retyping parameters) require **recompile of ALL consumers**. Adding new procedures is safe; removing procedures breaks callers.
 
+### P18: "Orphaned + tangled — refactor or archive triage" (Quadrant Analysis)
+Cross-tool chain for modernization audits. Splits programs into 4 quadrants by usage age × complexity.
+
+1. `ia_code_complexity(member_name='*ALL', limit=200)` → score each row: `GOTO×5 + CAB×5 + CAS×5 + IF×1 + SQL×0.5`. High score = tangled.
+2. `ia_object_lifecycle` on the top-scoring candidates → read `LASTUSED_DATE`.
+3. Classify each program into one of four quadrants:
+   - **Active & Clean** (recent + low score) — leave alone.
+   - **Active & Tangled** (recent + high score) — refactor priority.
+   - **Sleeping & Clean** (old + low score) — archive candidate.
+   - **Orphaned & Toxic** (old + high score) — audit FIRST, then archive.
+4. For any "Orphaned & Toxic" candidate, validate with `ia_find_object_usages` before recommending deletion — `LASTUSED_DATE` alone is not delete-safe.
+
+**Why this matters:** Modernization-scope studies show isolating "Orphaned & Toxic" can cut effective refactor scope ~30%. The quadrant verdict is the deliverable, not the raw table.
+
 ## Risk Rubric
 
 | References | Risk | Guidance |