Improve workflow discovery with inferred route links

.agents/skills/tldrgraph-init/SKILL.md

@@ -8,27 +8,59 @@ description: Build or continue this repository's TLDRGraph architecture graph (l
 In Claude Code or Cursor, invoke `/tldrgraph-init`. In Codex CLI, type `/skills`
 and select `tldrgraph-init`, or mention `$tldrgraph-init` directly.
 
-One command handles layer design, extraction, enrichment, and embeddings:
+One command handles layer design, extraction, enrichment, LLM route links, and embeddings:
 
 ```bash
 tldrgraph init
 ```
 
 By default TLDRGraph detects `claude`, `cursor-agent`, or `gemini`, asks once before enrichment token spend, processes every
 eligible node in batches of 200, and downloads/builds the local embedding model.
-Use `--yes` for non-interactive approval, `--batch N` to override the batch size,
-`--embeddings off|auto|on` to override embeddings, or `--no-agent-cli` for the
-manual file handoff.
+Use `--yes` for approval, `--batch N` for batch size, `--embeddings off|auto|on`,
+`--no-llm-links` to skip LLM frontend/backend route inference, or `--no-agent-cli`
+for manual file handoff.
 
 After the user approves the full run, use exactly `tldrgraph init --yes`. The
 approval is saved for the current candidate set, so later `tldrgraph init` calls
 must continue without asking again. `--batch 200` means all nodes in 200-node
 batches; `--limit 200` means stop after only 200 nodes. Never add `--limit` or
 `--embeddings off` unless the user explicitly requests a partial or no-embedding run.
 
+## Completion contract for agents
+
+Once the user approves a full enrichment campaign, you are not done until one of
+these terminal states occurs:
+
+- `tldrgraph init` reports `status: done`.
+- Dense embeddings finish, or `init` explicitly reports that embeddings are
+  unavailable while preserving a queryable graph.
+- A real blocking error occurs that requires user action, and you report the
+  exact command/output that blocked continuation.
+
+These are **not** terminal states:
+
+- `status: needs_enrichment`
+- `NEXT ACTION`
+- "nodes remaining"
+- "batches remaining"
+- "applied N enrichment entries"
+
+For every non-terminal enrichment state, immediately continue the loop:
+
+1. Read `.tldrgraph/enrichment_request.yaml`.
+2. Open the source file for every requested node.
+3. Write `.tldrgraph/enrichment_response.yaml`.
+4. Run `tldrgraph init` again.
+5. Repeat until a terminal state occurs.
+
+Do not end the task with a progress-only summary such as "I applied 400 entries
+and 1,438 remain." That is an incomplete run, not a final answer. If nested-agent
+protection prevents a CLI from launching another agent, you are the enrichment
+agent and must process the batch yourself.
+
 If no supported agent is available or dense embeddings cannot be built, `init`
-preserves the graph and prints a resumable status. It never guesses source intent
-or architectural layers.
+preserves the graph and prints a resumable status. It never guesses source intent,
+route links, or architectural layers.
 
 ## `status: needs_layers`
 
@@ -102,9 +134,13 @@ Do not decide for them.
   calls: [ApplicationsService, pension_cases]
 ```
 
-4. Run `tldrgraph init` again. Approval is already saved. If another
-   `needs_enrichment` batch appears, process it immediately and repeat this loop
-   without asking the user again. Continue until `status: done`.
+Every `intent` must contain **2-3 complete sentences** covering what the symbol does,
+why it exists, and its source-backed behavior. Markdown headings and list markers do not
+count as sentences.
+
+4. Run `tldrgraph init` again. Approval is saved; process any next
+   `needs_enrichment` batch immediately without asking the user again until
+   `status: done` or `needs_llm_links`.
 
 Inside an existing Codex/Claude/Cursor session, nested-agent protection may stop
 the CLI from launching a second agent. In that case **you are the enrichment
@@ -117,6 +153,15 @@ gets reported back to you -- but the work is wasted.
 **Never invent `fields` or `calls`.** Omit what you cannot verify in the code: an
 empty list is a correct answer, a wrong `calls` entry becomes a real wrong edge.
 
+## `status: needs_llm_links`
+
+1. Read `.tldrgraph/llm_links_request.yaml`.
+2. Open the referenced frontend and backend source files.
+3. Write `.tldrgraph/llm_links_response.yaml` as a YAML list of
+   `{source, target, confidence, frontend_evidence, backend_evidence, explanation}`.
+   Only include source-backed links with file and line evidence.
+4. Run `tldrgraph init` again, or use `--no-llm-links` to skip this optional stage.
+
 ## Once it says DONE
 
 ```bash

