@thomasminh1995/depverdict 0.6.0-alpha.1

package/docs/mp-r04-evidence-bounded-migration-handoff-architecture.md

@@ -0,0 +1,116 @@
+# MP-R04 Evidence-Bounded Migration Handoff Architecture
+
+## Decision
+
+Upgrade the existing `.upgradelens/migration-checklist.json` artifact instead
+of creating a separate Migration Handoff artifact.
+
+The checklist already owns the evidence-bounded action projection, exact
+evidence references, deterministic candidate locations, limitations, stable
+item IDs, atomic writer, qualification boundary, and console/Markdown
+presentation. A second artifact would either duplicate those facts or require
+Coding Agents to join two handoff documents. Schema version 2 adds the missing
+deterministic handoff projection to each dependency occurrence while retaining
+the extractive action contract.
+
+The artifact remains experimental and human-reviewed. It is not a migration
+execution plan, approval record, patch, command runner, or proof that migration
+work is complete.
+
+## Discovery answers
+
+1. The v1 checklist already contains the Version Analysis result and dependency
+   occurrence identities, installed/current/target version facts, target
+   policy, selected evidence refs, breaking findings, exact-excerpt-derived
+   review instructions, positive Impact Evidence locations, limitations, stable
+   IDs, ordering, lineage, and mandatory item review state.
+2. AI owns only selection of an exact allowlisted evidence excerpt. The legacy
+   wire value `AI_AUTHORED` identifies that selected item, but deterministic
+   runtime owns the final prefix, item ID, evidence refs, location-free action
+   shape, ordering, status, and review requirement.
+3. The existing artifact is the correct product boundary. It needs an
+   incompatible schema upgrade because v1 cannot represent authoritative
+   decision identity, recommendation driver, handoff outcome, verification
+   state, recovery state, or structured coverage alongside every occurrence.
+4. No new artifact is introduced. The missing values are represented in v2
+   without copying raw upstream artifacts.
+5. Target origin is the persisted Upgrade Decision
+   `versions.targetPolicy`. The current only production recommendation driver
+   is `USER_SELECTED_TARGET`, present as the `PLAN_UPGRADE` primary reason and
+   reason code under policy 1.1.0.
+6. Action evidence must be official/publisher, available, fresh,
+   non-conflicted, one of the existing migration-capable kinds, referenced by
+   the finding, and scoped to the exact selected target version.
+7. Affected areas come only from Repository Impact Evidence positive
+   `matchedSymbols[].usages[]`, preserving its evidence ID, finding ID, symbol,
+   portable file path, and coverage state.
+8. Project Manifest v2 does not contain verification scripts. MP-R04 therefore
+   reads only supported package manifests already identified by Project
+   Manifest. For Node `package.json`, it projects safe script names into
+   package-manager commands and records the source path plus exact-byte digest.
+   It does not parse script bodies, README prose, arbitrary CI shell, or execute
+   commands. Other ecosystems and missing/unsafe script metadata produce
+   `VERIFICATION_COMMAND_UNAVAILABLE`.
+9. The extractive prompt forbids identity, paths, commands, URLs, ordering,
+   prerequisites, rollback, effort, approval, code, and reasoning. Candidate
+   schema permits only evidence ref plus exact excerpt. Trust validation
+   requires exact substring containment and rejects the whole candidate when
+   any item has a prohibited capability.
+10. Provider abstention, invalid output, trust rejection, timeout, and runtime
+    failure already produce deterministic manual-review records without
+    publishing partial candidate actions. V2 maps abstention to
+    `NO_GROUNDED_ACTION` and generation/rejection/runtime failures to
+    `ACTION_GENERATION_FAILED`.
+
+## V2 ownership
+
+Deterministic runtime owns:
+
+- dependency, project, manifest, Version Analysis, and Upgrade Decision IDs;
+- installed and target versions, target origin, and recommendation driver;
+- decision-to-handoff mapping and human-review state;
+- evidence references and official evidence metadata projection;
+- verified affected areas and coverage state;
+- safe project-derived verification commands and their source digests;
+- precondition codes, recovery availability, stable IDs, and ordering.
+
+AI may only select an exact action excerpt from the bounded official evidence
+allowlist. It cannot own or modify any other handoff field.
+
+## Decision mapping
+
+| Upgrade Decision | Handoff status | Provider eligible |
+| --- | --- | --- |
+| `KEEP_CURRENT` | `NO_VERSION_CHANGE_REQUIRED` | No |
+| `PLAN_UPGRADE` / `UPGRADE_NOW`, accepted actions | `ACTIONABLE_WITH_REVIEW` | Yes |
+| `PLAN_UPGRADE` / `UPGRADE_NOW`, abstention/no instruction | `NO_GROUNDED_ACTION` | Yes, at most one call per eligible finding |
+| `PLAN_UPGRADE` / `UPGRADE_NOW`, rejected/failed generation | `ACTION_GENERATION_FAILED` | Yes, package-local failure |
+| `INVESTIGATE` | `INVESTIGATION_REQUIRED` | No |
+| `INSUFFICIENT_EVIDENCE` | `INSUFFICIENT_EVIDENCE` | No |
+| `NOT_ANALYZED` | `NOT_ANALYZED` | No |
+
+Every persisted Upgrade Decision occurrence must produce exactly one dependency
+handoff record. Missing or legacy Upgrade Decision artifacts are never treated
+as actionable.
+
+## Verification and recovery
+
+Verification commands are bounded deterministic projections, not executed
+results. Supported Node package scripts are selected by exact generic
+verification roles (`test`, `build`, `lint`, `typecheck`, and `check`) and
+invoked through the declared supported package manager. The record includes
+the portable working directory, source manifest path, script name, and
+source-byte digest. No command is inferred when any required structured fact is
+missing.
+
+MP-R04 does not synthesize recovery. Until an exact structured upstream
+recovery instruction exists, records contain `RECOVERY_PLAN_NOT_PROVIDED`.
+
+## Compatibility
+
+Schema v1 checklists are non-actionable legacy artifacts and must be
+regenerated. The v2 loader requires exact Upgrade Decision lineage and rejects
+tampering or occurrence mismatches before generation. The public
+`analyze-version` CLI still chooses `registryLatest`; positive handoff
+acceptance uses the supported programmatic explicit-target boundary. Default
+Migration Checklist enablement and provider qualification rules are unchanged.

