@thomasminh1995/depverdict 0.6.0-alpha.1

package/docs/live-ai-validation.md

@@ -0,0 +1,299 @@
+# Live AI Validation — Model + Real Evidence
+
+Date: 2026-07-15
+
+## Executive Summary
+
+Live AI Validation is **not complete**.
+
+UpgradeLens successfully ran the real-evidence portion of the production pipeline:
+
+```text
+discover
+  ↓
+research
+  ↓
+knowledge-manifest.json
+knowledge-evidence-bundle.json
+```
+
+The validation then stopped at `analyze-version` because no real AI runtime was configured in the environment. The run did **not** use a fake runtime, golden runtime, registry fixtures, or manually edited evidence.
+
+This means the MVP-02-09 blocker is resolved for real registry evidence, but the live model gate is still blocked by runtime configuration.
+
+## Repository
+
+Preferred repository: `VinGrade`
+
+Result: `VinGrade` was not available in the local filesystem during validation.
+
+Fallback repository: `UpgradeLens`
+
+Validation root:
+
+```text
+<TEMPORARY_LIVE_VALIDATION_REPOSITORY>
+```
+
+The fallback repository was a temporary copy containing the real `UpgradeLens` package manifest. This avoided modifying the working repository while still exercising the production CLI against real npm registry metadata.
+
+Repository dependencies discovered:
+
+| Dependency | Declared Version | Ecosystem |
+| ---------- | ---------------- | --------- |
+| `ajv` | `^8.18.0` | npm |
+| `ajv-formats` | `^3.0.1` | npm |
+| `undici` | `^6.27.0` | npm |
+
+The repository has only three discovered dependencies, so the requested random review of at least five dependencies could not be completed with this repository.
+
+## Model
+
+Model: **not available**
+
+Runtime environment:
+
+```text
+UPGRADELENS_AI_ENDPOINT       unset
+UPGRADLENS_AI_ENDPOINT        unset
+UPGRADELENS_AI_PROVIDER       unset
+UPGRADELENS_AI_MODEL          unset
+UPGRADELENS_AI_AUTHORIZATION  unset
+OPENAI_API_KEY                unset
+OPENAI_BASE_URL               unset
+OPENAI_MODEL                  unset
+ANTHROPIC_API_KEY             unset
+GOOGLE_API_KEY                unset
+```
+
+The CLI requires a configured `UPGRADELENS_AI_ENDPOINT` or an injected `AiRuntime`. Injection was intentionally not used because this validation forbids fake or golden runtimes.
+
+## Prompt Version
+
+Prompt version: `1`
+
+Source: `VERSION_ANALYSIS_PROMPT_VERSION` in `src/ai-version-analysis.js`.
+
+## Pipeline Result
+
+| Step | Result | Notes |
+| ---- | ------ | ----- |
+| `discover` | PASS | Project Manifest was generated in the temporary repository. |
+| `research` | PASS | Real npm registry evidence was fetched after running with network permission. |
+| `analyze-version` | FAIL | Blocked because no real AI runtime was configured. |
+| `eval` | NOT RUN | Would fall back to golden fake without a configured runtime; skipped to respect validation rules. |
+| `scorecard` | NOT RUN | Depends on evaluation output; skipped. |
+| `benchmark` | NOT RUN | Depends on model/runtime validation; skipped. |
+
+Command evidence:
+
+```text
+node bin/upgradelens.js discover <TEMPORARY_LIVE_VALIDATION_REPOSITORY>
+```
+
+Result:
+
+```text
+Discovered 1 project(s).
+Manifest: <TEMPORARY_LIVE_VALIDATION_REPOSITORY>/.upgradelens/project-manifest.json
+```
+
+```text
+node bin/upgradelens.js research <TEMPORARY_LIVE_VALIDATION_REPOSITORY>
+```
+
+Result:
+
+```text
+✓ Loaded Project Manifest
+✓ Planned research (3 packages)
+✓ Research complete
+✓ Knowledge Manifest validated
+✓ Wrote:
+<TEMPORARY_LIVE_VALIDATION_REPOSITORY>/.upgradelens/knowledge-manifest.json
+✓ Knowledge Evidence Bundle validated
+✓ Wrote:
+<TEMPORARY_LIVE_VALIDATION_REPOSITORY>/.upgradelens/knowledge-evidence-bundle.json
+```
+
+```text
+node bin/upgradelens.js analyze-version <TEMPORARY_LIVE_VALIDATION_REPOSITORY>
+```
+
+Result:
+
+```text
+upgradelens: AI runtime is not configured. Set UPGRADELENS_AI_ENDPOINT or provide an AiRuntime.
+```
+
+## Artifact Summary
+
+### Project Manifest
+
+Generated:
+
+```text
+<TEMPORARY_LIVE_VALIDATION_REPOSITORY>/.upgradelens/project-manifest.json
+```
+
+### Knowledge Manifest
+
+Generated:
+
+```text
+<TEMPORARY_LIVE_VALIDATION_REPOSITORY>/.upgradelens/knowledge-manifest.json
+```
+
+Package resolution:
+
+| Package | Status | Registry Latest |
+| ------- | ------ | --------------- |
+| `npm:ajv` | resolved | `8.20.0` |
+| `npm:ajv-formats` | resolved | `3.0.1` |
+| `npm:undici` | resolved | `8.7.0` |
+
+Warnings: `0`
+
+### Knowledge Evidence Bundle
+
+Generated:
+
+```text
+<TEMPORARY_LIVE_VALIDATION_REPOSITORY>/.upgradelens/knowledge-evidence-bundle.json
+```
+
+Summary:
+
+```json
+{
+  "schemaVersion": "1.0.0",
+  "evidenceCount": 3,
+  "warningCount": 0
+}
+```
+
+Evidence references:
+
+| Package | Evidence ID | Kind | Release Versions |
+| ------- | ----------- | ---- | ---------------- |
+| `npm:ajv` | `sha256:4857f89db56ac95775a1fcb4fdac2aff719481300f1e0d79ece558190c117273` | `registryFact` | `8.20.0` |
+| `npm:undici` | `sha256:4b0e9da799e844dff7e608252d103e6c49260b35bda6f0a88753d7d55f7ffac3` | `registryFact` | `8.7.0` |
+| `npm:ajv-formats` | `sha256:b8e04856e6cafc92fe70e2b15d36fcdfb952494e003fbd63f0c3b168f7269bef` | `registryFact` | `3.0.1` |
+
+## AI Output Review
+
+AI output was not produced because `analyze-version` could not construct a real runtime.
+
+Validation answers:
+
+| Question | Answer |
+| -------- | ------ |
+| Artifact được sinh đầy đủ? | NO — Project, Knowledge Manifest, and Evidence Bundle were generated; Version Analysis was not. |
+| AI có trả structured output hợp lệ? | NO — no model call occurred. |
+| Trust Layer có pass? | NO — trust validation could not run without AI output. |
+| Evidence references hợp lệ? | PARTIAL — bundle references are valid before AI; AI evidence references could not be assessed. |
+| Invented evidence reference? | Not assessable — no AI output. |
+
+## Trust Review
+
+Trust layer execution was blocked by missing AI runtime.
+
+Pre-AI checks that did pass:
+
+- real registry evidence bundle was generated;
+- bundle schema validated;
+- evidence IDs were deterministic digests;
+- evidence referenced known package IDs and source IDs;
+- no bundle-level evidence conflicts were present;
+- no manually edited or injected evidence was used.
+
+Trust checks not reached:
+
+- invented evidence reference detection;
+- invented URL detection;
+- deterministic field mutation protection;
+- risk downgrade;
+- human-review policy on model output.
+
+## Human Review
+
+Human review policy could not be evaluated against AI output.
+
+Manual dependency review from available repository dependencies:
+
+| Dependency | Observed Version Situation | Manual Review |
+| ---------- | -------------------------- | ------------- |
+| `ajv` | Declared `^8.18.0`, registry latest `8.20.0` | Likely low-to-medium operational risk, but declared constraint means installed version is unresolved and should require review under current policy. |
+| `ajv-formats` | Declared `^3.0.1`, registry latest `3.0.1` | Likely no upgrade delta if installed version is already compatible, but exact installed version is unresolved. |
+| `undici` | Declared `^6.27.0`, registry latest `8.7.0` | Major-version target from 6 to 8 appears higher risk and should require human review. |
+
+The requested sample size of five dependencies was not possible because the fallback repository exposes only three dependencies.
+
+## Evaluation Result
+
+`upgradelens eval` was intentionally not run.
+
+Reason: with no configured real runtime, the current CLI would use the golden fake runtime by default. That would violate this validation's rule:
+
+```text
+Không dùng Fake Runtime
+Không dùng Golden Runtime
+```
+
+## Benchmark Result
+
+`upgradelens benchmark` was intentionally not run.
+
+Reason: benchmark must validate a real model/runtime for this task. No model runtime was configured.
+
+## Known Issues
+
+### Critical
+
+- Live AI validation cannot complete until a real `UPGRADELENS_AI_ENDPOINT` is configured.
+
+### High
+
+- No local `VinGrade` repository was available, so the preferred real repository could not be used.
+- The fallback `UpgradeLens` dependency set has only three dependencies, which is insufficient for the requested five-dependency manual review sample.
+
+### Medium
+
+- The real Evidence Bundle currently contains registry facts only. This proves portability and lineage, but it is still thin evidence for high-quality risk analysis.
+- If `eval` is run without a configured endpoint, it falls back to golden fake runtime. That is useful for CI but unsafe for live-model validation unless explicitly called out.
+
+### Low
+
+- The first sandboxed `research` run produced `REGISTRY_UNAVAILABLE`; the registry run succeeded only after network permission was granted.
+
+## Recommended Backlog
+
+1. Provide a real AI runtime configuration for validation:
+
+   ```text
+   UPGRADELENS_AI_ENDPOINT
+   UPGRADELENS_AI_PROVIDER
+   UPGRADELENS_AI_MODEL
+   UPGRADELENS_AI_AUTHORIZATION, if required
+   ```
+
+2. Re-run this validation on `VinGrade` or another repository with at least five dependencies.
+
+3. Add a documented live-validation benchmark config that uses `runtime.type = "environment"` so benchmark can run against the configured provider without relying on golden fake.
+
+4. Expand Evidence Bundle production beyond registry facts when release notes, changelog, or migration-guide source candidates are available.
+
+5. Add a CLI safety option for live validation to fail if evaluation would fall back to golden fake runtime.
+
+## MVP-04 Readiness Decision
+
+Decision: **NO GO for Live AI Validation completion**.
+
+Reason:
+
+- Real evidence generation works.
+- Portable Evidence Bundle exists and validates.
+- The live model step did not run because no real runtime is configured.
+- Therefore there is no evidence yet that structured model output, trust validation, human-review policy, evaluation, scorecard, and benchmark work end-to-end with a real model.
+
+This is not a source-code blocker discovered in UpgradeLens. It is an environment/configuration blocker for live validation.