.claude/commands/tldrgraph-init.md

@@ -8,27 +8,59 @@ description: Build or continue this repository's TLDRGraph architecture graph (l
 In Claude Code or Cursor, invoke `/tldrgraph-init`. In Codex CLI, type `/skills`
 and select `tldrgraph-init`, or mention `$tldrgraph-init` directly.
 
-One command handles layer design, extraction, enrichment, and embeddings:
+One command handles layer design, extraction, enrichment, LLM route links, and embeddings:
 
 ```bash
 tldrgraph init
 ```
 
 By default TLDRGraph detects `claude`, `cursor-agent`, or `gemini`, asks once before enrichment token spend, processes every
 eligible node in batches of 200, and downloads/builds the local embedding model.
-Use `--yes` for non-interactive approval, `--batch N` to override the batch size,
-`--embeddings off|auto|on` to override embeddings, or `--no-agent-cli` for the
-manual file handoff.
+Use `--yes` for approval, `--batch N` for batch size, `--embeddings off|auto|on`,
+`--no-llm-links` to skip LLM frontend/backend route inference, or `--no-agent-cli`
+for manual file handoff.
 
 After the user approves the full run, use exactly `tldrgraph init --yes`. The
 approval is saved for the current candidate set, so later `tldrgraph init` calls
 must continue without asking again. `--batch 200` means all nodes in 200-node
 batches; `--limit 200` means stop after only 200 nodes. Never add `--limit` or
 `--embeddings off` unless the user explicitly requests a partial or no-embedding run.
 
+## Completion contract for agents
+
+Once the user approves a full enrichment campaign, you are not done until one of
+these terminal states occurs:
+
+- `tldrgraph init` reports `status: done`.
+- Dense embeddings finish, or `init` explicitly reports that embeddings are
+  unavailable while preserving a queryable graph.
+- A real blocking error occurs that requires user action, and you report the
+  exact command/output that blocked continuation.
+
+These are **not** terminal states:
+
+- `status: needs_enrichment`
+- `NEXT ACTION`
+- "nodes remaining"
+- "batches remaining"
+- "applied N enrichment entries"
+
+For every non-terminal enrichment state, immediately continue the loop:
+
+1. Read `.tldrgraph/enrichment_request.yaml`.
+2. Open the source file for every requested node.
+3. Write `.tldrgraph/enrichment_response.yaml`.
+4. Run `tldrgraph init` again.
+5. Repeat until a terminal state occurs.
+
+Do not end the task with a progress-only summary such as "I applied 400 entries
+and 1,438 remain." That is an incomplete run, not a final answer. If nested-agent
+protection prevents a CLI from launching another agent, you are the enrichment
+agent and must process the batch yourself.
+
 If no supported agent is available or dense embeddings cannot be built, `init`
-preserves the graph and prints a resumable status. It never guesses source intent
-or architectural layers.
+preserves the graph and prints a resumable status. It never guesses source intent,
+route links, or architectural layers.
 
 ## `status: needs_layers`
 
