@thomasminh1995/depverdict 0.6.0-alpha.1

package/docs/GR-03-Extractive-Contract-Safety-Experiment.md

@@ -0,0 +1,242 @@
+# GR-03 — Extractive Contract Safety Experiment
+
+## 1. Why This Experiment Exists
+
+GR-02 left the production free-form path at `NOT_QUALIFIED`. Its versioned fake baseline correctly separated live quality, recorded containment, and injected failure fixtures, but the unchanged trust validator still published two recorded unsafe candidates:
+
+- `containment/invented-flag`: `--invented-flag` was absent from evidence;
+- `containment/semantic-unsupported`: “delete stored data” was absent from evidence.
+
+The same free-form boundary also rejected the safe prose prefix `For npm package ...` as command-like content. Adding more production regexes would address examples rather than the ownership problem: the model currently owns the final instruction, while exact excerpts establish only citation provenance.
+
+GR-03 evaluates a narrower contract:
+
+```text
+selected evidence
+  -> model selects exact action span
+  -> exact-substring and GR-02 action-criteria validation
+  -> deterministic human-review presentation
+```
+
+This is an offline experiment. It does not change or requalify the production Migration Checklist path.
+
+## 2. Current Free-Form Baseline
+
+The runner reproduces the immutable GR-02 fake baseline and fails if its key values drift.
+
+| Metric | Free-form result |
+| --- | ---: |
+| Action support | `5/5 = 1.0` |
+| Published unsupported actions | `0/5 = 0` |
+| Published ambiguous actions | `0/5 = 0` |
+| Action specificity | `5/5 = 1.0` |
+| Abstention precision / recall | `3/3` / `3/3` |
+| Unsafe containment | `15/17 = 0.8824` |
+| Invented identifier containment | `3/4 = 0.75` |
+| Prohibited capability containment | `9/10 = 0.90` |
+| Injected failure containment | `3/3 = 1.0` |
+| Recorded safe candidate acceptance | `0/1 = 0` |
+| Verdict | `NOT_QUALIFIED` |
+
+The failed critical gates remain:
+
+- `NO_PUBLISHED_INVENTED_IDENTIFIER` for `containment/invented-flag`;
+- `ALL_RECORDED_UNSAFE_CANDIDATES_CONTAINED` for the invented flag and semantic unsupported action.
+
+GR-03 does not reinterpret RR-01, GR-01, or GR-02.
+
+## 3. Experimental Candidate Contract
+
+Identity: `migration-checklist-extractive-candidate.experimental.v1`.
+
+An actionable candidate contains only evidence references and exact spans:
+
+```json
+{
+  "status": "ACTIONABLE",
+  "actions": [
+    {
+      "evidenceRef": "sha256:...",
+      "actionExcerpt": "Exact action text copied from evidence."
+    }
+  ],
+  "abstentionReason": null
+}
+```
+
+An abstention contains no action:
+
+```json
+{
+  "status": "ABSTAIN",
+  "actions": [],
+  "abstentionReason": "NO_EXPLICIT_ACTION"
+}
+```
+
+The strict schema uses `additionalProperties: false`, at most four actions, a 500-character span bound, digest-form evidence references, constrained statuses, and constrained abstention reasons. It provides no field for an instruction, item ID, dependency/finding/version identity, URL, repository location, code, command, ordering, prerequisite, rollback, effort, confidence, safety claim, or review state.
+
+The experimental prompt is separate from MP-03. It asks only for verbatim selection, prohibits paraphrase/merging/additions, and requires abstention for descriptive or ambiguous evidence. Automated GR-03 execution uses fixed candidates only; the prompt is boundary-tested but never sent to a provider.
+
+## 4. Exact Span Validation
+
+Validation is whole-candidate and fail-closed:
+
+1. Parse and validate the experimental schema.
+2. Require every `evidenceRef` in both the context allowlist and selected evidence.
+3. Normalize CRLF/CR to LF and perform exact substring membership.
+4. Reject duplicate `(evidenceRef, actionExcerpt)` pairs.
+5. Evaluate the exact span with GR-02 `migration-action-evaluation@1.0.0` criteria.
+6. Publish only `SUPPORTED`; reject `UNSUPPORTED`, `AMBIGUOUS`, and `NOT_APPLICABLE`.
+7. Apply the existing checklist instruction content guard to the deterministic presentation. An official command-like span therefore remains a documented limitation rather than weakening production containment.
+
+Exact membership contains both known trust gaps because neither unsafe phrase exists in selected evidence. It does not alone prove action eligibility; the separate GR-02 criteria check is what rejects an exact descriptive span, a forbidden expansion, or a wrong version scope in this experiment.
+
+The v2 dataset has no live action criteria for the recorded `node/whole-candidate-rejection` base case. The experiment adapter therefore declares one small, local old-client/new-client criterion for that fixture. It is not added to either dataset and is not a general production classifier.
+
+## 5. Deterministic Presentation
+
+The model does not own the final instruction. The renderer uses one constant prefix:
+
+```text
+Review this official migration instruction (human review required): <exact action span>
+```
+
+It preserves the normalized exact span without paraphrase or added technical identifiers. Stable IDs are derived from the contract, presentation version, deterministic analysis/finding identity, evidence reference, and exact span. Actions are sorted by evidence reference and excerpt.
+
+Every rendered action:
+
+- is `DETERMINISTIC_EXTRACTIVE`;
+- requires human review;
+- owns no repository location;
+- retains deterministic package/finding/version identity;
+- preserves positive candidate locations separately from the model-owned contract.
+
+The safe npm fixture succeeds because the selected evidence span is `Replace oldClient with newClient ...`; the model no longer creates the false-positive `For npm package ...` prefix. If an official exact span itself contains command-like content, the unchanged content guard rejects it and produces a deterministic fallback.
+
+## 6. Dataset Mapping
+
+The adapter consumes the immutable `migration-planning-golden@2.0.0` dataset:
+
+| Role | Count | Extractive routing |
+| --- | ---: | --- |
+| `LIVE_QUALITY` | 7 | Fixed exact evidence spans or the existing constrained abstention reason |
+| `RECORDED_CONTAINMENT` | 18 | Fixed unsafe span/field attempts; no provider |
+| `INJECTED_FAILURE` | 3 | Invalid JSON, schema-invalid output, or local runtime failure |
+
+For live actionable cases, the adapter selects the complete short action sentence from each selected evidence record. For recorded unsafe cases it preserves the unsafe intention: absent flags/actions fail exact membership; wrong/paraphrased refs fail provenance; code/command/URL/location and identity ownership fail the strict schema; mixed supported/unsupported actions reject the whole candidate. The recorded safe npm case selects its exact supporting span.
+
+Provider request count is always `0`.
+
+## 7. Safety Results
+
+| Metric | Extractive result | Adoption requirement |
+| --- | ---: | ---: |
+| Published unsupported actions | `0/5 = 0` | `0` |
+| Published ambiguous actions | `0/5 = 0` | `0` |
+| Unsafe containment | `17/17 = 1.0` | `1.0` |
+| Invented identifier containment | `4/4 = 1.0` | `1.0` |
+| Prohibited capability containment | `10/10 = 1.0` | `1.0` |
+| Injected failure containment | `3/3 = 1.0` | `1.0` |
+| Evidence ref/excerpt validity | `5/5 = 1.0` | `1.0` |
+| Identity/location/review preservation | `28/28 = 1.0` | `1.0` |
+| Deterministic replay | `28/28 = 1.0` | `1.0` |
+| Recorded safe candidate acceptance | `1/1 = 1.0` | `>= 0.80` |
+
+Critical cases:
+
+- Invented leading-dash flag: rejected as `EXCERPT_NOT_EXACT`; no action published.
+- Plain-language unsupported action: rejected as `EXCERPT_NOT_EXACT`; no action published.
+- Safe npm prose: exact official span accepted; deterministic presentation avoids the model-authored false-positive prefix.
+
+All other recorded unsafe candidates and all injected failures are contained.
+
+## 8. User-Value Results
+
+| Measure | Result |
+| --- | ---: |
+| Retained actions | `5` |
+| Action verb retention | `5/5 = 1.0` |
+| Source identifier coverage | `5/5 = 1.0` |
+| Target identifier coverage | `5/5 = 1.0` |
+| Version scope coverage | `5/5 = 1.0` |
+| Evidence reference coverage | `5/5 = 1.0` |
+| Action specificity | `5/5 = 1.0` |
+| Identifier specificity | `5/5 = 1.0` |
+| Duplicate action rate | `0/5 = 0` |
+| Mean deterministic presentation length | `132.4` characters |
+
+A bounded manual fixture review found that the exact spans identify the review action, remain short in this dataset, make human review explicit, and do not imply that UpgradeLens executed the migration.
+
+These results measure controlled fixtures, not general evidence extraction quality from a real provider.
+
+## 9. Free-Form vs Extractive Comparison
+
+| Measure | Free-form | Extractive | Delta |
+| --- | ---: | ---: | ---: |
+| Action support | `5/5` | `5/5` | none |
+| Action specificity | `5/5` | `5/5` | none |
+| Abstention precision/recall | `3/3`, `3/3` | `3/3`, `3/3` | none |
+| Unsafe containment | `15/17` | `17/17` | `+2` contained cases |
+| Invented identifier containment | `3/4` | `4/4` | `+1` |
+| Prohibited capability containment | `9/10` | `10/10` | `+1` |
+| Safe recorded acceptance | `0/1` | `1/1` | false rejection removed for the fixture |
+| Injected failures | `3/3` | `3/3` | none |
+| Verdict | `NOT_QUALIFIED` | adoption gates pass | improved |
+
+The safety delta comes from removing model ownership of novel instruction text, not from weakening command or capability guards.
+
+## 10. Complexity and Compatibility
+
+GR-03 adds four experiment implementation files:
+
+- one 42-line JSON Schema;
+- one 270-line contract/prompt/validator/renderer module;
+- one 145-line dataset adapter;
+- one 512-line comparison runner.
+
+The total experiment implementation is 969 lines. Of those, approximately 312 lines are production-equivalent contract/schema logic; 657 lines are fixture mapping, metrics, comparison, and verdict machinery that would not move into the product path.
+
+If adopted, the affected production identities/components are the candidate schema/contract, prompt, trust path, and generator. The final public Migration Checklist artifact can remain backward-compatible because deterministic code still emits review instructions with stable identity/location ownership. The provider qualification identity must change, and the safest transition is to run the extractive contract beside v1 until a fresh qualification and artifact compatibility review pass.
+
+No new public API is required if the existing generator API selects the contract internally under an explicit version. One optional contract-version selector may be useful for controlled rollout. Provider portability is favorable because the candidate remains strict provider-neutral JSON and validation is local.
+
+Because `eval/` and `docs/` are included in the npm package, GR-03 changes the dry-run package from the GR-02 baseline of 185 files / 436.0 kB to 190 files / 448.2 kB: `+5` packaged files and approximately `+12.2 kB` compressed. Production adoption should not ship the fixture runner unless it remains useful as evaluation tooling.
+
+## 11. Adoption Criteria
+
+Criteria were declared in code before the result is evaluated:
+
+- zero published unsupported and ambiguous actions;
+- complete unsafe, invented-identifier, prohibited-capability, injected-failure, evidence, ownership, and replay gates;
+- recorded safe acceptance `>= 0.80`;
+- action support `>= 0.90`;
+- abstention precision/recall `>= 0.85`;
+- action specificity `>= 0.70`;
+- identifier specificity `>= 0.60`.
+
+All 15 criteria pass. Thresholds were not lowered after observing results.
+
+## 12. Limitations
+
+- The experiment uses recorded candidates and makes no real-provider claim.
+- The dataset is small: 7 live-quality, 18 recorded-containment, and 3 injected-failure cases.
+- Dataset criteria are predeclared fixture oracles, not a general production action classifier.
+- The local old-client/new-client criterion exists only to evaluate the recorded safe and whole-candidate fixtures.
+- An official exact span containing command-like material can still fail the unchanged content guard.
+- No controlled repository or VinGrade pipeline was run.
+- No provider/model is requalified by this verdict.
+
+## 13. Final Verdict
+
+**`ADOPT_EXTRACTIVE_CONTRACT`**
+
+The experimental path passes every predeclared safety and user-value gate, contains both known unsafe fixtures, removes the safe npm false rejection for the recorded case, retains all five supported actions, and requires no provider-specific behavior.
+
+This verdict recommends the contract direction only. It does not mean production has changed, the existing provider is qualified, RR-02 is unblocked, or v0.5.0 is release-ready.
+
+## 14. Next Implementation Task
+
+Implement exactly one follow-up task: **GR-04 — Versioned Production Extractive Contract and Requalification Boundary**.
+
+That task should version the production candidate schema, prompt, trust/generator identities, define the production action-eligibility boundary explicitly, preserve the public checklist artifact, and prepare a new offline qualification identity. It must not reuse the GR-03 verdict as real-provider qualification.

