@thomasminh1995/depverdict 0.6.0-alpha.1

package/docs/openrouter-one-dependency-validation.md

@@ -0,0 +1,205 @@
+# OpenRouter One-Dependency Enriched Evidence Validation
+
+**IMPLEMENTED — NOT YET EXECUTED**
+
+## 1. Purpose
+
+This procedure validates one real dependency with its enriched release/changelog evidence through the existing OpenAI-compatible runtime and Version Analysis path. It is a bounded manual transport and integration check, not a model benchmark, qualification, or production certification.
+
+The intended path is:
+
+```text
+one real dependency
+→ enriched evidence
+→ exact OpenRouter model slug
+→ structured output
+→ JSON Schema/Ajv validation
+→ Trust Layer
+→ version-analysis.json
+```
+
+## 2. Prerequisites
+
+- An OpenRouter API key and sufficient credit/quota for the exact selected model.
+- A repository in which `discover` and `research` have already completed.
+- An enriched Knowledge Evidence Bundle produced by the current UpgradeLens research flow.
+- One exact OpenRouter model slug chosen by the maintainer.
+- A Node.js version supported by UpgradeLens.
+- The current UpgradeLens binary, or an existing local `npm link` installation.
+
+## 3. Local `.env`
+
+From the UpgradeLens checkout, create an ignored local file:
+
+```bash
+cp .env.example .env
+```
+
+Then replace the placeholders locally:
+
+```dotenv
+UPGRADELENS_AI_MODEL=<exact-model-slug>
+UPGRADELENS_AI_AUTHORIZATION=Bearer <real-key>
+```
+
+Do not send the key to Codex, chat, logs, or issue reports. Never commit `.env`.
+
+UpgradeLens does not load `.env` automatically and does not search parent directories for runtime configuration. Node `--env-file` should not be assumed to interpolate `${OPENROUTER_API_KEY}` inside `.env`. Put the complete local value directly in that ignored file:
+
+```dotenv
+UPGRADELENS_AI_AUTHORIZATION=Bearer <REAL_OPENROUTER_KEY>
+```
+
+## 4. Configurations Maintainer Must Add
+
+The manual run requires exactly these runtime settings:
+
+```text
+UPGRADELENS_AI_PROVIDER=openai-compatible
+UPGRADELENS_AI_ENDPOINT=https://openrouter.ai/api/v1/chat/completions
+UPGRADELENS_AI_MODEL=<exact-model-slug>
+UPGRADELENS_AI_AUTHORIZATION=Bearer <real-openrouter-key>
+UPGRADELENS_AI_TIMEOUT_MS=180000
+```
+
+- `UPGRADELENS_AI_PROVIDER` remains `openai-compatible`; OpenRouter is not hardcoded into the AI core.
+- `UPGRADELENS_AI_ENDPOINT` is the OpenRouter Chat Completions endpoint.
+- `UPGRADELENS_AI_MODEL` is one exact model slug selected by the maintainer. Do not use `openrouter/auto` or `openrouter/free`.
+- `UPGRADELENS_AI_AUTHORIZATION` is `Bearer` followed by the real local OpenRouter key.
+- `UPGRADELENS_AI_TIMEOUT_MS` is the bounded runtime deadline; `180000` is the suggested validation value.
+
+No `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, or `GOOGLE_API_KEY` is required by this procedure.
+
+## 5. Loading Environment
+
+### Option A — Node env file
+
+Use the local ignored `.env` without relying on any automatic application loader:
+
+```bash
+node --env-file=.env /path/to/UpgradeLens/bin/upgradelens.js \
+  analyze-version . \
+  --package pypi:langsmith
+```
+
+Replace `/path/to/UpgradeLens` with the maintainer's local checkout path.
+
+### Option B — Shell exports
+
+If the OpenRouter key is already present in a private shell variable, export the five UpgradeLens settings explicitly:
+
+```bash
+export UPGRADELENS_AI_PROVIDER="openai-compatible"
+export UPGRADELENS_AI_ENDPOINT="https://openrouter.ai/api/v1/chat/completions"
+export UPGRADELENS_AI_MODEL="<exact-model-slug>"
+export UPGRADELENS_AI_AUTHORIZATION="Bearer ${OPENROUTER_API_KEY}"
+export UPGRADELENS_AI_TIMEOUT_MS="180000"
+
+upgradelens analyze-version . --package pypi:langsmith
+```
+
+The placeholders above are documentation only; never paste a real key into a committed file or shared command transcript.
+
+## 6. Preparing Enriched Evidence
+
+The maintainer should prepare the target repository before loading the cloud runtime configuration:
+
+```bash
+upgradelens discover .
+upgradelens research .
+```
+
+Confirm that these artifacts exist without printing their full contents:
+
+```text
+.upgradelens/project-manifest.json
+.upgradelens/knowledge-manifest.json
+.upgradelens/knowledge-evidence-bundle.json
+```
+
+The `analyze-version` command reads these artifacts but does not modify them.
+
+## 7. Recommended First Dependency
+
+The recommended initial selector is:
+
+```text
+pypi:langsmith
+```
+
+KR-10 found an exact baseline, a target, nearby release notes, and real enriched context for this package. The package is not hardcoded in UpgradeLens; another exact canonical ID can be supplied with `--package`.
+
+The selector is exact and case-sensitive. Bare names, wildcard/regex selectors, multiple package values, and automatic package choice are not supported. If one package ID maps to multiple dependency occurrences, the command stops before creating the runtime so the run cannot exceed one dependency call.
+
+## 8. Manual Validation Command
+
+With the ignored `.env` populated locally:
+
+```bash
+node --env-file=.env /path/to/UpgradeLens/bin/upgradelens.js \
+  analyze-version . \
+  --package pypi:langsmith
+```
+
+When UpgradeLens is already linked, the equivalent command is:
+
+```bash
+upgradelens analyze-version . --package pypi:langsmith
+```
+
+## 9. Expected Checks
+
+After the maintainer runs the command, verify all of the following rather than assuming success:
+
+- Exactly one runtime call occurred.
+- The selected result has status `analyzed`.
+- The candidate passed structured JSON Schema/Ajv validation.
+- The Trust Layer passed.
+- Every evidence reference belongs to the enriched Evidence Bundle.
+- The output contains no invented URL, API, migration step, or evidence reference.
+- The risk assessment has evidence support.
+- The human-review decision follows the current policy.
+- `.upgradelens/version-analysis.json` is valid.
+- No retry or fallback occurred.
+
+These are post-run checks, not claims that the validation has already passed.
+
+## 10. Security
+
+- Do not log the key or include it in errors, artifacts, fixtures, documentation, or chat.
+- Do not store the Authorization header in `version-analysis.json` or another report.
+- Do not commit `.env`; only `.env.example` is intended for version control.
+- Do not persist the raw prompt, full evidence payload, or raw provider response in a report.
+- Do not use an automatic model router for this validation.
+- Enriched evidence is sent to a cloud service. The maintainer must explicitly accept this disclosure and use only repositories/evidence permitted to leave the local environment.
+
+## 11. Interpretation
+
+One successful request demonstrates only this combined path:
+
+```text
+OpenRouter transport
++ exact selected model
++ enriched evidence
++ structured-output/trust path
+```
+
+It does not prove that:
+
+- the model is `CERTIFIED`;
+- the upstream provider route is reproducible;
+- this is the best model;
+- the model is ready for MVP-04 or MVP-05;
+- benchmark quality gates pass.
+
+An exact model slug prevents model-level automatic selection, but OpenRouter may still route that model through multiple upstream providers. This setup does not add `provider.only`, `allow_fallbacks: false`, or other OpenRouter-specific request fields because the current adapter has no generic safe request-extra contract. Provider pinning and fallback control belong to a separate gateway-conformance task. This run is therefore not a reproducible locked-provider benchmark.
+
+## 12. Status
+
+```text
+Execution status: NOT RUN
+Qualification status: EXPERIMENTAL
+Production certification: NONE
+```
+
+Tests and live OpenRouter validation were intentionally deferred to the maintainer.

package/docs/oss-02-package-guard-hardening-architecture.md

@@ -0,0 +1,131 @@
+# OSS-02 Package Guard Hardening Architecture
+
+## Decision
+
+UpgradeLens treats the entries read from the actual gzip tarball produced by
+`npm pack --json` as the package authority. The guard remains a repository release
+check, not a consumer lifecycle hook or a general source-tree scanner.
+
+## 1. Current boundary
+
+The existing guard already invokes `npm pack --json`, reads the resulting `.tgz`,
+and validates tar entry paths. It does not rely only on a working-tree walk.
+However, its pure validation layer currently checks only capture exclusions and 20
+required paths. It does not reject copy/backup names, invalid or duplicate manifest
+paths, or packaged untracked implementation files.
+
+## 2. Manifest production and recursion safety
+
+`inspectNpmPackage` remains the manifest producer:
+
+1. create isolated temporary pack and npm-cache directories;
+2. run `npm pack --json --ignore-scripts`;
+3. read the actual tarball entries;
+4. correlate those entries with optional Git state;
+5. run the pure validator;
+6. delete only the task-owned temporary directory.
+
+`--ignore-scripts` makes manifest production independent of package lifecycle
+scripts. The current `package.json` has no `prepack`, `prepare`, `prepublishOnly`, or
+install lifecycle hook, and `check:package` is not invoked by npm lifecycle. Thus
+there is no `check:package → npm pack → prepack → check:package` recursion. Tests
+call the pure validator directly, while one isolated integration test exercises
+actual npm inclusion.
+
+## 3. Protected implementation areas
+
+Strict filename and optional untracked-file policy applies to actual packaged files
+under:
+
+- `package/bin/`: executable entry points;
+- `package/src/`: runtime implementation and public exports;
+- `package/schemas/`: public data contracts;
+- `package/eval/datasets/`: published evaluation cases;
+- `package/eval/migration-planning/`: published versioned evaluation datasets;
+- `package/eval/schemas/`: published evaluation contracts.
+
+`scripts/` and `test/` are repository-only under the current `files` allowlist, so
+they cannot be checked as package entries. Their accidental inclusion would first
+require an explicit package-boundary change. Documentation is still checked by the
+existing capture and general forbidden-entry rules, but is excluded from the
+copy-name grammar because legitimate historical names such as the TS-FIX-01
+duplicate-occurrence architecture document must remain valid.
+
+## 4. Suspicious filename grammar
+
+Within protected areas, a basename is suspicious when it has:
+
+- a whitespace-delimited numeric copy suffix immediately before its extension,
+  including multi-extension files: `runtime 2.js`, `schema 3.schema.json`;
+- a parenthesized numeric suffix: `runtime (2).js`;
+- a terminal copy label delimited by whitespace, hyphen, or underscore:
+  `runtime copy.js`, `runtime-copy.js`, `runtime_duplicate.js`;
+- a backup/editor suffix: `~`, `.bak`, `.orig`, `.save`, `.tmp`, `.swp`, `.swo`.
+
+The numeric rule requires a copy delimiter and terminal copy position. It therefore
+accepts `sha256.js`, `oauth2.js`, `v2-runtime.js`, `schema-v2.json`,
+`mp-r02-policy.js`, `python3.md`, and `fixture-2fa.json`.
+
+## 5. Portable path policy
+
+The pure validator first rejects absolute paths, drive-letter paths, NUL bytes,
+empty/dot segments, parent traversal, and paths outside the npm `package/` root.
+Backslashes are normalized to `/` only after the original path has passed the
+absolute/traversal checks. It then detects duplicate normalized entries before
+deduplication and sorts diagnostics by stable reason code and portable path.
+
+## 6. Git-state policy
+
+The release command asks Git for tracked entries and untracked non-ignored entries.
+In strict release mode, an actual packaged untracked regular file under a protected
+area fails with `UNEXPECTED_PACKAGED_UNTRACKED_IMPLEMENTATION_FILE`.
+
+Git absence or a source archive without `.git` is represented explicitly as
+`GIT_METADATA_UNAVAILABLE`; it does not fail package-content validation by itself.
+Suspicious filename, required-asset, forbidden-entry, invalid-path, and duplicate
+entry rules remain authoritative without Git. Git command errors other than
+repository absence are surfaced as operational errors, not silently treated as a
+clean tracked state. There is no generated-file allowlist because the current
+package has no repository-owned generated public implementation path.
+
+## 7. Diagnostics and exit contract
+
+The validator returns a frozen structured result with normalized entries, summary,
+Git state, and violations. Every violation has a stable `code` and relative portable
+`path`. Policy failures render:
+
+```text
+Package guard failed.
+
+REASON_CODE
+- relative/path
+```
+
+Reasons and paths are sorted, output is bounded, totals are retained in the
+structured result, file contents are never printed, and the script exits non-zero.
+Pass output reports package entry count, zero suspicious artifacts, and the single
+authoritative required-asset count.
+
+## 8. Isolated adversarial tests
+
+Pure unit tests use in-memory manifest entries. The npm-boundary integration test
+creates an isolated temporary package containing an untracked `src/runtime 2.js`,
+runs npm pack with lifecycle scripts disabled, proves npm includes the file, and
+passes those actual tar entries to the validator. Temporary fixtures and npm caches
+live outside the repository and are removed by the test. Mutation checks compare
+fixture bytes before and after validation.
+
+## 9. Manifest determinism layer
+
+The validator sorts normalized entries and diagnostics, detects duplicate normalized
+paths, and produces byte-identical structured/rendered results for reversed input.
+Release validation may repeat `npm pack` and compare actual entry inventories.
+Neither a file count nor a tarball digest is a permanent business invariant.
+
+## 10. Explicit scope boundary
+
+OSS-02 preserves the existing required assets, capture exclusion, `.env`, local
+artifact, credential/authorization-file, qualification-input/record, bin, and export
+target checks. It adds structural package hygiene only. It does not inspect arbitrary
+file content, detect malware, scan secrets generally, alter product behavior, pin a
+manifest snapshot, delete findings, or run on consumer installation.

package/docs/oss-04-public-ci-package-metadata-architecture.md

@@ -0,0 +1,142 @@
+# OSS-04 Public CI and Package Metadata Architecture
+
+## Status and scope
+
+This decision defines read-only public continuous integration and npm/GitHub
+metadata for UpgradeLens `0.5.0`. It does not change runtime, schema, evaluation,
+upgrade-decision, or Migration Checklist policy. It also does not publish a package,
+create a release, or mutate repository state.
+
+## Workflow triggers
+
+CI runs for every `pull_request`, pushes to `main` and `develop`, and manual
+`workflow_dispatch` requests. Both long-lived branches exist locally and on the
+canonical remote. Pull requests are the primary review gate; direct pushes are
+covered so the protected branch state is independently validated. There is no
+schedule because OSS-04 has no time-based check or dependency-update policy.
+
+`pull_request_target` is prohibited. Fork code therefore runs only in the ordinary
+pull-request context with a read-only token and no repository secrets.
+
+## Supported Node matrix
+
+The package declares `node >=20`, so CI does not narrow the engine contract. The
+mandatory compatibility matrix is:
+
+- Node 20: the declared minimum, retained as a compatibility floor even though its
+  upstream support window ended on 2026-04-30;
+- Node 22: the newer maintenance LTS line, supported through 2027-04-30;
+- Node 24: the current active LTS line, supported through 2028-04-30.
+
+The dates come from the official
+[Node.js release schedule](https://github.com/nodejs/Release/blob/main/schedule.json).
+Node 26 is Current until October 2026, not LTS at this decision date, so it is not a
+mandatory preview gate. The Node 24 package-smoke job is the primary release-line
+check. Node 20 remains visible rather than being silently removed; changing the
+minimum engine is a separate compatibility and release-policy decision.
+
+## Action supply-chain policy
+
+Only GitHub-maintained `actions/checkout` and `actions/setup-node` are used. Each is
+pinned to the full commit currently referenced by its supported `v6` release line,
+with the major version retained in a comment:
+
+- `actions/checkout`: `df4cb1c069e1874edd31b4311f1884172cec0e10`;
+- `actions/setup-node`: `249970729cb0ef3589644e2896645e5dc5ba9c38`.
+
+Full SHA pinning makes a reviewed workflow revision immutable. The trade-off is
+that action security and runtime updates require an explicit pull request instead
+of arriving through a moving major tag. No third-party action is needed.
+
+Checkout disables credential persistence because no later step performs an
+authenticated Git operation. Setup Node uses the committed lockfile as the explicit
+npm cache dependency.
+
+## Permissions, fork safety, and provider isolation
+
+Workflow permissions are exactly `contents: read`. There is no write, package,
+identity-token, security-event, issue, or pull-request permission. Jobs do not read
+`secrets`, call a write API, interpolate pull-request-controlled fields into shell
+commands, upload artifacts, or retain credentials.
+
+The test job sets `CI=true` and shadows supported UpgradeLens provider variables
+with empty values. This prevents a runner or repository environment from supplying
+an inherited endpoint, model, authorization value, timeout, or debug mode. Tests
+continue to inject their own deterministic fake environments where required.
+Neither CI job needs OpenAI, OpenRouter, Anthropic, Ollama, a local qualification
+record, private repository access, or any real-provider credential.
+
+## Install, test, and package-smoke stages
+
+The matrix job performs:
+
+1. read-only checkout;
+2. Node setup with npm cache;
+3. deterministic `npm ci`;
+4. the canonical `npm test`;
+5. `npm run check:package`, which creates and validates an actual tarball with
+   lifecycle scripts disabled.
+
+No lint, typecheck, or build command is invented because the repository defines
+none. Local matrix replay found that Node 20's default test-runner concurrency can
+starve one real keep-alive lifecycle test past its unchanged three-second natural
+exit budget. The same test passes alone, and the complete Node 20 suite passes when
+the canonical npm test script receives `--test-concurrency=2`. CI applies that
+bounded runner concurrency only on Node 20; it does not skip the test, increase its
+timeout, or alter product behavior. Node 22 and Node 24 use plain `npm test`.
+
+The Node 24 package-smoke job performs:
+
+1. the same checkout, setup, and deterministic install;
+2. `npm pack --dry-run --json --ignore-scripts`;
+3. a repository-owned Node script that creates an actual tarball in an isolated
+   cache/output directory;
+4. actual-manifest package-guard validation and tar extraction;
+5. a clean, lifecycle-disabled install from that tarball;
+6. installed CLI `--version` and `--help`;
+7. ESM package import and the existing 438-public-export contract;
+8. cleanup of all task-owned temporary state in `finally`.
+
+The package smoke does not call the product analysis workflow, a provider, a
+publisher, or a deployment target. No tarball is uploaded as an Actions artifact;
+logs contain only bounded verification summaries, so artifact retention is zero.
+
+## Lifecycle and side-effect boundary
+
+`package.json` has no `prepack`, `prepare`, `prepublishOnly`, `preinstall`,
+`install`, or `postinstall` hook. The package guard calls
+`npm pack --json --ignore-scripts`, so `check:package` cannot recurse through an npm
+lifecycle. Consumer installation in the smoke also uses `--ignore-scripts`.
+
+The workflow contains no `npm publish`, Git tag, release creation, commit, push,
+deployment, PR comment, or generated-file writeback. It cannot publish because it
+has neither a publishing command nor write/OIDC credentials.
+
+## Concurrency, cancellation, and timeout
+
+The concurrency group uses the workflow name and stable Git ref. A newer commit on
+the same branch or pull-request ref cancels the older run. Different branches and
+pull requests remain independent.
+
+Each job has a 20-minute timeout. This allows deterministic install and the
+canonical suite reasonable runner variance while bounding dependency, listener, or
+subprocess hangs. The package smoke has the same finite ceiling.
+
+## Package metadata ownership and lockfile policy
+
+`package.json` owns the public npm description, repository, homepage, issue URL,
+keywords, version, engine, executable, export, license, and package-content
+boundary. OSS-04 updates only stale positioning and missing public discovery
+metadata.
+
+`package-lock.json` mirrors dependency-tree and root-package fields that npm records.
+Description, homepage, bugs, and keywords are not forced into the lockfile. A
+lockfile-only npm consistency check must produce no dependency, resolved, integrity,
+or version drift.
+
+## Hosted acceptance
+
+Static validation and local command replay can prove the workflow contract but
+cannot prove a hosted run. After a maintainer commits and pushes the change, every
+Node matrix job and the Node 24 package-smoke job must pass at the recorded commit
+before branch protection or the next qualification gate treats CI as hosted proof.

package/docs/package-content-policy.md

@@ -0,0 +1,98 @@
+# npm package content policy
+
+DepVerdict treats the tarball produced by `npm pack` as the authoritative
+public package boundary. Repository evidence can remain tracked without
+becoming npm consumer content.
+
+## Included content
+
+`package.json.files` explicitly includes the executable, public runtime source,
+schemas, evaluation datasets, user-facing documentation, license, and README.
+The package guard additionally requires critical assets such as:
+
+- `bin/depverdict.js`, the bounded `bin/upgradelens.js` compatibility wrapper,
+  and the public runtime entry points;
+- the current architecture overview, identity-migration decision,
+  UpgradeLens-to-DepVerdict guide, preview release draft, and migration report;
+- Migration Planning qualification and extractive-candidate schemas;
+- Migration Planning v1 and v2 golden datasets;
+- CLI progress, qualification-resolution, and package-policy documentation.
+
+The guard reads actual gzip tar entries from a fresh
+`npm pack --json --ignore-scripts`; it does not infer package contents from the
+working tree. Lifecycle scripts are disabled for manifest production so a future
+`prepack` hook cannot recurse into the guard.
+
+## Repository-only CLI capture evidence
+
+CLI transcripts, screenshots, environment summaries, and manifests use the
+direct-child convention:
+
+```text
+docs/*-cli-captures/
+```
+
+They are retained in Git for release review but excluded by the path-specific
+`package.json.files` rule:
+
+```text
+!docs/*-cli-captures
+```
+
+The rule intentionally does not exclude all documentation. User-facing
+Markdown remains package-visible.
+
+Capture helper programs under `scripts/` or `tools/` are also repository-only.
+Those directories are outside the package allowlist. The guard recognizes
+known release capture trees, the future direct-child naming convention, and
+capture-helper path patterns as forbidden tarball entries.
+
+## Validation
+
+Run:
+
+```text
+npm run check:package
+```
+
+The check fails when an actual tarball:
+
+- contains a capture, environment, credential-file, local-machine, or private
+  qualification artifact;
+- omits any required public asset;
+- contains an invalid, traversing, absolute, or duplicate normalized entry;
+- contains numeric-copy, parenthesized-copy, copy/duplicate-label, or backup
+  filenames in packaged runtime, executable, schema, or evaluation areas; or
+- contains a protected implementation file that is not tracked by Git during a
+  strict release check.
+
+Git correlation is supplemental. In a source archive without Git metadata, the
+structural tarball rules still run and Git absence does not fail by itself. The
+filename grammar is copy-suffix-specific: legitimate names such as `sha256.js`,
+`oauth2.js`, `v2-runtime.js`, and `schema-v2.json` remain valid. Documentation is
+outside strict copy-name matching so intentional historical document identities are
+preserved.
+
+`npm run check` runs the repository tests and this package check. Focused guard
+tests also verify stable path normalization, the future capture convention,
+missing-required-asset failures, invalid paths, deterministic diagnostics,
+tracked/untracked policy, valid numeric-name false positives, and an isolated npm
+tarball that contains an untracked numeric-copy artifact.
+
+The guard reports findings and exits non-zero; it never deletes or rewrites them.
+Investigate ownership and content before cleanup.
+
+Package validation for a release should inspect the real tar entries, perform
+an isolated install of the produced tarball, and smoke-test the packaged
+version, help, public import, and default analysis command. Generated tarballs,
+installation directories, caches, and raw provider data are never committed.
+
+## Privacy and compatibility
+
+Capture evidence must be sanitized before staging: no credentials,
+authorization material, private endpoints, raw provider payloads, hidden
+reasoning, or machine-specific absolute paths. Exclusion from npm is a package
+size and privacy boundary, not a substitute for repository privacy review.
+
+This policy changes only package composition. It does not alter qualification,
+progress, impact, evidence, migration-planning, or provider semantics.