@@ -102,9 +134,13 @@ Do not decide for them.
   calls: [ApplicationsService, pension_cases]
 ```
 
-4. Run `tldrgraph init` again. Approval is already saved. If another
-   `needs_enrichment` batch appears, process it immediately and repeat this loop
-   without asking the user again. Continue until `status: done`.
+Every `intent` must contain **2-3 complete sentences** covering what the symbol does,
+why it exists, and its source-backed behavior. Markdown headings and list markers do not
+count as sentences.
+
+4. Run `tldrgraph init` again. Approval is saved; process any next
+   `needs_enrichment` batch immediately without asking the user again until
+   `status: done` or `needs_llm_links`.
 
 Inside an existing Codex/Claude/Cursor session, nested-agent protection may stop
 the CLI from launching a second agent. In that case **you are the enrichment
@@ -117,6 +153,15 @@ gets reported back to you -- but the work is wasted.
 **Never invent `fields` or `calls`.** Omit what you cannot verify in the code: an
 empty list is a correct answer, a wrong `calls` entry becomes a real wrong edge.
 
+## `status: needs_llm_links`
+
+1. Read `.tldrgraph/llm_links_request.yaml`.
+2. Open the referenced frontend and backend source files.
+3. Write `.tldrgraph/llm_links_response.yaml` as a YAML list of
+   `{source, target, confidence, frontend_evidence, backend_evidence, explanation}`.
+   Only include source-backed links with file and line evidence.
+4. Run `tldrgraph init` again, or use `--no-llm-links` to skip this optional stage.
+
 ## Once it says DONE
 
 ```bash

.cursor/commands/tldrgraph-init.md