package/docs/migration-planning-qualification-resolution.md

@@ -0,0 +1,99 @@
+# Migration Planning qualification resolution
+
+The experimental Migration Checklist uses one immutable qualification decision
+for the complete stage. Qualification resolution is deterministic and does not
+contact a provider or re-run evaluation.
+
+## When resolution runs
+
+The normal `depverdict analyze <repository>` pipeline does not include the
+Migration Checklist and does not resolve a qualification record. Resolution
+runs only when the user explicitly enables:
+
+```text
+depverdict analyze <repository> --experimental-migration-checklist
+```
+
+The default persisted record is repository-local:
+
+```text
+.depverdict/migration-planning-qualification.json
+```
+
+An alternative portable path relative to the repository may be selected with:
+
+```text
+--migration-qualification <path>
+```
+
+Absolute paths and paths that escape the repository contract are rejected.
+
+## Source precedence
+
+Exactly one source is selected in this order:
+
+1. a qualification injected through the application API;
+2. the explicit `--migration-qualification` path;
+3. the default project-local path;
+4. a missing-record decision.
+
+The selected record is validated as a complete unit. A missing or invalid
+explicit source never falls back to the default path. A corrupted default
+record never falls back to a missing-record decision.
+
+## Decision states
+
+| State | Execution | Meaning |
+| --- | --- | --- |
+| `QUALIFIED` | allowed | The record matches the exact task and runtime identity and all required gates passed. |
+| `QUALIFIED_WITH_LIMITATIONS` | allowed | The record matches and execution retains its recorded limitations. |
+| `MISSING` | experimental exception only | No default record exists. The opt-in experimental CLI path may continue with mandatory human review. |
+| `NOT_QUALIFIED` | blocked | A matching runtime failed a critical qualification gate or threshold. |
+| `INSUFFICIENT_EVIDENCE` | blocked | A matching record does not contain enough evidence for execution. |
+| `IDENTITY_MISMATCH` | blocked | Task, provider, model, adapter, dataset, prompt, schema, policy, or runtime identity differs. Fake-runtime evidence also falls into this fail-closed class for a real runtime. |
+| `CORRUPTED` | blocked | JSON, schema, invariant, digest, or sensitive-value validation failed. |
+
+Only a genuinely missing default record may use the existing experimental
+exception. Missing explicit records, corrupted records, identity mismatches,
+fake qualifications, insufficient evidence, and matching `NOT_QUALIFIED`
+records block before provider use.
+
+## Integrity and identity
+
+The persisted artifact follows
+`schemas/migration-planning-qualification-record.schema.json`. Loading verifies
+the schema, the qualification identity digest, the record digest, deterministic
+ordering, verdict invariants, and the absence of secret-like values.
+
+Runtime matching binds the decision to the exact Migration Planning v2 task,
+provider, model, adapter, evaluation dataset, prompt, candidate schema,
+grounding policy, and other versioned qualification inputs. Changing one of
+those inputs requires a matching record; it is not silently accepted.
+
+Use the public writer to persist a completed qualification:
+
+```js
+import { writeMigrationPlanningQualificationRecord } from '@thomasminh1995/depverdict';
+
+await writeMigrationPlanningQualificationRecord(
+  repositoryRoot,
+  evaluationReport.report.qualification
+);
+```
+
+The writer validates first and publishes atomically. Qualification status,
+reason, source kind, source path, runtime identity, limitations, and next
+action come from the same frozen decision used by the guard, progress events,
+console presentation, failure log, and migration artifact assembly.
+
+During the `0.6.x` preview compatibility window, a complete default record under
+`.upgradelens/` may be selected only through the whole-root fallback contract.
+DepVerdict never merges qualification or workflow inputs across artifact roots.
+An explicit legacy path remains caller-owned and is honored as written.
+
+## Limitations
+
+Migration Checklist remains experimental, opt-in, and mandatory-human-review.
+A persisted qualification permits the exact qualified runtime to execute; it
+does not make generated migration instructions automatically safe, enable the
+feature by default, or replace review of cited evidence.

