@thomasminh1995/depverdict 0.6.0-alpha.1

package/docs/IA-03-Repository-Impact-Evidence.md

@@ -0,0 +1,160 @@
+# IA-03 — Repository Impact Evidence Generation
+
+## 1. Scope and architecture review
+
+IA-03 là một artifact-to-artifact stage giải thích mọi kết luận trong Repository Impact bằng dữ liệu đã tồn tại. Stage này không scan repository, không parse source, không gọi AI/internet, không tính severity/confidence và không sinh migration plan.
+
+Input trust chain:
+
+```text
+Project Manifest
+      ↓
+Version Analysis
+      ↓
+Usage Index
+      ↓
+Repository Impact
+      ↓
+Repository Impact Evidence
+```
+
+Contract hiện tại đủ để tạo evidence ở cấp dependency/symbol/file:
+
+- Version Analysis có stable analysis result ID, breaking finding ID và original summary.
+- Usage Index có `projectId`, `packageId`, symbol và repository-relative files.
+- Repository Impact có exact matched symbols/files và giữ cả impacted lẫn non-impacted breaking findings.
+
+Technical debt/contract gaps:
+
+1. Usage Index `1.0.0` chưa có usage/import kind. Evidence chỉ chứa `{file}`; không tạo `kind` giả.
+2. Usage Index chưa có line, column, snippet, function, call count hoặc member-level usage. Evidence schema không có các field này.
+3. Version Analysis chưa có structured affected API paths. IA-02 exact matcher đã xử lý free-text summary; IA-03 không tìm hoặc suy luận match mới.
+4. Repository Impact finding dùng cùng finding ID với Version Analysis và chưa có evidence-record ID riêng. IA-03 tạo stable SHA-256 ID từ `{analysisResultId, findingId}`, đồng thời giữ nguyên hai source references để trace ngược.
+5. Evidence reason contract hiện hỗ trợ `exact-symbol@1.0.0`. Matcher khác phải có evidence policy/version riêng thay vì bị gắn nhãn exact sai.
+
+Các gap trên không chặn IA-03 và không được giải quyết bằng cách sửa artifact cũ.
+
+## 2. Runtime flow
+
+```text
+project-manifest.json --------\
+version-analysis.json ---------+--> schema + invariant + exact-byte lineage
+usage-index.json --------------+--> dependency/finding/symbol/file references
+repository-impact.json -------/                         |
+                                                          v
+                                         deterministic reason selection
+                                                          |
+                                                          v
+                                      evidence model + stable evidence IDs
+                                                          |
+                                                          v
+                         .upgradelens/repository-impact-evidence.json
+```
+
+Không có repository path hoặc source scanner/parser trong runtime IA-03.
+
+## 3. Module structure
+
+```text
+src/impact-evidence/
+  input-loader.js                 four-artifact trust boundary
+  repository-impact-evidence.js  generator, model, summary, invariants
+  runtime.js                      pure orchestration
+  writer.js                       validated atomic writer
+
+schemas/
+  repository-impact-evidence.schema.json
+```
+
+Infrastructure được tái sử dụng theo chuỗi: IA-03 loader gọi IA-02 loader; IA-02 loader gọi IA-01 loader. Mỗi stage chỉ bổ sung validation cho artifact mới của nó.
+
+## 4. Artifact contract
+
+Artifact mặc định: `.upgradelens/repository-impact-evidence.json`.
+
+Schema version: `1.0.0`.
+
+```json
+{
+  "analysisResultId": "sha256:...",
+  "projectId": "node:.",
+  "packageId": "npm:antd",
+  "name": "antd",
+  "impacted": true,
+  "findings": [
+    {
+      "id": "sha256:...",
+      "findingId": "modal-info-removed",
+      "kind": "breakingChange",
+      "summary": "Modal.info was removed.",
+      "impacted": true,
+      "reasonCode": "EXACT_SYMBOL_USAGE_FOUND",
+      "matchedSymbols": [
+        {
+          "symbol": "Modal",
+          "usages": [
+            { "file": "src/components/UserDialog.tsx" },
+            { "file": "src/pages/Home.tsx" }
+          ]
+        }
+      ]
+    }
+  ]
+}
+```
+
+Input lineage giữ exact-byte SHA-256 cho Project Manifest, Version Analysis, Usage Index và Repository Impact. Output không copy evidence refs/release notes vì chúng không cần thiết để giải thích repository usage match.
+
+## 5. Reason codes
+
+| Code | Điều kiện deterministic |
+| --- | --- |
+| `EXACT_SYMBOL_USAGE_FOUND` | Repository Impact finding impacted và có ít nhất một exact matched symbol/file record. |
+| `NO_EXACT_SYMBOL_USAGE_FOUND` | Dependency có ít nhất một matchable API symbol nhưng finding không có exact match. |
+| `DEPENDENCY_NOT_USED` | Không có Usage Index dependency entry cho exact `projectId + packageId`. |
+| `NO_MATCHABLE_SYMBOL_FOUND` | Dependency có usage entry nhưng không có API symbol có thể exact-match, ví dụ chỉ `*`, `default` hoặc side-effect usage. |
+
+Reason code không kèm AI prose. Consumer có thể render message bằng template riêng dựa trên enum ổn định.
+
+## 6. Validation and invariants
+
+Loader từ chối input khi:
+
+- bất kỳ artifact nào sai schema/runtime invariants;
+- Project/Version/Usage/Impact lineage khác artifact bytes đang load;
+- repository identity hoặc artifact path không khớp lineage;
+- Repository Impact dependency không trỏ tới exact Version Analysis result;
+- dependency identity/name khác source result;
+- thiếu/thừa/unknown breaking finding;
+- original finding summary bị đổi;
+- matched symbol không tồn tại trong Usage Index;
+- file set khác exact symbol usage files;
+- impact matcher không phải `exact-symbol@1.0.0`.
+
+Output invariants:
+
+- dependencies sort theo project/package/analysis result;
+- findings sort theo finding ID;
+- matched symbols và usage files sort lexical;
+- mọi evidence ID ổn định từ analysis result + finding ID;
+- impacted finding phải có `EXACT_SYMBOL_USAGE_FOUND` và non-empty matches;
+- non-impacted finding không được có match;
+- dependency impacted phải bằng OR của findings;
+- summary và bốn reason counts phải tái tính đúng từ records;
+- IDs, symbols và usage files không trùng.
+
+## 7. Known limitations and upgrade path
+
+- Evidence chỉ chứng minh symbol-level impact. `Modal.info` match `Modal` chưa chứng minh exact member `info` được gọi.
+- Không có usage kind trong schema hiện tại, nên evidence không thể phân biệt named/default/namespace import ngoài canonical symbol facts.
+- Dependency có side-effect usage nhưng không có API symbol nhận `NO_MATCHABLE_SYMBOL_FOUND`; engine không suy diễn side effect có bị breaking change ảnh hưởng hay không.
+- Non-breaking Version Analysis findings không thuộc Repository Impact `1.0.0`, do đó không nằm trong evidence artifact.
+
+Hướng nâng cấp sau MVP:
+
+1. thêm optional structured `affectedApiPaths` vào Version Analysis version mới;
+2. thêm optional `usageKind` và member paths vào Usage Index version mới;
+3. thêm matcher/evidence-policy version mới để match exact API path;
+4. chỉ thêm line/snippet khi source discovery artifact thực sự sở hữu và version các dữ liệu đó.
+
+Không dùng fuzzy matching hoặc AI để bù contract gap.