@@ -102,6 +102,10 @@ Do not decide for them.
   calls: [ApplicationsService, pension_cases]
 ```
 
+Every `intent` must contain **2-3 complete sentences** covering what the symbol does,
+why it exists, and its source-backed behavior. Markdown headings and list markers do not
+count as sentences.
+
 4. Run `tldrgraph init` again. Approval is already saved. If another
    `needs_enrichment` batch appears, process it immediately and repeat this loop
    without asking the user again. Continue until `status: done`.

.tldrgraph/AGENT_CONTRACT.md

@@ -140,7 +140,7 @@ Equivalent JSON format (also accepted from `.tldrgraph/enrichment_response.json`
 [
   {
     "id": "backend_src_applications_applications_controller_applicationscontroller",
-    "intent": "### Pension Application Lifecycle Gateway\nREST gateway for the pension application lifecycle.",
+    "intent": "### Pension Application Lifecycle Gateway\nREST gateway for the pension application lifecycle. It authorizes roles and dispatches source-backed status transitions.",
     "input_fields": ["caseId", "transitionPayload", "remarks", "sanctionOrderNo"],
     "output_fields": ["applicationStatus", "disposition"],
     "calls": ["ApplicationsService", "JwtAuthGuard", "RolesGuard", "pension_cases"]
@@ -151,7 +151,7 @@ Equivalent JSON format (also accepted from `.tldrgraph/enrichment_response.json`
 | Key | Type | Meaning |
 | --- | --- | --- |
 | `id` | string, **required** | The node id, copied **verbatim** from the request. An id that is not in the graph is skipped silently. |
-| `intent` | string (Markdown) | Markdown formatted explanation: what this symbol does, its role, and why it exists. AI decides how much depth is needed. This is the text semantic search matches against. |
+| `intent` | string (Markdown) | Markdown formatted 2-3 sentence explanation: what this symbol does, why it exists, and its source-backed behavior. Headings and list markers do not count as sentences. This is the text semantic search matches against. |
 | `input_fields` | array of strings | Input parameters, arguments, request body payload attributes, query filters. |
 | `output_fields` | array of strings | Return types, response models, emitted event names, or mutated state attributes. |
 | `fields` | array of strings (legacy) | Supported for backwards compatibility (maps to input fields). |
@@ -171,13 +171,17 @@ valid and useful.
    describe what it really does. An intent paraphrased from the label is worse than no
    intent, because it poisons search with confident-sounding noise.
 
-2. **Do not invent fields or calls. Omit what you cannot verify in the code.** If you
+2. **Write every intent in 2-3 complete sentences.** Cover what the symbol does, why it
+   exists, and its source-backed behavior. Markdown headings and list markers do not count
+   as sentences.
+
+3. **Do not invent fields or calls. Omit what you cannot verify in the code.** If you
    read the file and it handles three params, list three. Do not pad the list with what a
    symbol of that name "usually" has. `"fields": []` is a correct, honest answer.
    A wrong `calls` entry creates a real, wrong edge in the graph that later queries will
    follow.
 
-3. **`calls` entries are resolved with 2-tier high precision.**
+4. **`calls` entries are resolved with 2-tier high precision.**
    - **Tier 1 (Exact Match, 100% confidence):** Exact symbol names (`ApplicationsService`),
      function names, node IDs, file paths (`calc.ts`), or database table names (`pension_cases`).
    - **Tier 2 (Vector Fallback):** Semantic search with a calibrated 0.35 score floor.
@@ -191,12 +195,12 @@ valid and useful.
 
    Prefer the exact symbol name, file name, or table/model name as it appears in the source.
 
-4. **Copy `id` verbatim.** Do not normalize, shorten or re-case it.
+5. **Copy `id` verbatim.** Do not normalize, shorten or re-case it.
 
-5. **Answer only the nodes in the request.** Extra ids are ignored; missing ids just come
+6. **Answer only the nodes in the request.** Extra ids are ignored; missing ids just come
    back in a later batch.
 
-6. **After full approval, never ask again for the same campaign.** Continue processing
+7. **After full approval, never ask again for the same campaign.** Continue processing
    `needs_enrichment` batches until `status: done`. Do not silently add `--limit` or
    `--embeddings off`.
 

AGENTS.md

@@ -25,9 +25,31 @@ tldrgraph dead-code                            # review candidates, never a dele
 Those are read-only and never trigger enrichment.
 
 **To build or refresh the graph**, run `tldrgraph init`. It automatically handles
-layer design, extraction, source-aware enrichment in 200-node batches, and dense
-embeddings when a supported agent CLI is available. If it prints a `NEXT ACTION`
-fallback, follow that handoff without guessing from symbol names.
+layer design, extraction, source-aware enrichment in 200-node batches, LLM
+frontend/backend route-link inference, and dense embeddings when a supported
+agent CLI is available. If it prints a `NEXT ACTION` fallback, follow that
+handoff without guessing from symbol names.
+
+### ✅ TLDRGraph Init Completion Contract
+After the user approves a full TLDRGraph enrichment run, the agent MUST keep
+working until `tldrgraph init` reports `status: done` or a genuine blocking error
+requires user action.
+
+- `needs_enrichment`, "nodes remaining", "batches remaining", and "NEXT ACTION"
+  are continuation states, not completion states.
+- Do not end with a progress-only summary such as "I enriched 400 nodes and
+  1,438 remain" unless a blocking error prevents continuation.
+- After each enrichment response is written, immediately run `tldrgraph init`
+  again and repeat the loop.
+- If `status: needs_llm_links` appears, read `.tldrgraph/llm_links_request.yaml`,
+  open the referenced frontend/backend source files, and write
+  `.tldrgraph/llm_links_response.yaml` with evidence-backed
+  `{source, target, confidence, frontend_evidence, backend_evidence, explanation}`
+  entries before running `tldrgraph init` again.
+- If nested-agent protection prevents launching another CLI agent, the current
+  agent is responsible for processing the batch manually.
+- Final responses may summarize progress only after `status: done`, embeddings
+  are completed or explicitly unavailable, or the exact blocker is reported.
 
 Full workflow: `.claude/commands/tldrgraph-init.md` (identical copies live in every
 other agent directory). Schema: `.tldrgraph/AGENT_CONTRACT.md`.

AGENT_CONTRACT.md

@@ -140,7 +140,7 @@ Equivalent JSON format (also accepted from `.tldrgraph/enrichment_response.json`
 [
   {
     "id": "backend_src_applications_applications_controller_applicationscontroller",
-    "intent": "### Pension Application Lifecycle Gateway\nREST gateway for the pension application lifecycle.",
+    "intent": "### Pension Application Lifecycle Gateway\nREST gateway for the pension application lifecycle. It authorizes roles and dispatches source-backed status transitions.",
     "input_fields": ["caseId", "transitionPayload", "remarks", "sanctionOrderNo"],
     "output_fields": ["applicationStatus", "disposition"],
     "calls": ["ApplicationsService", "JwtAuthGuard", "RolesGuard", "pension_cases"]
@@ -151,7 +151,7 @@ Equivalent JSON format (also accepted from `.tldrgraph/enrichment_response.json`
 | Key | Type | Meaning |
 | --- | --- | --- |
 | `id` | string, **required** | The node id, copied **verbatim** from the request. An id that is not in the graph is skipped silently. |
-| `intent` | string (Markdown) | Markdown formatted explanation: what this symbol does, its role, and why it exists. AI decides how much depth is needed. This is the text semantic search matches against. |
+| `intent` | string (Markdown) | Markdown formatted 2-3 sentence explanation: what this symbol does, why it exists, and its source-backed behavior. Headings and list markers do not count as sentences. This is the text semantic search matches against. |
 | `input_fields` | array of strings | Input parameters, arguments, request body payload attributes, query filters. |
 | `output_fields` | array of strings | Return types, response models, emitted event names, or mutated state attributes. |
 | `fields` | array of strings (legacy) | Supported for backwards compatibility (maps to input fields). |
@@ -171,13 +171,17 @@ valid and useful.
    describe what it really does. An intent paraphrased from the label is worse than no
    intent, because it poisons search with confident-sounding noise.
 
-2. **Do not invent fields or calls. Omit what you cannot verify in the code.** If you
+2. **Write every intent in 2-3 complete sentences.** Cover what the symbol does, why it
+   exists, and its source-backed behavior. Markdown headings and list markers do not count
+   as sentences.
+
+3. **Do not invent fields or calls. Omit what you cannot verify in the code.** If you
    read the file and it handles three params, list three. Do not pad the list with what a
    symbol of that name "usually" has. `"fields": []` is a correct, honest answer.
    A wrong `calls` entry creates a real, wrong edge in the graph that later queries will
    follow.
 
-3. **`calls` entries are resolved with 2-tier high precision.**
+4. **`calls` entries are resolved with 2-tier high precision.**
    - **Tier 1 (Exact Match, 100% confidence):** Exact symbol names (`ApplicationsService`),
      function names, node IDs, file paths (`calc.ts`), or database table names (`pension_cases`).
    - **Tier 2 (Vector Fallback):** Semantic search with a calibrated 0.35 score floor.
@@ -191,12 +195,12 @@ valid and useful.
 
    Prefer the exact symbol name, file name, or table/model name as it appears in the source.
 
-4. **Copy `id` verbatim.** Do not normalize, shorten or re-case it.
+5. **Copy `id` verbatim.** Do not normalize, shorten or re-case it.
 
-5. **Answer only the nodes in the request.** Extra ids are ignored; missing ids just come
+6. **Answer only the nodes in the request.** Extra ids are ignored; missing ids just come
    back in a later batch.
 
-6. **After full approval, never ask again for the same campaign.** Continue processing
+7. **After full approval, never ask again for the same campaign.** Continue processing
    `needs_enrichment` batches until `status: done`. Do not silently add `--limit` or
    `--embeddings off`.
 

README.md

@@ -100,7 +100,7 @@ Opens the interactive canvas:
 ```bash
 tldrgraph query "pension application approval flow"
 ```
-Outputs five readable Markdown execution flow tables by default, tracing the request across UI, API, Service, and DB layers. Queries use dense embeddings by default (and may download the configured model); use `--top-k`, `--embeddings auto`, or `--embeddings off` to override this behavior.
+Outputs ten readable Markdown execution flow tables by default, tracing the request across UI, API, Service, and DB layers. Queries use dense embeddings by default (and may download the configured model); use `--top-k`, `--embeddings auto`, or `--embeddings off` to override this behavior.
 
 ### 5. Trace Exact Call Paths
 ```bash