package/docs/mp-r05-product-completion-and-decision-first-cli-architecture.md

@@ -0,0 +1,162 @@
+# MP-R05 Product Completion and Decision-First CLI Architecture
+
+## Decision
+
+Keep `upgradelens analyze` as the primary product workflow and add two small,
+orthogonal public controls:
+
+- repeatable `--target <selector>` for structured caller-selected targets; and
+- `--fail-on-incomplete` for CI that requires every trustworthy outcome to be
+  free of review or data gaps.
+
+Do not add a configuration framework, a new persisted domain artifact, source
+editing, command execution, or provider fallback. Product completion is a
+deterministic presentation/exit projection over persisted Version Analysis,
+Upgrade Decision, and optional Migration Checklist v2 artifacts.
+
+## Discovery record
+
+1. The public CLI has no explicit-target input. `analyze` always invokes
+   Version Analysis with `{ target: { policy: "registryLatest" } }`;
+   `analyze-version --package` selects one canonical package but does not select
+   a version.
+2. The supported programmatic shape is
+   `{ target: { policy: "explicit", version: "<version>" } }`. The ecosystem
+   adapter normalizes the value before a context is built.
+3. An occurrence cannot be selected safely by name alone. Resolution needs the
+   canonical package ID and, when ambiguous, `projectId`, manifest, and
+   dependency type. Declared version remains part of upstream occurrence
+   identity but is not required from the user because the validated Project
+   Manifest supplies it.
+4. Scoped npm packages are already canonicalized as
+   `npm:@scope/package`. The target parser must not split on `@`.
+5. Python packages are normalized by PEP 503-style name normalization and
+   represented as `pypi:normalized-name`. Versions are validated by the Python
+   ecosystem adapter, not npm SemVer.
+6. The same canonical package in multiple projects/workspaces produces
+   multiple occurrences. An unqualified selector must fail with
+   `TARGET_SELECTOR_AMBIGUOUS` and list stable candidate selectors; it must
+   never choose the first occurrence or fan out implicitly.
+7. The final console summary is built by `renderConsoleSummary` after the
+   Markdown Report stage. Upgrade Decision and Migration Checklist renderers
+   are appended after impact counts.
+8. Current `COMPLETE`/`INCOMPLETE` values describe impact/checklist coverage,
+   not whether the product workflow has a trustworthy terminal result. They
+   remain compatible diagnostic fields and are not reused as product
+   completion.
+9. Fatal stage failures return 1, controlled cancellation returns 130, and
+   `discover --fail-on-warning` returns 2. Package-local provider/output
+   failures are persisted as failed Version Analysis results but a successful
+   `analyze` pipeline currently returns 0.
+10. Existing tests assert artifact retention and exit 0 for some direct
+    `analyze-version` package-local failures. MP-R05 intentionally changes the
+    product `analyze` exit contract; the stage command remains an artifact
+    producer and reports its failed-result count without pretending that its
+    result is a completed product analysis.
+
+## Public target selector
+
+Use a repeatable, key/value selector:
+
+```text
+--target package=<canonical-package-id>,target=<version>
+--target package=<id>,target=<version>,project=<project-id>,manifest=<path>,type=<dependency-type>
+```
+
+Examples:
+
+```text
+--target 'package=npm:framework-a,target=2.0.0'
+--target 'package=npm:@scope/package,target=3.1.0'
+--target 'package=pypi:library-b,target=3.0.0'
+--target 'package=npm:framework-a,target=2.0.0,project=node:apps/web,manifest=apps/web/package.json,type=dependency'
+```
+
+The grammar is deliberately not `name@version`, so scoped npm names require no
+special-case split. Required keys are `package` and `target`; optional keys are
+`project`, `manifest`, and `type`. Unknown/duplicate keys, non-portable
+manifests, duplicate occurrence selection, unsupported adapters, and invalid
+versions fail before provider construction.
+
+Resolution is performed against validated `resolveDependencyAnalysisInputs`
+facts. Zero matches produce `TARGET_SELECTOR_NOT_FOUND`; multiple matches
+produce `TARGET_SELECTOR_AMBIGUOUS` with stable candidate guidance; invalid or
+unsupported versions produce `TARGET_VERSION_INVALID`. Repeated selectors are
+resolved as a set independently of CLI input order.
+
+Selected occurrences receive an explicit target. Every unselected occurrence
+continues to use `registryLatest`, so the default and mixed workflows never
+convert registry facts into user intent.
+
+## Product completion projection
+
+The projection has closed outcomes:
+
+```text
+COMPLETED
+COMPLETED_WITH_REVIEW
+PARTIAL
+INSUFFICIENT_DATA
+FAILED
+CANCELLED
+```
+
+Successful pipeline precedence is:
+
+1. Any retained Version Analysis provider/output/runtime failure, or
+   `ACTION_GENERATION_FAILED` handoff: `PARTIAL`.
+2. Any selected explicit target with `INSUFFICIENT_EVIDENCE`, or more than half
+   of occurrences unable to answer because of insufficient/missing analysis:
+   `INSUFFICIENT_DATA`.
+3. Any valid `PLAN_UPGRADE`, `UPGRADE_NOW`, `INVESTIGATE`, review-required
+   decision, or coverage limitation: `COMPLETED_WITH_REVIEW`.
+4. Otherwise: `COMPLETED`.
+
+Fatal stage/config/schema/lineage errors are reported as `FAILED` and
+controlled cancellation as `CANCELLED`; they do not publish a successful
+completion projection.
+
+`INVESTIGATE`, zero actions, and `KEEP_CURRENT` are not failures. Provider
+failure precedence cannot be hidden by successful decision counts.
+
+## Exit compatibility
+
+Default `analyze` exits:
+
+- 0 for `COMPLETED`, `COMPLETED_WITH_REVIEW`, and `INSUFFICIENT_DATA`;
+- 2 for retained `PARTIAL`;
+- 1 for fatal `FAILED`; and
+- 130 for `CANCELLED`.
+
+With `--fail-on-incomplete`, `COMPLETED_WITH_REVIEW` and
+`INSUFFICIENT_DATA` also exit 2. The flag never fails solely because there are
+zero migration actions or because all decisions are `KEEP_CURRENT`.
+
+Exit 2 is reused as the existing non-fatal/strict public convention. This is an
+intentional behavior change for `analyze` workflows that previously exited 0
+despite retained provider/output failures.
+
+## Presentation hierarchy
+
+Console and Markdown lead with:
+
+1. product completion and plain-language next step;
+2. decision counts and occurrence table;
+3. handoff counts/actions and review boundary;
+4. failed occurrences, coverage/evidence/provider limitations, and recovery;
+5. artifact paths; and
+6. legacy impact counts and internal diagnostics.
+
+`analyze --stdout` emits only a machine-readable completion summary on stdout;
+progress remains on stderr. Qualification IDs, evidence IDs, lineage digests,
+and raw reason codes remain in artifacts or diagnostic sections rather than
+the default decision table.
+
+## Experimental boundary
+
+Migration Checklist v2 remains opt-in and experimental. The extractive
+candidate/prompt identity is unchanged by the deterministic v2 envelope, but
+MP-R05 does not claim new real-provider qualification or default enablement.
+Public explicit targets can produce Upgrade Decisions without the experimental
+stage; evidence-bounded migration actions still require the existing
+experimental flag and qualification boundary.