package/docs/GR-04-Versioned-Production-Extractive-Contract.md

@@ -0,0 +1,154 @@
+# GR-04 — Versioned Production Extractive Contract
+
+> Historical compatibility note: GR-04 originally shipped public Migration
+> Checklist schema `1.0.0`. MP-R04 later upgrades the artifact to schema
+> `2.0.0` for deterministic handoff fields. The extractive candidate, prompt,
+> trust, and presentation identities documented here remain unchanged; v1
+> checklist artifacts must be regenerated and are not actionable handoffs.
+
+## Decision
+
+UpgradeLens now uses the extractive v2 contract for every new experimental Migration Checklist run. The historical free-form v1 generator remains available to regression and evaluation code, but the application runtime does not select it.
+
+The public `.upgradelens/migration-checklist.json` schema stays at `1.0.0`. Its existing `AI_AUTHORED` basis remains wire-compatible and now means that AI selected an official evidence span; deterministic code rendered the final human-review text. The model does not author that final instruction, item identity, repository location, or review state.
+
+This change does not enable Migration Checklist in the default `analyze` pipeline. The stage is still available only through `--experimental-migration-checklist`.
+
+## Why the free-form contract was replaced
+
+The GR-02 evaluation demonstrated that exact evidence references plus lexical checks were not a sufficient production boundary for model-authored prose. A model could add an unsupported identifier or action while retaining a valid quoted excerpt. GR-03 then demonstrated that an extractive candidate contract contains those failures and accepts the recorded safe npm prose.
+
+GR-04 productionizes only that small trust boundary. The GR-03 experiment runner, comparison policy, and experiment fixtures remain regression assets; they are not part of checklist generation.
+
+## Versioned identities
+
+| Component | Identity |
+| --- | --- |
+| Task | `migration-planning.v2` |
+| Prompt | `2` plus a canonical prompt identity digest |
+| Candidate | `migration-checklist-extractive-candidate.v2` plus schema digest |
+| Trust | `migration-checklist-trust.extractive.v2` |
+| Generator result | `2` |
+| Presentation | `migration-checklist-extractive-presentation.v1` |
+| Dataset | `migration-planning-golden` / `2.0.0` plus digest |
+| Evaluation | criteria, comparator, and normalization identities from GR-02 |
+| Qualification policy | `3.0.0` plus digest |
+
+A qualification identity also includes provider, model, adapter, runtime mode, and observed provider/model identities. Any prompt, schema, trust, generator, presentation, dataset, criteria, comparator, normalization, policy, or runtime identity change requires requalification.
+
+## Candidate and prompt boundary
+
+The strict candidate has only:
+
+```json
+{
+  "status": "ACTIONABLE",
+  "actions": [
+    {
+      "evidenceRef": "sha256:...",
+      "actionExcerpt": "Exact selected official guidance"
+    }
+  ],
+  "abstentionReason": null
+}
+```
+
+An abstention contains no actions and one constrained reason. Every object rejects additional properties. At most four actions are allowed and each excerpt is bounded to 500 characters.
+
+The model is a bounded evidence-span selector. It can copy a verbatim span from selected evidence or abstain. It cannot emit final instructions, identity, versions, URLs, locations, code, commands, patches, prerequisites, ordering, rollback, effort, confidence, safety, approval, completion, or reasoning. The model-visible context continues to use the MP-02 projection and excludes repository source and deterministic candidate locations.
+
+## Production trust path
+
+The production validator applies:
+
+1. strict candidate schema and status semantics;
+2. exact context evidence allowlist membership;
+3. selected evidence record existence;
+4. line-ending normalization only;
+5. exact substring membership in the same evidence record;
+6. duplicate `(evidenceRef, actionExcerpt)` rejection;
+7. whole-candidate structural and prohibited-content validation.
+
+GR-02 action criteria are not used by the production trust validator. They remain controlled evaluation criteria. Production exact-span validation establishes provenance, exact membership, ownership, and structural safety. It does not establish semantic applicability to the repository.
+
+Command-like or code-like official spans remain outside the MVP checklist capability. They fail closed and produce a deterministic manual-review fallback while preserving the selected evidence references.
+
+## Deterministic presentation and ownership
+
+Accepted spans are rendered with the constant prefix:
+
+```text
+Review this selected official migration guidance (human review required): <exact span>
+```
+
+The normalized exact span is preserved without paraphrase. Existing deterministic code owns checklist IDs, ordering, package/finding/version identity, `requiresHumanReview: true`, and positive candidate locations. AI-selected items own no locations. Presentation labels use “AI-selected official guidance,” not “AI-authored action” or “verified action.”
+
+The legacy public basis value `AI_AUTHORED` is retained solely for schema compatibility. It represents AI-assisted selection followed by deterministic rendering in v2.
+
+## Runtime and failure behavior
+
+`runMigrationChecklistStage` now defaults internally to `generateMigrationExtractiveChecklistDrafts`. The provider-neutral `AiRuntime.generateStructured()` call remains one call per eligible context. MP-02 fallback records do not call the runtime.
+
+Abstention, provider failure, invalid schema, unknown evidence, non-exact text, duplicate spans, and prohibited content are package-local safe outcomes. They publish no unsafe item, preserve unrelated contexts, create a deterministic fallback, and expose only constrained reason codes. Invalid normalized context, duplicate identity, corrupted qualification identity, programming invariants, and final artifact validation remain fatal.
+
+Progress event names are unchanged and contain no raw prompt, response, or evidence content.
+
+## Qualification boundary
+
+The application guard now expects the complete extractive v2 identity. Therefore:
+
+- a free-form v1 record cannot qualify v2;
+- a fake v2 qualification cannot qualify a real runtime;
+- a missing v2 real qualification remains `EXPERIMENTAL` only when explicit experimental policy is enabled;
+- provider, model, or adapter mismatch invalidates the record;
+- a matching explicit `NOT_QUALIFIED` record blocks the run;
+- the historical v1 `NOT_QUALIFIED` result is unchanged and is treated as a different identity.
+
+The checklist reports `NOT_AVAILABLE` when no matching real v2 qualification exists. No qualification database or provider-specific behavior was added.
+
+## Offline production evaluation
+
+The production extractive generator runs through the versioned GR-02 evaluation layer using local role-routed fixtures:
+
+| Boundary | Result |
+| --- | --- |
+| Live-quality cases | `7` |
+| Recorded containment cases | `18` |
+| Recorded unsafe containment | `17/17` |
+| Recorded safe acceptance | `1/1` |
+| Prohibited capability containment | `10/10` |
+| Injected failures | `3/3` |
+| Published unsupported actions | `0` |
+| Published ambiguous actions | `0` |
+| Provider requests | `0` |
+| Critical gates | all pass |
+| Fake verdict | `QUALIFIED_WITH_LIMITATIONS` |
+
+The evaluation criteria measure action support and specificity. They do not become a general production classifier. The deterministic prefix is presentation text, so evaluation measures support against the exact selected span and separately checks the published prefix for prohibited capabilities and ownership.
+
+## Packaging and complexity
+
+Production-specific schema, candidate/trust, and prompt code are 270 lines before generator/qualification integration. No dependency was added. Shared generator and evaluation modules were extended instead of copying the GR-03 comparison runner.
+
+The npm `files` list retains the general evaluation datasets/schemas and the two historical/versioned migration golden datasets. The GR-03 experiment runner, fixtures, and experiment candidate schema remain in the repository for regression value but are excluded from the package. `npm pack --dry-run` reports 191 files / 447.8 kB: one more file and about 0.4 kB less compressed than the GR-03 package (190 files / 448.2 kB), or six more files and about 11.8 kB more than the GR-02 baseline (185 files / 436.0 kB).
+
+## Compatibility
+
+- Public Migration Checklist schema: unchanged `1.0.0`.
+- Historical v1 prompt, candidate, trust, generator, dataset digests, and evaluation entry points: retained.
+- Default CLI: Migration Checklist still absent.
+- Experimental CLI: uses extractive v2.
+- Provider integration: unchanged and provider-neutral.
+- Thresholds: unchanged.
+
+## Known limitations
+
+- Exact official text does not prove that the guidance applies to a particular repository usage.
+- Official command/code-like spans are not published as executable-looking checklist instructions.
+- The versioned dataset is intentionally small.
+- No real provider has been evaluated for v2.
+- `AI_AUTHORED` remains a legacy wire name whose v2 meaning requires this compatibility note.
+
+## Requalification boundary
+
+GR-04 is ready for a separate real-provider decision only after focused, full-suite, packaging, and diff validation pass. GR-04 itself performs no real-provider call and no repository validation.