package/docs/migrations/upgradelens-to-depverdict.md

@@ -0,0 +1,97 @@
+# UpgradeLens to DepVerdict migration
+
+DepVerdict is the canonical product identity beginning with
+`0.6.0-alpha.1`. This guide covers the bounded `0.6.x` preview transition. It
+does not change historical artifact schemas or move local data automatically.
+
+## Identity map
+
+| Old | New | Compatibility |
+| --- | --- | --- |
+| `upgradelens` npm identity | `@thomasminh1995/depverdict` | The old npm package was never successfully published; install the scoped package after its preview distribution gate passes. |
+| `upgradelens` CLI | `depverdict` | The alias remains for one `0.6.x` preview window and emits a bounded stderr warning. |
+| `.upgradelens/` | `.depverdict/` | A complete legacy input chain may be read as fallback; new implicit writes are canonical. |
+| `UPGRADELENS_*` | `DEPVERDICT_*` | Canonical variables win; legacy fallback warns without printing values. |
+| GitHub UpgradeLens URL | GitHub DepVerdict URL | The rename is complete. Use the DepVerdict URL directly; the former URL is a redirect compatibility aid, not an operational dependency. |
+
+## Commands and installation
+
+New commands should use:
+
+```sh
+depverdict analyze .
+depverdict analyze . --offline
+depverdict analyze . --fail-on-incomplete
+```
+
+The planned npm preview install command is:
+
+```sh
+npm install -g @thomasminh1995/depverdict@preview
+```
+
+The preview has not yet passed final distribution qualification, so this command
+is not presented as currently guaranteed to succeed. Until publication, run the
+canonical source executable:
+
+```sh
+node ./bin/depverdict.js --help
+```
+
+Do not install an `upgradelens` npm package as a migration step.
+
+## Artifact migration
+
+New implicit writes go to `.depverdict/`. DepVerdict does not automatically move,
+copy, delete, or merge `.upgradelens/` data.
+
+Automatic compatibility reads select one complete root:
+
+1. a complete canonical chain wins;
+2. a complete legacy chain may be used only when no canonical chain member exists;
+3. partial, split, or conflicting roots fail closed;
+4. explicitly supplied paths remain authoritative, including explicit legacy
+   paths.
+
+Do not combine files from the two roots to manufacture a complete chain. Historical
+schemas and existing artifacts remain valid under their original protocol
+identities; the brand migration does not rewrite `generator.name`, schema names,
+task IDs, reason codes, or lineage.
+
+## Environment migration
+
+Rename each supported variable key without printing or copying its value into logs:
+
+| Legacy | Canonical |
+| --- | --- |
+| `UPGRADELENS_AI_PROVIDER` | `DEPVERDICT_AI_PROVIDER` |
+| `UPGRADELENS_AI_ENDPOINT` | `DEPVERDICT_AI_ENDPOINT` |
+| `UPGRADELENS_AI_MODEL` | `DEPVERDICT_AI_MODEL` |
+| `UPGRADELENS_AI_AUTHORIZATION` | `DEPVERDICT_AI_AUTHORIZATION` |
+| `UPGRADELENS_AI_TIMEOUT_MS` | `DEPVERDICT_AI_TIMEOUT_MS` |
+| `UPGRADELENS_AI_TIMEOUT_SECONDS` | `DEPVERDICT_AI_TIMEOUT_SECONDS` |
+| `UPGRADELENS_AI_MAX_RESPONSE_BYTES` | `DEPVERDICT_AI_MAX_RESPONSE_BYTES` |
+| `UPGRADELENS_AI_DEBUG` | `DEPVERDICT_AI_DEBUG` |
+
+Edit secret stores manually. Never print an authorization value to verify the
+rename. When both mapped keys exist, the canonical key wins and DepVerdict emits a
+key-only diagnostic.
+
+## Repository transition
+
+The repository rename is complete. Use the canonical routes directly:
+
+- repository: `https://github.com/thomasMinh1995/DepVerdict`;
+- issues: `https://github.com/thomasMinh1995/DepVerdict/issues`;
+- private security reports:
+  `https://github.com/thomasMinh1995/DepVerdict/security/advisories/new`.
+
+The former `https://github.com/thomasMinh1995/UpgradeLens` route redirects for
+continuity, but current operations and metadata do not depend on that redirect.
+
+## Compatibility removal
+
+The compatibility window is preview-bounded, not an indefinite support guarantee
+or a stable calendar deadline. Removing the CLI alias, artifact fallback, or
+environment fallback requires a separate decision, release note, consumer-usage
+review, canonical-only regression validation, and explicit release authorization.