package/docs/mvp-05-deterministic-context-runtime.md

@@ -0,0 +1,127 @@
+# MVP-05 Deterministic Context Runtime
+
+## Scope
+
+MP-02 prepares trusted, immutable input for the later migration-checklist generator. It performs no AI call, provider/network access, source scan, artifact write, CLI integration, or migration instruction generation.
+
+The public orchestration API is `prepareMigrationChecklistContexts(input, options)`. `input` may be a repository root or an explicit `sources` object. The lower-level APIs are `loadMigrationChecklistInputs` and `buildMigrationTaskContexts`. The MP-03 consumer of this output is documented in [`mvp-05-provider-neutral-generator.md`](./mvp-05-provider-neutral-generator.md).
+
+## Seven input artifacts and lineage
+
+The loader reads the raw bytes of:
+
+1. Project Manifest;
+2. Knowledge Manifest;
+3. Knowledge Evidence Bundle;
+4. Version Analysis;
+5. Usage Index;
+6. Repository Impact;
+7. Repository Impact Evidence.
+
+Every public artifact is validated with its existing schema and invariant validator. Digests are SHA-256 over the exact bytes that were read; JSON reserialization is never used as lineage proof.
+
+The validated graph is:
+
+```text
+Project Manifest ──> Knowledge Manifest ──> Knowledge Evidence Bundle
+       │                    │                         │
+       └────────────────────┴─────────────────────────┴──> Version Analysis
+       │                                                   │
+       └───────────────────────────────────────────────────┴──> Usage Index
+       │                                                        │
+       └────────────────────────────────────────────────────────┴──> Repository Impact
+       │                                                             │
+       └─────────────────────────────────────────────────────────────┴──> Repository Impact Evidence
+```
+
+Only lineage fields that exist in the current schemas are compared. A mismatch is fatal and reports the consumer, upstream artifact, field, declared value, and actual exact-byte value with code `LINEAGE_MISMATCH`.
+
+## Cross-artifact trust checks
+
+Before any context is built, MP-02 verifies:
+
+- exact Project and Knowledge dependency occurrence identity;
+- package-level Usage identity (`projectId + packageId`) against one or more exact Version Analysis occurrences;
+- package/ecosystem/registry identity across Project, Knowledge, and Version Analysis;
+- unique finding identity within each analysis result;
+- Version finding evidence refs against Version evidence metadata, bundle content, Knowledge source metadata, and package provenance;
+- Usage dependency identity against Version Analysis;
+- Repository Impact result/finding identity and exact matcher output against Usage symbols/files;
+- Repository Impact Evidence identity, reason, symbol, and file records against Repository Impact and Usage.
+
+Unknown, cross-package, cross-project, or ambiguous references are fatal. Corruption is not converted into a package-local fallback.
+
+### Duplicate declaration reconciliation
+
+Usage coverage is package-level: one Usage Index dependency records the symbols and files observed for a package in a project. Version Analysis is occurrence-level: repeated declarations of that package retain separate results, including separate analyzed, skipped, or failed states.
+
+MP-02 therefore permits one package-level Usage identity to map to multiple valid Version Analysis occurrences. It validates every occurrence against its exact Project and Knowledge declaration facts, then processes every Version result independently. It does not merge declarations, choose a preferred result, upgrade a skipped result from a sibling analyzed result, or infer that duplicate declarations represent duplicate source-code usage.
+
+Repository Impact and Repository Impact Evidence remain isolated by `analysisResultId`, then by exact finding and evidence identity. Positive locations are copied only from the matching `analysisResultId + findingId` record and retain their `impactEvidenceId + symbol + file` identity. A location or finding from one occurrence is never broadcast to another occurrence merely because both share a package.
+
+An exact duplicate occurrence that cannot be distinguished by the existing canonical declaration facts remains fatal. Duplicate result IDs, duplicate findings within one result, unknown or cross-project/package identities, inconsistent downstream identities, and non-exact locations also remain fatal. These states are corruption, not manual-review fallbacks.
+
+## Eligibility precedence
+
+Action-generation eligibility is separate from location eligibility.
+
+Action precedence is:
+
+1. non-analyzed Version result → `NOT_ANALYZED`;
+2. stale/conflicted selected evidence → `INVALID_OR_CONFLICTED_EVIDENCE`;
+3. missing target, over-bound summary, or no bounded target-scoped official/publisher evidence → `NO_GROUNDED_ACTION`;
+4. otherwise → `ELIGIBLE`.
+
+An `ELIGIBLE` context is permission for MP-03 to inspect bounded evidence. It is not proof that the evidence contains an entailed migration instruction. Evidence kinds are used only as a deterministic allowlist and priority; `migrationGuide` is preferred, but its label is not semantic proof.
+
+Location eligibility is:
+
+- `POSITIVE_USAGE_MATCH` when an exact validated Impact Evidence symbol/file exists;
+- `NO_POSITIVE_USAGE_MATCH` for a narrowly supported single Node.js-project JS/TS run with no positive match;
+- `UNSUPPORTED_USAGE_COVERAGE` when project-level coverage cannot be proven;
+- `NOT_ANALYZED` when Version Analysis did not complete.
+
+Unsupported coverage never blocks a dependency-level action context when action evidence is otherwise eligible. It leaves locations empty and records an explicit limitation. No negative state is converted into “unused” or “safe.”
+
+## Context boundary and evidence bounds
+
+Each eligible context contains only:
+
+- dependency occurrence and declared/current/target version facts;
+- Version Analysis result and breaking-finding identity;
+- bounded finding summary and applies-to versions;
+- selected Knowledge evidence records and an exact evidence allowlist;
+- URLs copied only from validated Knowledge source metadata;
+- optional positive `impactEvidenceId + symbol + file` locations;
+- action and location eligibility;
+- upstream and mandatory human-review reasons;
+- deterministic limitations.
+
+It excludes repository source, unrelated dependencies/evidence, provider configuration, arbitrary URLs, commands, code/patches, prerequisites, ordering, rollback, effort, numeric confidence, and safety claims.
+
+Default bounds are six evidence records, 24,000 total evidence characters, and a 2,000-character finding summary. Evidence is selected by stable kind priority and ID, deduplicated by content digest, and never truncated. Evidence must be official/publisher-controlled, available, fresh, action-relevant by structured kind, and explicitly scoped to the target release. Bounds are configurable positive integers for deterministic tests and future policy revisions.
+
+## Fallback records
+
+`fallbackRecords` use the normalized dependency/finding shape accepted by the MP-01 builder:
+
+- skipped/failed results preserve upstream reasons and contain no generated finding/action;
+- no grounded action produces only a deterministic `MANUAL_REVIEW_REQUIRED` record;
+- stale/conflicted evidence fails closed to deterministic manual review;
+- unsupported usage is recorded as a location limitation and does not replace otherwise eligible dependency-level action context.
+
+Fallbacks retain only useful official evidence refs, use existing stable `analysisResultId` and finding IDs, and are sorted deterministically.
+
+## Fatal errors versus expected ineligibility
+
+Missing/malformed/schema-invalid artifacts, lineage mismatch, unknown reference, ambiguous identity, and inconsistent impact location are fatal input errors. Expected absence of analysis, action evidence, or supported usage coverage produces a normalized fallback or limitation.
+
+Returned loaded artifacts, contexts, fallbacks, lineage, and summary are deep-cloned and deeply frozen. The runtime holds no mutable reference to parsed upstream values.
+
+## Deferred work
+
+- MP-03 implements prompt construction, structured AI output, exact excerpt and conservative trust checks, and generated migration-instruction drafts.
+- MP-04 implements task-specific evaluation, adversarial cases, and provider qualification; see [`mvp-05-migration-evaluation-and-qualification.md`](./mvp-05-migration-evaluation-and-qualification.md).
+- MP-05 implements final checklist assembly/writer, experimental CLI orchestration, and presentation renderers; see [`mvp-05-migration-checklist-orchestration.md`](./mvp-05-migration-checklist-orchestration.md).
+
+The current Usage Index exposes analyzer coverage globally rather than per project. MP-02 therefore treats multi-project, non-JS/TS, warning-bearing, or otherwise unprovable negative coverage conservatively. A future analyzer-coverage schema can improve location eligibility without changing action eligibility.