package/docs/IA-01-Repository-Usage-Discovery.md

@@ -0,0 +1,122 @@
+# IA-01 — Repository Usage Discovery
+
+## 1. Architecture review
+
+UpgradeLens đã có boundary tốt giữa các MVP:
+
+- Project Manifest sở hữu project và dependency declarations.
+- Version Analysis sở hữu tập dependency occurrences sẽ đi tiếp vào MVP-04.
+- Usage Discovery chỉ sở hữu facts lấy từ source code: dependency, symbol và file.
+
+IA-01 không đọc findings/risk/release notes trong Version Analysis, không match breaking change, không chấm severity và không tạo migration plan. Version Analysis chỉ được dùng để giới hạn dependency scope và giữ `packageId`/`projectId` nhất quán với downstream pipeline.
+
+Các technical debt phát hiện trước khi implement:
+
+1. `src/files.js` chỉ scan manifest candidates. Source discovery cần walker riêng nhưng phải dùng cùng ignored-directory policy, không follow symlink và sort deterministic.
+2. Repository chưa có JS/TS AST parser. Regex không đủ an toàn cho JSX, TS, alias, type import và re-export. IA-01 thêm duy nhất `@babel/parser`; analyzer tự làm một lexical binding pass nhỏ nên không cần thêm traversal framework.
+3. Dependency name không đủ làm identity trong monorepo. Usage Index phải giữ cả `projectId` và `packageId`.
+4. Source tree hiện chưa có artifact lineage/revision digest. Index ghi portable file paths nhưng không tuyên bố reproducible theo commit khi input chưa cung cấp source revision.
+5. Project Manifest đã detect nhiều ecosystem nhưng dependency inventory mới đầy đủ chủ yếu ở Node/Python. Plugin contract cho phép thêm analyzer mới; MVP chỉ đăng ký JS/TS cho `node`.
+
+## 2. Runtime flow
+
+```text
+project-manifest.json ----\
+                          +--> validate schema, lineage, dependency references
+version-analysis.json ---/                         |
+                                                    v
+repository --> deterministic source scanner --> deepest project ownership
+                                                    |
+                                                    v
+                                            analyzer registry
+                                                    |
+                                            JS/TS AST analyzer
+                                                    |
+                                                    v
+                                              Usage Index
+                                  project + dependency + symbol + file
+```
+
+Một syntax error chỉ tạo warning cho file đó. Các file còn lại vẫn được phân tích. Trong monorepo, source file thuộc project sâu nhất chứa nó; root workspace không được nhận usage của member project. File của project không có dependency occurrence trong Version Analysis không bị scan nhầm dưới scope của root.
+
+## 3. Module structure
+
+```text
+src/usage/
+  analyzer-registry.js   static plugin registry and capability selection
+  input-loader.js        artifact validation, lineage, occurrence references
+  runtime.js             orchestration and project ownership
+  scope.js               Version Analysis occurrence to declared dependency scope
+  source-files.js        deterministic source inventory
+  usage-index.js         canonical index builder and validation
+  writer.js              deterministic atomic artifact output
+  js/
+    analyzer.js          npm matching, binding/reference and usage extraction
+    parser.js            Babel JS/JSX/TS/TSX AST parsing
+
+schemas/
+  usage-index.schema.json
+```
+
+Analyzer plugin contract tối thiểu:
+
+```js
+{
+  id: 'javascript-typescript',
+  version: '1.0.0',
+  ecosystems: ['node'],
+  extensions: ['.js', '.jsx', '.ts', '.tsx'],
+  analyze({ source, file, projectId, dependencies }) { /* usage facts */ }
+}
+```
+
+Registry là static composition, không dynamic-load arbitrary code. Thêm Python/Java/Go/Rust analyzer sau này không làm thay đổi runtime hoặc Usage Index contract.
+
+## 4. JS/TS MVP semantics
+
+- Hỗ trợ `.js`, `.jsx`, `.mjs`, `.cjs`, `.ts`, `.tsx`, `.mts`, `.cts`.
+- Named import được index theo exported name; alias local không làm đổi symbol.
+- Default import dùng symbol ổn định `default`.
+- Namespace member như `Ant.Button` được index thành `Button`; namespace dùng như một value được index thành `*`.
+- `export { Button } from`, default re-export và `export * from` là usages trực tiếp.
+- Static imported binding chỉ được index khi có lexical reference; unused và shadowed binding bị loại.
+- Constant dynamic import `import('antd')` dùng symbol `*`; computed dynamic import bị bỏ qua.
+- Side-effect-only import vẫn tạo dependency/file location nhưng không tạo symbol giả.
+- npm subpath quy về package declaration (`antd/es/button` → `antd`, `@scope/ui/button` → `@scope/ui`). Relative, absolute, URL, `node:` và package import-map specifier không được coi là external dependency.
+- `.upgradelens`, `node_modules`, build outputs và các ignored directories hiện có không được scan; symlink không được follow.
+
+Known MVP limitations:
+
+- CommonJS `require()` chưa thuộc contract IA-01.
+- Không thực hiện module resolution, path alias resolution hoặc type checker semantics.
+- Dynamic import không phải string literal bị bỏ qua deterministic.
+- Source parse failure không có partial usage cho file lỗi.
+- Chưa lưu line/column theo đúng scope của task.
+
+## 5. Usage Index contract
+
+Artifact mặc định: `.upgradelens/usage-index.json`, schema version `1.0.0`.
+
+```json
+{
+  "projectId": "node:.",
+  "packageId": "npm:antd",
+  "name": "antd",
+  "files": ["src/pages/Home.tsx", "src/components/UserModal.tsx"],
+  "symbols": [
+    { "name": "Button", "files": ["src/pages/Home.tsx"] },
+    { "name": "Modal", "files": ["src/components/UserModal.tsx"] }
+  ]
+}
+```
+
+Mọi dependency, symbol, file và warning đều được sort deterministic. `files` ở dependency level bao gồm cả side-effect usage; `symbols[].files` là API/symbol locations. Writer validate lại schema/invariants rồi publish atomically, không sửa Project Manifest hoặc Version Analysis.
+
+Runtime API mặc định đọc hai input trong `.upgradelens` và không tự ghi file:
+
+```js
+const index = await runUsageDiscovery({ repositoryRoot });
+await writeUsageIndex(DEFAULT_USAGE_INDEX_PATH, index);
+```
+
+Tách discovery khỏi writer giúp caller có thể validate/inspect output trước khi publish và giữ mọi filesystem mutation explicit.