package/docs/mp-r03-deterministic-upgrade-decision-architecture.md

@@ -0,0 +1,135 @@
+# MP-R03 Deterministic Upgrade Decision Architecture
+
+## Decision boundary
+
+The Upgrade Decision stage runs after Repository Impact Evidence and before
+Migration Checklist context preparation. It is deterministic and performs no
+provider or model calls.
+
+The stage consumes the same seven validated upstream artifacts that form the
+existing checklist boundary:
+
+1. Project Manifest
+2. Knowledge Manifest
+3. Knowledge Evidence Bundle
+4. Version Analysis
+5. Usage Index
+6. Repository Impact
+7. Repository Impact Evidence
+
+This is the smallest existing boundary that has exact dependency occurrence
+identity, installed and target versions, target-scoped evidence, analysis
+state, repository impact, and ecosystem-aware usage coverage. The validated
+input loader remains responsible for schema, lineage, occurrence identity, and
+evidence-reference integrity.
+
+Validated Knowledge Manifest package occurrences are the decision cardinality
+source because they retain the Project Manifest occurrence plus canonical
+package identity. Version Analysis results are joined by the full occurrence
+key. A validated occurrence with no matching result is retained as
+`NOT_ANALYZED`; it is never silently dropped.
+
+## Canonical inputs and ownership
+
+Project Manifest owns the dependency occurrence and installed-version
+baseline. Version Analysis owns the evaluated target, analysis status,
+target-scoped evidence references, and structured findings. Repository Impact
+Evidence owns repository impact and coverage state. Ecosystem version adapters
+own version normalization and ordering.
+
+The decision policy owns only deterministic precedence. AI output, prose risk
+labels, package popularity, package names, repository names, file names, and a
+registry-latest candidate do not own the decision.
+
+## Recommendation-driver policy
+
+Target discovery, migration/risk evidence, and a recommendation driver are
+separate facts:
+
+- Registry metadata and `targetPolicy: registryLatest` establish only a
+  registry-discovered candidate.
+- Release notes, changelogs, breaking changes, deprecations, compatibility
+  notes, and migration guides describe the target or the cost/risk of a
+  possible migration. They do not recommend changing versions.
+- `targetPolicy: explicit` is the only current structured production driver.
+  It records that the caller selected and adapter-normalized a target version,
+  so the policy maps it to `USER_SELECTED_TARGET`.
+
+The current upstream schemas have no structured security advisory,
+end-of-support, deprecation-deadline, runtime-requirement, dependency-policy,
+or organization-policy driver. Free-form evidence and AI-authored prose must
+not synthesize one.
+
+Therefore, a newer registry-discovered target without another structured
+driver produces `INVESTIGATE` with
+`UPGRADE_AVAILABLE_NO_RECOMMENDATION_DRIVER`, even when target-scoped
+migration/risk evidence is sufficient. `PLAN_UPGRADE` requires an explicit
+target plus valid target-scoped evidence and all existing comparison,
+conflict, impact, and coverage checks.
+
+A referenced evidence claim that is invalid, stale, unavailable, or otherwise
+insufficient remains `INSUFFICIENT_EVIDENCE`; unverified prose never becomes a
+recommendation driver. A registry candidate with no migration evidence at all
+remains the bounded no-driver `INVESTIGATE` case.
+
+## Policy precedence
+
+For each validated Version Analysis occurrence:
+
+1. A non-analyzed Version Analysis status produces `NOT_ANALYZED`.
+2. A missing installed baseline produces `INSUFFICIENT_EVIDENCE`; an explicitly
+   non-registry declaration produces `INVESTIGATE`.
+3. A missing target produces `INSUFFICIENT_EVIDENCE`.
+4. An unavailable ecosystem adapter or incomparable version produces
+   `INVESTIGATE`.
+5. Equal installed and target versions produce `KEEP_CURRENT`.
+6. Installed newer than the evaluated target produces `KEEP_CURRENT` with a
+   limitation.
+7. Conflicted evidence produces `INVESTIGATE`; referenced invalid, stale,
+   unavailable, or non-target-scoped evidence produces
+   `INSUFFICIENT_EVIDENCE`.
+8. A newer registry-discovered target without a structured recommendation
+   driver produces `INVESTIGATE`, including when no migration evidence was
+   referenced.
+9. A structured driver with missing evidence produces
+   `INSUFFICIENT_EVIDENCE`.
+10. Partial or unavailable repository coverage for a repository-sensitive
+    finding produces `INVESTIGATE`.
+11. A future validated structured urgency signal may produce `UPGRADE_NOW`.
+   MP-R03 defines no production urgency input, so prose risk labels cannot
+   produce this decision.
+12. A newer caller-selected target with sufficient target-scoped evidence and
+    no blocker produces `PLAN_UPGRADE`.
+13. Remaining ambiguous states produce `INVESTIGATE`.
+
+Equal-version precedence intentionally comes before coverage uncertainty:
+coverage limitations remain visible but cannot turn a no-version-change fact
+into an upgrade recommendation.
+
+## Version comparison
+
+The policy calls the registered adapter for the occurrence ecosystem. Node uses
+SemVer and Python uses the current PEP 440 subset. An unsupported ecosystem,
+invalid version, URL/Git/local declaration, or adapter `unknown` result is never
+compared lexically and produces an investigation outcome.
+
+## Persistence and consumers
+
+The stage writes `.upgradelens/upgrade-decision.json` atomically. Its lineage
+contains portable paths and digests for all seven immutable inputs. Decisions
+are sorted by stable occurrence identity and include versions, comparison,
+evidence references, impact/coverage, reason codes, human-review state,
+limitations, and policy provenance.
+
+CLI and Markdown presentation display the persisted decision. Migration
+Checklist receives the persisted artifact and may only prepare AI action
+contexts for `PLAN_UPGRADE` or `UPGRADE_NOW`. `INVESTIGATE` is manual-review
+only; `KEEP_CURRENT`, `INSUFFICIENT_EVIDENCE`, and `NOT_ANALYZED` cannot create
+migration actions.
+
+## Genericity
+
+No rule depends on VinGrade, a package name, a framework name, a repository
+path, or a source filename. VinGrade is an acceptance repository only. The
+policy operates on schema-validated occurrence facts and registered ecosystem
+capabilities.