package/docs/IA-04-CLI-Orchestration.md

@@ -0,0 +1,235 @@
+# IA-04 — CLI Orchestration & Report
+
+## Architecture review
+
+IA-01, IA-02, and IA-03 already expose independent runtimes, validators, and artifact writers. IA-04 keeps those boundaries: it schedules the runtimes and passes artifact paths to the next stage without duplicating discovery, matching, or evidence logic.
+
+The earlier Knowledge Research and Version Analysis entry-point orchestration still lives in `src/cli.js`. IA-04 uses small stage adapters around those existing functions. Moving them into dedicated application-service modules is useful future cleanup, but is deliberately outside IA-04 because it would increase regression risk without changing pipeline behavior.
+
+Legacy stage commands remain available for backward compatibility. `upgradelens analyze` is the primary end-to-end command.
+
+## Pipeline flow
+
+```text
+upgradelens analyze <repository>
+                |
+                v
+        Project Discovery
+                |
+                v
+        Knowledge Research
+                |
+                v
+         Version Analysis
+                |
+                v
+    Repository Usage Discovery
+                |
+                v
+    Repository Impact Analysis
+                |
+                v
+    Repository Impact Evidence
+                |
+                v
+         Markdown Report
+                |
+                v
+          Console Summary
+```
+
+The scheduler runs stages sequentially. Every successful stage writes its existing artifact before the next stage starts. A failed stage is wrapped with its stage identity, the remaining stages are not invoked, and a concise log is written to `.upgradelens/logs/analyze.log`.
+
+The scheduler accepts injected stage runners and a progress reporter. This keeps orchestration tests deterministic and keeps each runtime independently testable.
+
+## Artifact flow
+
+| Stage | Reads | Writes |
+| --- | --- | --- |
+| Project Discovery | repository | `.upgradelens/project-manifest.json` |
+| Knowledge Research | Project Manifest | `.upgradelens/knowledge-manifest.json` and the existing evidence bundle |
+| Version Analysis | Project, Knowledge, and knowledge evidence artifacts | `.upgradelens/version-analysis.json` |
+| Usage Discovery | Project Manifest, Version Analysis, repository source | `.upgradelens/usage-index.json` |
+| Impact Analysis | Project Manifest, Version Analysis, Usage Index | `.upgradelens/repository-impact.json` |
+| Impact Evidence | Project Manifest, Version Analysis, Usage Index, Repository Impact | `.upgradelens/repository-impact-evidence.json` |
+| Markdown Report | completed in-memory artifact values produced by the same run | `.upgradelens/repository-impact.md` |
+
+IA-04 does not rescan or parse source outside the existing Usage Discovery runtime. It does not perform impact matching or evidence generation itself.
+
+## CLI usage
+
+Run the complete pipeline:
+
+```bash
+upgradelens analyze .
+```
+
+Select a validated caller-owned target without converting other registry
+candidates into recommendations:
+
+```bash
+upgradelens analyze . --target 'package=npm:framework-a,target=2.0.0'
+```
+
+For an ambiguous monorepo occurrence, add the stable occurrence qualifiers:
+
+```bash
+upgradelens analyze . \
+  --target 'package=npm:framework-a,target=2.0.0,project=node:apps/web,manifest=apps/web/package.json,type=dependency'
+```
+
+If the same package is declared more than once with those same qualifiers,
+the ambiguity error supplies one copy/paste-ready selector per declaration:
+
+```bash
+upgradelens analyze . \
+  --target 'package=pypi:library-a,target=2.0.0,project=python:.,manifest=requirements.txt,type=runtime,occurrence=sha256:<candidate-id>'
+```
+
+The optional `occurrence` discriminator is derived from canonical portable
+declaration facts. It does not use array position or an absolute path.
+Existing selectors remain valid when they already resolve one occurrence.
+Stale or conflicting occurrence identifiers fail before provider
+construction.
+
+The repeatable key/value grammar is safe for scoped npm packages and Python
+canonical IDs. Resolution is exact; zero matches, ambiguous matches, and
+ecosystem-invalid targets fail before provider construction.
+
+Use cached research data without registry requests:
+
+```bash
+upgradelens analyze . --offline
+```
+
+Limit discovery and usage scanning depth:
+
+```bash
+upgradelens analyze . --max-depth 6
+```
+
+On success, progress is printed without internal stage output or stack traces:
+
+```text
+Running UpgradeLens Analysis...
+
+✓ Project Discovery
+✓ Knowledge Research
+✓ Version Analysis
+✓ Repository Usage Discovery
+✓ Repository Impact Analysis
+✓ Repository Impact Evidence
+✓ Markdown Report
+
+Analysis completed.
+```
+
+On failure, the failed stage is identified and later stages do not run:
+
+```text
+✗ Repository Usage Discovery
+
+Repository Usage Discovery failed.
+
+See:
+.upgradelens/logs/analyze.log
+```
+
+## Renderer architecture
+
+```text
+Version Analysis + Repository Impact + Repository Impact Evidence
+                              |
+                              v
+                  Presentation View Model
+                              |
+              +---------------+---------------+
+              |                               |
+              v                               v
+      Console renderer                Markdown renderer
+```
+
+The report stage builds one immutable, in-memory presentation view model and passes that same instance to both renderers. The builder joins dependency occurrences by `analysisResultId`, preserves Repository Impact ordering, validates artifact counts and cross-references, and clones evidence records without modifying the source artifacts. It creates no artifact or schema.
+
+Renderers are presentation-only functions. They receive the shared view model and return text. They do not call analyzers or matchers, modify artifacts, derive severity or confidence, or write files. Writing is handled by the orchestration adapter after rendering.
+
+This boundary permits future HTML, SARIF, or GitHub Summary renderers without changing the scheduler or IA-01 through IA-03.
+
+### Analysis completeness contract
+
+Overall analysis status comes only from existing Version Analysis result statuses:
+
+- `COMPLETE`: every dependency occurrence has status `analyzed`;
+- `INCOMPLETE`: one or more dependency occurrences has status `skipped` or `failed`.
+
+`requiresHumanReview` remains an explicit count, but does not by itself make an analyzed result incomplete.
+
+This legacy analysis completeness is diagnostic. The public CLI separately
+projects product completion as `COMPLETED`, `COMPLETED_WITH_REVIEW`, `PARTIAL`,
+or `INSUFFICIENT_DATA`. Fatal pipeline failures and controlled cancellation are
+reported as `FAILED` and `CANCELLED`.
+
+Default `analyze` exits 0 for completed, review-required, and valid
+insufficient-data outcomes; retained provider/output/runtime failures are
+`PARTIAL` and exit 2. `--fail-on-incomplete` also exits 2 for
+`COMPLETED_WITH_REVIEW` and `INSUFFICIENT_DATA`, but never fails only because
+there are zero actions or all occurrences are `KEEP_CURRENT`.
+
+Each dependency occurrence has exactly one presentation status:
+
+- `IMPACTED`: Version Analysis status is `analyzed` and Repository Impact reports `impacted: true`;
+- `NOT_IMPACTED`: Version Analysis status is `analyzed` and Repository Impact reports `impacted: false`;
+- `NOT_ANALYZED`: Version Analysis status is `skipped` or `failed`.
+
+Skipped and failed results are never described as not impacted. They receive a deterministic safe message based only on their status; raw runtime errors are not included. The following invariant must hold or presentation fails clearly:
+
+```text
+impacted + not impacted + not analyzed = dependency occurrences
+```
+
+Missing references, identity mismatches, finding-reference mismatches, and inconsistent summary counts also fail rather than being silently classified.
+
+### Console format
+
+The console summary leads with:
+
+- product completion and plain-language next step;
+- decision counts and an occurrence-level installed-to-target table;
+- handoff counts and failed-occurrence recovery guidance;
+- report and artifact paths;
+- legacy impact counts as trailing diagnostics.
+
+The diagnostic section contains:
+
+- repository name from Project Manifest;
+- overall `COMPLETE` or `INCOMPLETE` analysis status;
+- analyzed, skipped, failed, and human-review counts from Version Analysis;
+- separate impacted, not-impacted, and not-analyzed occurrence counts;
+- breaking finding count from Repository Impact;
+- evidence record count from Repository Impact Evidence (`summary.findingCount`);
+- Markdown report path.
+
+An incomplete run also prints a plain-text warning that impact conclusions are incomplete. Color is not required to understand the state.
+
+### Markdown format
+
+The Markdown report contains:
+
+- repository name;
+- an Analysis Completeness section and warning when incomplete;
+- analyzed, skipped, failed, impacted, not-impacted, and not-analyzed counts;
+- one section per dependency;
+- the dependency's Version Analysis and impact presentation statuses;
+- finding ID, original finding summary, impacted flag, evidence reason code;
+- matched symbols and source file paths already present in Repository Impact Evidence.
+
+For `NOT_ANALYZED`, the dependency section renders no impact conclusion or evidence and explains only whether Version Analysis was skipped or failed. The report does not add conclusions beyond the artifact fields.
+
+## Limitations and technical debt
+
+- Knowledge Research and Version Analysis application orchestration remain CLI-local legacy code. They should eventually be extracted into dedicated stage services without changing their domain runtimes.
+- `analyze` inherits the configured behavior of existing stages. Online Research may access registries, and Version Analysis may require its already-configured runtime. IA-04 adds no provider or AI behavior.
+- Failure logging currently keeps one deterministic `analyze.log`; a later observability task may add rotation or run identifiers.
+- The presentation builder checks the cross-artifact relationships required for truthful rendering, but upstream artifact schema validation remains the responsibility of each owning stage.
+- `INCOMPLETE` does not repair or retry skipped/failed Version Analysis results. Provider/runtime configuration and Version Analysis quality remain outside IA-04.
+- Dependency ordering is deterministic for the same inputs and preserves occurrence-level Repository Impact ordering. Stable identifiers across separate pipeline runs remain outside this fix.