package/docs/mvp-05-migration-checklist-contract.md

@@ -0,0 +1,166 @@
+# MVP-05 Migration Checklist Contract
+
+## Purpose and boundary
+
+`.upgradelens/migration-checklist.json` is a versioned, provider-neutral, human-review artifact. It records evidence-grounded review actions and deterministic fallback records. It is not an autonomous migration plan, safety certificate, patch, command runner, or migration execution log.
+
+The current schema is [`migration-checklist.schema.json`](../schemas/migration-checklist.schema.json), version `2.0.0`. Version 2 adds the MP-R04 deterministic Migration Handoff projection while preserving the extractive action boundary. Version 1 artifacts are legacy, non-actionable, and must be regenerated. MP-01 provides a pure builder, schema validator, invariant validator, stable item IDs, deterministic serialization, and grounding/eligibility policy. MP-02 exact-byte loading and upstream joins are documented in [`mvp-05-deterministic-context-runtime.md`](./mvp-05-deterministic-context-runtime.md).
+
+`COMPLETE` never means “migration complete” or “safe to upgrade.” It only means all dependency checklist records in the normalized valid input contain structurally grounded actionable records.
+
+## Artifact identity and lineage
+
+The artifact contains `schemaVersion`, `generatedAt`, `generator`, repository identity, overall `status`, summary, dependency records, and limitations. `generatedAt` is mandatory input to `buildMigrationChecklist`; the builder does not read the clock.
+
+`input` records the schema version, portable artifact path, and exact-byte digest for all eight required artifacts:
+
+- Project Manifest, including repository identity;
+- Knowledge Manifest, including `researchId`;
+- Knowledge Evidence Bundle;
+- Version Analysis;
+- Usage Index;
+- Repository Impact;
+- Repository Impact Evidence.
+- Upgrade Decision.
+
+Every dependency occurrence also contains a deterministic handoff projection:
+
+- authoritative decision ID, decision status, target origin, reason codes, and
+  recommendation driver;
+- one of `NO_VERSION_CHANGE_REQUIRED`, `ACTIONABLE_WITH_REVIEW`,
+  `INVESTIGATION_REQUIRED`, `INSUFFICIENT_EVIDENCE`, `NOT_ANALYZED`,
+  `ACTION_GENERATION_FAILED`, or `NO_GROUNDED_ACTION`;
+- verified affected areas and coverage state;
+- bounded official-evidence metadata (stable evidence/source identity, kind,
+  authority, trust, content digest, locator, and release scope; never raw
+  evidence text or provider-owned provenance);
+- project-derived verification commands or
+  `VERIFICATION_COMMAND_UNAVAILABLE`;
+- structured preconditions, explicit recovery unavailability, human-review
+  state, investigation questions, evidence gaps, and next step.
+
+Only `PLAN_UPGRADE` and `UPGRADE_NOW` may contain AI-selected migration
+instructions. Registry-discovered targets, keep decisions, evidence gaps, and
+not-analyzed occurrences never enter action generation.
+
+MP-01 validates the lineage object shape and repository identity consistency. MP-02 calculates these digests from exact input bytes and verifies cross-artifact lineage before calling the builder. MP-03 generation and trust validation are documented in [`mvp-05-provider-neutral-generator.md`](./mvp-05-provider-neutral-generator.md). MP-04 task-specific gates are documented in [`mvp-05-migration-evaluation-and-qualification.md`](./mvp-05-migration-evaluation-and-qualification.md).
+
+## Status taxonomy
+
+| Status | Meaning |
+| --- | --- |
+| `COMPLETE` | Every normalized dependency record is `COMPLETE` and contains grounded actionable items. This is checklist completeness only. |
+| `INCOMPLETE` | At least one record needs manual review, has unsupported usage coverage, conflicted/invalid evidence, or is mixed with a non-complete record. |
+| `NO_GROUNDED_ACTION` | Analyzed input contains no structurally grounded action. It does not imply no migration work is required. |
+| `NOT_ANALYZED` | All represented dependency results were skipped or failed. No migration action is present. |
+
+Dependency and overall statuses are derived by the builder, not supplied as trusted input. A mixed artifact is fail-closed as `INCOMPLETE`.
+
+## Eligibility taxonomy
+
+Eligibility is not boolean. Each normalized context has a constrained `status` and `reasonCode`:
+
+| Reason code | Eligibility status | Checklist status | Policy |
+| --- | --- | --- | --- |
+| `ELIGIBLE` | `ELIGIBLE` | `COMPLETE` | May contain deterministic items or AI-selected, deterministic-rendered migration guidance. |
+| `NOT_ANALYZED` | `INELIGIBLE` | `NOT_ANALYZED` | Skipped/failed Version Analysis; no generated finding/action. |
+| `NO_GROUNDED_ACTION` | `INELIGIBLE` | `NO_GROUNDED_ACTION` | Only deterministic `MANUAL_REVIEW_REQUIRED` fallback is permitted for a represented finding. |
+| `UNSUPPORTED_USAGE_COVERAGE` | `INELIGIBLE` | `INCOMPLETE` | Absence from the Usage Index is not interpreted as dependency non-use or safety. |
+| `INVALID_OR_CONFLICTED_EVIDENCE` | `INELIGIBLE` | `INCOMPLETE` | No AI-authored action; deterministic manual review only. |
+| `MANUAL_REVIEW_REQUIRED` | `REVIEW_REQUIRED` | `INCOMPLETE` | No AI-authored action; deterministic manual review only. |
+
+An analyzed dependency with multiple finding states is aggregated conservatively. Any mixed complete/no-action state is `INCOMPLETE`; invalid/conflicted evidence takes precedence, followed by unsupported usage coverage, then manual review.
+
+## Checklist item taxonomy and basis
+
+Item `kind` is limited to:
+
+- `REVIEW_MIGRATION_INSTRUCTION` — review an instruction grounded in selected evidence;
+- `REVIEW_CANDIDATE_USAGE` — review a deterministic positive symbol/file candidate;
+- `VERIFY_OFFICIAL_REQUIREMENT` — verify an evidence-linked official requirement;
+- `MANUAL_REVIEW_REQUIRED` — non-actionable deterministic fallback.
+
+Item `basis` is either:
+
+- `DETERMINISTIC`; or
+- `AI_AUTHORED`.
+
+All items have `requiresHumanReview: true`. The artifact has no approved/completed state. The legacy `AI_AUTHORED` wire value means AI-selected, deterministic-rendered guidance in extractive v2. Such an item is valid only when it:
+
+- belongs to an `ELIGIBLE` finding;
+- has kind `REVIEW_MIGRATION_INSTRUCTION`;
+- references the enclosing `findingId`;
+- carries at least one evidence ref declared by that finding and its dependency selected-evidence allowlist;
+- has no repository location;
+- requires human review.
+
+All actionable item kinds require evidence. Ineligible contexts may contain deterministic manual-review fallbacks only.
+
+## Grounding and cross-reference rules
+
+Each dependency record preserves the upstream Version Analysis `analysisResultId`, dependency occurrence identity, analysis status, selected evidence allowlist, and version facts. Each finding preserves its upstream ID, summary, evidence refs, and declared positive impact locations.
+
+MP-01 enforces:
+
+- unique Version Analysis result IDs, finding IDs per result, and checklist item IDs across the artifact;
+- stable item IDs derived from result, finding, item basis/kind/text, sorted evidence refs, sorted locations, and review state;
+- stable ordering of dependencies, findings, evidence refs, items, locations, and limitations;
+- finding evidence refs are in the dependency selected-evidence allowlist;
+- item evidence refs are in both the finding and selected-evidence allowlists;
+- item `findingId` equals the enclosing finding;
+- each candidate location exactly matches a declared positive triple of `impactEvidenceId`, `symbol`, and `file`;
+- repository locations are allowed only on deterministic `REVIEW_CANDIDATE_USAGE` items;
+- AI-authored and manual fallback invariants;
+- status, eligibility, version semantics, repository identity, and summary counts;
+- schema rejection of additional properties.
+
+Citation existence is structural grounding, not semantic entailment. MP-01 cannot prove that an instruction is actually supported by the cited text.
+
+## Candidate location semantics
+
+A location contains only:
+
+- `impactEvidenceId`;
+- `symbol`;
+- `file`.
+
+It is a candidate review location copied from positive Repository Impact Evidence. It is not a proven call site or semantic impact. The contract intentionally has no line, column, snippet, call count, or semantic-impact field. AI-authored items cannot own locations.
+
+## Version uncertainty
+
+The contract preserves Version Analysis version facts without recommendation semantics:
+
+- `currentVersion` and `currentVersionSource` may be null;
+- `exactBaseline` requires both values;
+- `declaredConstraint` and `unsupportedBaseline` require both values to remain null;
+- unknown baselines keep an unknown delta;
+- `targetPolicy: registryLatest` identifies a registry fact, not a recommended target;
+- no field can mark a target as recommended.
+
+The contract does not infer a migration path from a version range or unknown installed version.
+
+## Explicit exclusions
+
+The schema has no fields for dependency ordering, inferred prerequisites, generated code, patches, auto-fix, shell/package-manager commands, rollback, effort, numeric confidence, migration execution status, safety certification, or transitive dependency completeness. Additional properties are rejected.
+
+`instruction` is bounded text. MP-01 applies a small deterministic guard against obvious URLs, code/patch blocks, shell/package-manager commands, and safety claims. This is intentionally not NLP moderation and is not semantic proof. Later trust validation must still reject prohibited capabilities expressed indirectly.
+
+## Deferred checks
+
+### MP-02 — deterministic loader and context
+
+Implemented as a separate read-only runtime. It validates the seven legacy exact-byte artifacts plus persisted authoritative Upgrade Decision, the full lineage/reference graph, bounded official evidence, independent action/location eligibility, immutable MP-03 contexts, and MP-01-compatible deterministic fallbacks.
+
+### MP-03 — generator and trust validation
+
+Implemented as a provider-neutral, package-local runtime. New application runs use the versioned extractive v2 schema: the model selects an exact allowlisted evidence span and deterministic code renders the human-review text. Conservative prohibited-capability guards, whole-candidate fail-closed rejection, and safe abstention/failure fallbacks remain. Exact excerpts establish provenance, not repository applicability. Historical free-form v1 remains for evaluation reproducibility. See [`GR-04-Versioned-Production-Extractive-Contract.md`](./GR-04-Versioned-Production-Extractive-Contract.md).
+
+### MP-04 — evaluation and qualification
+
+Implemented as a separate offline-first evaluation runtime. It measures raw candidate, trust containment, and published behavior with a strict multi-ecosystem dataset, versioned metrics and critical gates, transparent scorecard, and provider/model/task-specific qualification. The fake result is `QUALIFIED_WITH_LIMITATIONS`; no real provider has been qualified.
+
+### MP-05 — presentation and orchestration
+
+Implemented as an experimental opt-in application stage. It assembles MP-02/MP-03 output strictly through this MP-01 builder, enforces the MP-04 qualification identity, atomically writes the artifact, and renders a shared presentation-only view model. See [`mvp-05-migration-checklist-orchestration.md`](./mvp-05-migration-checklist-orchestration.md). Real-provider generation is not enabled by default.
+
+No MP-01 module calls AI, network, filesystem loaders, source scanners, writers, CLI commands, or orchestration stages.