package/docs/IA-02-Repository-Impact-Analysis.md

@@ -0,0 +1,118 @@
+# IA-02 — Repository Impact Analysis Engine
+
+## 1. Architecture review
+
+Kiến trúc hiện tại phù hợp để thêm Impact Analysis như một artifact-to-artifact stage độc lập:
+
+- Version Analysis cung cấp dependency identity và breaking-change findings.
+- Usage Index cung cấp canonical `projectId`, `packageId`, symbol và portable file paths.
+- IA-02 không cần biết analyzer nào đã tạo usage, ngôn ngữ source hoặc cấu trúc repository.
+
+Boundary được giữ rõ ràng: Impact Engine không scan repository, không parse source, không gọi AI, không đọc internet, không tính severity/confidence và không tạo migration plan.
+
+Technical debt quan trọng:
+
+1. Version Analysis finding `1.0.0` chưa có `affectedSymbols` có cấu trúc; chỉ có free-text `summary`. Vì không được sửa artifact MVP trước, IA-02 MVP dùng lexical exact matching trên chính các symbol đã có trong Usage Index.
+2. Usage Index hiện có symbol-level granularity. Với finding `Modal.info removed` và usage symbol `Modal`, engine có thể xác nhận `Modal` được dùng nhưng chưa biết repository gọi đúng member `info` hay member khác. Đây là conservative symbol-level impact, không phải member-level proof.
+3. Symbol `*` và `default` là canonical/synthetic tokens của IA-01, không phải API names đủ chính xác để match free text. Matcher loại chúng khỏi automatic impact.
+4. Future precision nên đến từ một Version Analysis schema mới có structured affected API paths và một Usage Index mới có optional member paths. Runtime/matcher boundary hiện tại cho phép thêm matcher đó mà không phụ thuộc source language.
+
+IA-02 không sửa Version Analysis hoặc Usage Index để xử lý các debt này.
+
+## 2. Runtime flow
+
+```text
+project-manifest.json ----\
+version-analysis.json -----+--> schema + invariant + exact lineage validation
+usage-index.json ----------/                         |
+                                                       v
+                                    breakingChange findings only
+                                                       +
+                                          dependency usage symbols
+                                                       |
+                                                       v
+                                      exact-symbol rule matcher
+                                                       |
+                                                       v
+                                      Repository Impact model
+                                                       |
+                                                       v
+                              .upgradelens/repository-impact.json
+```
+
+Project Manifest được dùng tại trust boundary để xác nhận Version Analysis vẫn thuộc đúng repository/dependency declarations. Runtime matching chỉ consume Version Analysis và Usage Index đã validate.
+
+## 3. Module structure
+
+```text
+src/impact/
+  input-loader.js         three-artifact validation and lineage
+  matcher.js              exact lexical symbol rule
+  repository-impact.js    model builder, summary, schema/invariants
+  runtime.js              pure orchestration
+  writer.js               deterministic atomic publication
+
+schemas/
+  repository-impact.schema.json
+```
+
+Matcher boundary:
+
+```js
+{
+  id: 'exact-symbol',
+  version: '1.0.0',
+  match(finding, dependencyUsage) {
+    // returns [{ symbol, files }]
+  }
+}
+```
+
+Matcher không chứa JavaScript/TypeScript logic. Analyzer của IA-01 đã normalize mọi language về cùng Usage Index contract, nên Python/Java/Go/Rust analyzers tương lai không yêu cầu đổi Impact runtime.
+
+## 4. Exact matching rules
+
+- Chỉ `finding.kind === "breakingChange"` tham gia output/matching.
+- Match phân biệt hoa/thường.
+- Symbol phải xuất hiện nguyên vẹn với Unicode identifier boundaries.
+- `Modal` match `Modal` và root của API path `Modal.info`.
+- `Modal` không match `Modal2`, `LegacyModal` hoặc `modal`.
+- Không stemming, lowercase normalization, edit distance, synonyms hoặc semantic inference.
+- `*` và `default` không tự động match.
+- Dependency lookup dùng exact pair `projectId + packageId`; không match chỉ bằng display name.
+- Dependency không có Usage Index entry là `impacted: false`, không phải input error.
+- Usage Index entry không có Version Analysis result là invalid artifact reference.
+
+Mọi breaking finding được giữ trong dependency result. Finding không match có `impacted: false` và `matches: []`; vì vậy multiple findings không bị mất và not-impacted result audit được.
+
+## 5. Output model
+
+Artifact mặc định: `.upgradelens/repository-impact.json`, schema version `1.0.0`.
+
+```json
+{
+  "analysisResultId": "sha256:...",
+  "projectId": "node:.",
+  "packageId": "npm:antd",
+  "name": "antd",
+  "impacted": true,
+  "findings": [
+    {
+      "id": "modal-info-removed",
+      "kind": "breakingChange",
+      "summary": "Modal.info was removed.",
+      "impacted": true,
+      "matches": [
+        {
+          "symbol": "Modal",
+          "files": ["src/components/Dialog.tsx", "src/pages/Home.tsx"]
+        }
+      ]
+    }
+  ]
+}
+```
+
+Top-level summary trả lời trực tiếp repository có impacted hay không, cùng số dependency, finding, symbol match và affected file. `analysisResultId` giữ quan hệ chính xác khi cùng package có nhiều target analysis.
+
+Dependency, finding, match và file arrays đều được sort deterministic. Writer validate schema/runtime invariants trước khi atomic rename và không thay đổi ba input artifacts.