package/docs/IA-05-Real-Provider-Validation.md

@@ -0,0 +1,235 @@
+# IA-05-RERUN — Real Provider Validation on VinGrade
+
+## 1. Executive verdict
+
+**GO WITH KNOWN LIMITATIONS**
+
+The existing OpenAI-compatible HTTP runtime successfully invoked a configured remote provider, parsed strict structured output, and produced schema-valid Version Analysis results. The progressive validation analyzed three selected frontend dependencies, then the complete VinGrade pipeline analyzed 44 of 47 dependency occurrences with no provider/runtime failures.
+
+IA-04-FIX-01 rendered the mixed result truthfully: 44 analyzed occurrences were `NOT_IMPACTED`, three skipped occurrences were `NOT_ANALYZED`, and the report was `INCOMPLETE`. No skipped occurrence was presented as not impacted.
+
+The principal limitation is the declared IA-01 MVP scope: Usage Discovery currently indexes JavaScript/TypeScript only. Five of the six real breaking findings were for Python dependencies. Manual inspection found that the changed APIs in the sampled findings are not used, but IA-03's `DEPENDENCY_NOT_USED` reason for those Python packages means “absent from the supported usage index,” not proof that the repository does not import the package. MVP-04 is therefore validated for its current JS/TS usage-analysis scope, not as complete polyglot impact coverage.
+
+## 2. Provider configuration
+
+UpgradeLens does not automatically load `.env`. Validation explicitly used the existing ignored local file with `node --env-file=.env`; no secret value was printed or copied into an artifact, command transcript, source file, or this report.
+
+| Setting | Environment variable | Required by selected adapter | Secret | Validation value/status |
+| --- | --- | ---: | ---: | --- |
+| Provider adapter | `UPGRADELENS_AI_PROVIDER` | Yes, to select OpenAI-compatible mapping | No | `openai-compatible` |
+| Endpoint | `UPGRADELENS_AI_ENDPOINT` | Yes | No | configured; host `openrouter.ai` |
+| Model | `UPGRADELENS_AI_MODEL` | Yes | No | `openai/gpt-5.5` |
+| Authorization | `UPGRADELENS_AI_AUTHORIZATION` | Provider-dependent | Yes | configured |
+| Timeout | `UPGRADELENS_AI_TIMEOUT_MS` | No; default is 60000 ms | No | `180000` ms |
+
+The endpoint URL path and authorization value are intentionally not recorded. `UPGRADELENS_AI_DEBUG` was not enabled.
+
+## 3. Commands executed
+
+No command contained a key or authorization value.
+
+```bash
+git -C <VINGRADE_REPO> status --short
+git -C <VINGRADE_REPO> diff --name-only
+
+node ./bin/upgradelens.js discover \
+  <VINGRADE_REPO>
+
+node ./bin/upgradelens.js research \
+  <VINGRADE_REPO>
+
+node --env-file=.env ./bin/upgradelens.js analyze-version \
+  <VINGRADE_REPO> \
+  --package npm:react-router-dom
+
+node --env-file=.env ./bin/upgradelens.js analyze-version \
+  <VINGRADE_REPO> \
+  --package npm:react \
+  --output .upgradelens/validation/version-analysis-react.json
+
+node --env-file=.env ./bin/upgradelens.js analyze-version \
+  <VINGRADE_REPO> \
+  --package npm:axios \
+  --output .upgradelens/validation/version-analysis-axios.json
+
+node --env-file=.env ./bin/upgradelens.js analyze \
+  <VINGRADE_REPO>
+```
+
+Read-only `jq`, `rg`, `sed`, and `find` checks were then used to inspect artifact references, evidence content, report states, source usages, and Git safety. UpgradeLens verification used `npm test`, `npm pack --dry-run --cache "$TMPDIR/upgradelens-npm-cache"`, and `git diff --check`.
+
+## 4. Progressive validation
+
+### Preparation
+
+The VinGrade `.upgradelens` directory was absent at the start of this rerun, so Project Discovery and online Knowledge Research were run before the provider probe.
+
+The preparation Research run planned 46 unique packages from 47 occurrences. It reported 45 resolved packages, one unavailable package (`npm:vite`), 581 evidence records, zero cache hits, and 46 cache misses.
+
+### Level A — one dependency
+
+Selected `npm:react-router-dom` because it had one clear occurrence, declared constraint `^7.16.0`, registry target `7.18.1`, and publisher release/changelog evidence.
+
+Result:
+
+- one real remote request completed without timeout or retry;
+- result status: `analyzed`;
+- artifact validation: `valid`, with no validation warning codes;
+- target: `7.18.1` from registry evidence;
+- baseline: unresolved because the manifest declaration is a constraint, so risk remained `unknown` and required human review;
+- finding: a concrete compatibility finding describing the 7.18.1 patch fixes;
+- evidence: publisher changelog reference `sha256:4b82f43a882325c485526aaa805ef33a85efb355b09a7688fb3d895ec11575a5` directly contains those fixes.
+
+No unsupported URL or evidence reference survived validation.
+
+### Level B — small frontend set
+
+The cumulative set was `react-router-dom`, `react`, and `axios`. `vite` was excluded because Knowledge Research marked its target unavailable. Three dependencies met the requested minimum, so `pdfjs-dist` was not added merely to increase request volume.
+
+| Dependency | Declared | Target | Status | Findings |
+| --- | --- | --- | --- | ---: |
+| `npm:react-router-dom` | `^7.16.0` | `7.18.1` | analyzed | 1 compatibility |
+| `npm:react` | `^19.2.6` | `19.2.7` | analyzed | 5 compatibility |
+| `npm:axios` | `^1.17.0` | `1.18.1` | analyzed | 3 compatibility |
+
+All three outputs were schema-valid and had valid evidence references. There was no timeout, malformed response, schema mismatch, authentication failure, or provider compatibility error. The React output included some low-value compatibility records derived from registry status or unscoped changelog sections; this is model-quality noise, but it did not create breaking impact findings.
+
+### Level C — full VinGrade run
+
+The complete pipeline ran in online Research mode. Research reused 45 fresh registry cache entries and had one miss; it again produced 45 resolved and one unavailable unique package.
+
+Full Version Analysis produced 44 analyzed, three skipped, and zero failed occurrences. Under the one-call-per-eligible-context contract, this is 44 remote AI requests for Level C. Together with Level A and the two additional Level B calls, the progressive exercise made 47 remote requests. No retries or alternative models were used.
+
+The runtime does not publish an aggregate duration, per-result latency, token usage, or billing data in `version-analysis.json`; none is estimated here.
+
+The three skipped occurrences were:
+
+- `npm:vite`: target missing;
+- `pypi:langchain-core`: unsupported baseline;
+- one occurrence of `pypi:langchain-openai`: unsupported baseline.
+
+Another exact-baseline occurrence of `pypi:langchain-openai` was analyzed, confirming occurrence-level accounting.
+
+## 5. Pipeline counts
+
+| Metric | Count |
+| --- | ---: |
+| Dependency occurrences | 47 |
+| Analyzed | 44 |
+| Skipped | 3 |
+| Failed | 0 |
+| Requires human review | 46 |
+| Impacted | 0 |
+| Not impacted | 44 |
+| Not analyzed | 3 |
+| Breaking findings | 6 |
+| Impacted findings | 0 |
+| Evidence records | 6 |
+| Matched symbols | 0 |
+| Affected files | 0 |
+
+Version Analysis validation statuses were 44 `valid` and three `validWithWarnings`. The only warning codes were two `BASELINE_UNSUPPORTED` and one `TARGET_MISSING`. Across all results, 217 evidence references resolved to 111 unique included evidence records.
+
+## 6. Manual finding matrix
+
+Five of the six breaking findings were selected. Every selected claim is supported by the referenced publisher release evidence.
+
+| Dependency | Finding | Analyzed | Matched symbol | Source confirmed | Verdict |
+| --- | --- | ---: | --- | ---: | --- |
+| `pdfjs-dist` | `PageViewport.convertToViewportRectangle` removed in 6.1.200 | Yes | None | Yes: package is used, removed API is not | `CORRECT_NON_IMPACT` |
+| `langsmith` | `AsyncClient.projects` accessor removed in 0.10.0 | Yes | None | Yes: repository imports `Client`, not this accessor | `CORRECT_NON_IMPACT` |
+| `langsmith` | `online_evaluator` renamed to `evaluator` in 0.9.8 | Yes | None | Yes: no use of either SDK component was found | `CORRECT_NON_IMPACT` |
+| `python-dotenv` | `set_key`/`unset_key` symlink behavior changed in 1.2.2 | Yes | None | Yes: repository uses `find_dotenv`/`load_dotenv`, not mutation APIs | `CORRECT_NON_IMPACT` |
+| `python-jose` | Python 3.8 support removed in 3.5.0 | Yes | None | Yes: deployed Docker runtime is Python 3.11 | `CORRECT_NON_IMPACT` |
+
+Detailed observations:
+
+- VinGrade imports `pdfjs-dist` in `FE/src/components/shared/SubmissionDocumentPreview.jsx` and uses `GlobalWorkerOptions`, `Util`, `getDocument`, and the namespace value. Neither `PageViewport` nor `convertToViewportRectangle` is used. IA-02/IA-03 correctly returned `NO_EXACT_SYMBOL_USAGE_FOUND`.
+- VinGrade imports LangSmith `Client`; no LangSmith `AsyncClient.projects` or `online_evaluator` use was found.
+- VinGrade imports python-dotenv's loading helpers only; neither breaking mutation API is used.
+- VinGrade imports python-jose's `JWTError` and `jwt`, while its Dockerfile uses Python 3.11. The Python 3.8 platform removal does not affect that runtime.
+
+The unselected sixth finding concerns python-dotenv file-mode preservation and has the same manual non-impact result as the selected symlink finding.
+
+## 7. False positives and false negatives
+
+No confirmed false positive was found among the six breaking findings: each claim is specific and directly supported by publisher evidence.
+
+No confirmed false negative was found in the five manually inspected findings. However, there is a material false-negative risk for Python because IA-01 does not index Python imports in this MVP. `langsmith`, `python-dotenv`, and `python-jose` are demonstrably used in VinGrade source, while IA-03 reports `DEPENDENCY_NOT_USED` for their findings. The sampled changed APIs are not used, so the final non-impact conclusions happen to be correct, but the evidence reason is not a repository-wide Python usage assertion.
+
+## 8. Model and knowledge quality
+
+### Runtime correctness
+
+- OpenAI-compatible request mapping worked with the configured remote endpoint and exact model.
+- Strict JSON Schema output parsed successfully.
+- There were no provider, authentication, timeout, truncation, or malformed-response failures.
+- Package-local skipped states were produced before runtime invocation when target or baseline facts were insufficient.
+
+### Evidence support
+
+- All six breaking findings cite evidence present in the Knowledge Evidence Bundle.
+- Manual checks confirmed the cited release content supports each selected claim.
+- No invented evidence reference or unsupported URL survived the Trust Layer.
+
+### Finding specificity
+
+- Breaking findings were concrete: removed methods/accessors, renamed SDK surface, changed dotenv mutation behavior, and removed Python runtime support.
+- Some non-breaking compatibility findings were noisy or weakly actionable, especially registry-status observations and changelog items without exact release applicability.
+
+### Knowledge/version limitations
+
+- Forty-two results retained `unknown` risk, and 46 required human review.
+- Many declarations are ranges, so current versions remain unresolved despite lockfiles being present in the repository. For example, VinGrade's `pdfjs-dist` lock entry is already 6.1.200 while Version Analysis treats the baseline as unresolved and target as 6.1.200.
+- The Trust Layer correctly retained uncertainty instead of converting these cases into precise delta claims.
+
+## 9. Report validation
+
+The generated `.upgradelens/repository-impact.md` contains:
+
+- `Status: INCOMPLETE`;
+- 44 `NOT_IMPACTED` dependency sections;
+- three `NOT_ANALYZED` dependency sections;
+- zero `IMPACTED` dependency sections;
+- an explicit incomplete-analysis warning;
+- six non-impacted breaking finding records matching IA-02/IA-03.
+
+The skipped `vite`, `langchain-core`, and unresolvable `langchain-openai` occurrence use `NOT_ANALYZED` and the safe deterministic skipped message. They do not contain `Impacted: No`. The six `Impacted: No` lines in the report belong only to breaking findings under analyzed dependencies and agree with Repository Impact Evidence.
+
+No report claim was found that was absent from the presentation view model or upstream artifacts.
+
+## 10. Repository safety
+
+Before validation, VinGrade already had a deleted tracked `Makefile` and multiple untracked user files/directories. `.upgradelens` was absent. `git diff --name-only` returned only `Makefile`.
+
+After validation, the same pre-existing changes remained and `.upgradelens/` was newly untracked. `git diff --name-only` still returned only `Makefile`.
+
+Validation did not modify tracked source, `package.json`, requirements files, lockfiles, or manifests, and did not install dependencies. All validation writes were confined to `.upgradelens/`.
+
+## 11. Known limitations
+
+- Usage Discovery is JS/TS-only in IA-01 MVP; Python impact evidence is not source-aware.
+- Range declarations do not use lockfiles as exact baselines, leaving most risk classifications unknown.
+- No real-provider breaking finding matched a used symbol in this run, so the positive `IMPACTED`/affected-file path was not exercised with live model output; its deterministic implementation remains unit-tested.
+- The public Version Analysis artifact omits provider/model identity, latency, and token usage, so those operational facts must be recorded from the controlled configuration/run rather than derived from the artifact.
+- Three occurrences remained legitimately not analyzed because of missing target/baseline facts.
+
+## 12. Final recommendation
+
+MVP-04 meets **GO WITH KNOWN LIMITATIONS** for its current JS/TS usage-discovery scope:
+
+- the real provider runtime works;
+- real Version Analysis results are produced and evidence-grounded;
+- deterministic impact/evidence stages preserve all breaking findings;
+- the IA-04 report distinguishes analyzed and not-analyzed states correctly;
+- manual inspection found no confirmed false impact conclusion in the sampled findings.
+
+MVP-05 can begin provided product claims continue to state the current language-coverage limitation and do not present Python `DEPENDENCY_NOT_USED` as proof of repository non-use. There is no remaining real-provider blocker. Stable-ID work, Python Usage Discovery, and lockfile baseline resolution remain outside this validation and were not changed.
+
+## 13. Verification
+
+- `npm test`: 403 tests, 402 passed, zero failed, one existing sandbox-related skip because local loopback listeners were unavailable.
+- `npm pack --dry-run --cache "$TMPDIR/upgradelens-npm-cache"`: passed; 132 files, approximately 321.3 kB packed.
+- `git diff --check`: passed with no output.
+- Secret check: the configured authorization value was absent from all 113 generated/report files inspected.
+- VinGrade post-run `git diff --name-only`: only the pre-existing deleted `Makefile`; validation artifacts remained untracked under `.upgradelens/`.