Reference¶

Public API¶

ossiq exposes a stable library interface for programmatic use. Install without extras for the core scanner (pip install ossiq); install with [cli] to also get the terminal CLI (pip install 'ossiq[cli]').

from ossiq import scan, ScanResult, ScanRecord, Settings, CVE, Package, VersionsDifference, AbstractProjectSources

scan(sources)¶

def scan(sources: AbstractProjectSources, on_step: Callable[[str], None] | None = None) -> ScanResult

Runs a full dependency health scan against the project described by sources. Fetches package metadata, CVEs, and version history from the appropriate registry; runs the SAT solver to produce update recommendations; and returns a ScanResult. Must be called inside the sources context manager. on_step is an optional callback invoked with a short label at each scan phase (useful for driving a progress indicator).

from ossiq import scan, Settings
from ossiq.sources.project_sources import ProjectSources

settings = Settings.load()
sources = ProjectSources(settings, project_path=".")
with sources:
    result = scan(sources)

ScanResult¶

Aggregated output of a single scan run. Returned by scan().

ScanRecord¶

Per-package analysis record. Each entry in the ScanResult lists above is one ScanRecord.

Settings¶

Pydantic model holding runtime configuration. Load from the config file and environment variables with Settings.load(), or construct directly.

All fields can be set via environment variables prefixed with OSSIQ_ (e.g. OSSIQ_GITHUB_TOKEN).

CVE¶

A single vulnerability record attached to a ScanRecord.

Package¶

Metadata about a package as returned by its registry.

VersionsDifference¶

Semantic drift classification between two versions.

AbstractProjectSources¶

Base class for the scan context, exported from ossiq.sources.core. Use ossiq.sources.project_sources.ProjectSources (the concrete implementation) to construct a scan context for a real project on disk.

from ossiq.sources.project_sources import ProjectSources

sources = ProjectSources(
    settings=settings,
    project_path="/path/to/project",
    production=True,          # production deps only
    ignore_packages=("pytest",),
)
with sources:
    result = scan(sources)

Other optional keyword arguments mirror the CLI’s own flags: allow_prerelease, allow_prerelease_packages, security_only, rewrite_versions, and narrow_package_registry (force a specific registry instead of auto-detecting).

Data Model¶

The ossiq domain model is located in the ossiq.domain module. It defines the core entities used for analysis.

Project¶

A software project being analyzed. Each Project contains a name and lists of its direct production and development dependencies.

For full details, see ossiq/domain/project.py.

Package¶

A dependency of a Project. A Package is defined by its name and contains a list of all its available versions.

For full details, see ossiq/domain/package.py.

Version Models¶

The version-related models capture details from different sources and are aggregated into a single Version object.

The primary Version object aggregates package_data (from a package registry) and repository_data (from a source code repository). Other data classes like Commit and User provide granular detail about the source code history.

For a complete definition of all version-related data classes, see ossiq/domain/version.py.

Constraint Provenance¶

Most packages in a scan report were installed the normal way: a manifest declared them, the resolver picked a version, and the lockfile recorded it. The ConstraintSource field on a Dependency tracks when that was not the case — when an extra mechanism outside the normal dependency graph was controlling the version.

The five constraint types¶

Priority ordering (highest wins when multiple rules apply): OVERRIDE > ADDITIVE > PINNED > NARROWED > DECLARED.

Why you need to watch this¶

When a normal dependency becomes vulnerable, the fix is straightforward: update it, the resolver picks a patched version, done. Constraints and overrides break that flow. They impose version rules from outside the normal dependency graph. A constraint can pin a transitive package to a range that still contains a vulnerable version — and nothing in the lock file makes this obvious. You can stare at the lockfile, see h11==0.13.0, and have no idea that a rule somewhere else is preventing you from resolving 0.14.0.

This is the failure mode described in Against Upper-Bound Version Constraints in Libraries: once a constraint caps a package below a patched version, you cannot fix it unilaterally. The person who wrote the constraint has to release a patch first. At scale, with many transitive constraints scattered across pyproject.toml entries and nested overrides, this creates invisible debt that surfaces only when a CVE forces a full audit.

The key insight: a constraint doesn’t just describe what version is installed — it describes who has the power to change it. An OVERRIDE means someone decided this package’s own version declarations don’t matter. An ADDITIVE constraint means a separate authority is narrowing the resolution space. Both are worth tracking separately from ordinary declared dependencies.

OSS IQ surfaces constraint_info so you can see which packages are under a constraint, what kind of constraint, and which file introduced it — before a CVE forces you to find out.

Constraint provenance by package manager¶

pip classic — -c constraint files¶

pip’s -c flag in requirements.txt references a separate constraints file. Packages listed there are not installed as direct dependencies — they only narrow the version range for anything the resolver would pull in anyway.

# requirements.txt
-c constraints.txt
requests==2.31.0

When OSS IQ encounters a -c directive, it reads the referenced file and tags every package that appears in both the resolved dependencies and the constraints file with ConstraintType.ADDITIVE. The source_file field is set to the requirements.txt that introduced the -c directive. Nested -c includes are followed recursively; circular includes are detected and skipped.

A package tagged ADDITIVE in pip classic means: something outside your direct dependency list is controlling its allowed version range. If a CVE hits that package, check whether the constraint file is the thing blocking the update.

uv — constraint-dependencies and override-dependencies¶

uv exposes two settings under [tool.uv] in pyproject.toml:

• constraint-dependencies — PEP 508 specifiers that narrow allowed versions without adding direct dependencies. These map to ConstraintType.ADDITIVE.

• override-dependencies — PEP 508 specifiers that force a version regardless of what the dependency graph declares. These map to ConstraintType.OVERRIDE.

# pyproject.toml
[tool.uv]
constraint-dependencies = ["h11>=0.14.0"]
override-dependencies = ["urllib3==1.26.18"]

The distinction matters: a constraint-dependencies entry cooperates with the normal resolver — it adds a lower bound, an upper bound, or an exclusion. An override-dependencies entry overrules it. If a package under override-dependencies is later found vulnerable in the forced version, no amount of updating its parents will help — the override itself is the thing to remove.

Both lists are read from pyproject.toml at scan time. Matched packages in the resolved dependency tree are tagged accordingly, with source_file set to pyproject.toml.

npm — overrides¶

npm’s overrides field in package.json forces a specific version (or range) for a matching package anywhere in the dependency tree, regardless of what each package’s own dependencies declaration says.

// package.json
{
  "overrides": {
    "semver": "^7.5.2",
    "lodash": {
      "dot-prop": "^6.0.1"
    }
  }
}

OSS IQ reads the overrides block from package-lock.json (where npm records the resolved overrides) and tags matching packages with ConstraintType.OVERRIDE, adding an overridden category to their categories list.

For scoped overrides — where a version is forced only when a package appears as a dependency of a specific parent — the scope_path field on ConstraintSource records the ancestor chain. In the example above, dot-prop would carry scope_path: ["lodash"], meaning the override applies only when dot-prop is pulled in by lodash. A flat override like semver has scope_path: null.

The scope_path matters for remediation: a scoped override targeting dot-prop inside lodash does not affect dot-prop when pulled in by other packages. Removing it may leave dot-prop under lodash unprotected, or free it to resolve a patched version — depending on which direction the version was being forced.

Overrides are a marker, not a version source. OSS IQ only reads the keys of the overrides block to decide which packages to tag OVERRIDE; the forced version string is never parsed or fed into the solver. The installed version already reflects the override’s effect, because npm applied it before writing the lockfile — OSS IQ just labels the result.

Matching is by exact tree name. An override entry is matched against packages by the literal name npm registered them under in the lockfile — not the package’s canonical registry name. This matters for package aliases: an override keyed "chalk": "4.1.2" tags a plain chalk dependency, but does nothing to "chalk-legacy": "npm:chalk@4.1.2", because that alias is registered as chalk-legacy, not chalk. To override an aliased package, key the overrides entry with the alias name.

npm — package aliases¶

npm lets a package.json entry install one real package under a different name, using "npm:<real-name>@<range>" as the version specifier:

// package.json
{
  "dependencies": {
    "chalk-legacy": "npm:chalk@4.1.2",
    "chalk": ">4.1.2 <=5.3.0"
  }
}

This is how a project runs two versions of the same package side by side — commonly during a major-version migration, or when one dependency needs an old API another consumer has already moved past.

Each alias is tracked as its own entry, with its own recommendation. ScanRecord.package_name holds the canonical (real) name — chalk for both rows above — and ScanRecord.dependency_name holds the name actually used in package.json — chalk-legacy and chalk. The two occurrences never share a recommendation: chalk-legacy is held at 4.1.2 because its own alias range pins it there, while plain chalk is free to move up to 5.3.0, even though the solver evaluates candidate versions for the underlying chalk package once and both entries draw from the same candidate set.

That per-alias fitting also applies to the solver’s cooldown: when the shared candidate the solver would otherwise recommend falls outside one alias’s own range, OSS IQ re-fits that alias to the newest version that satisfies its range and (like the solver itself) still prefers one older than the cooldown period when one exists. If no published version satisfies an alias’s own range, that alias is reported with no recommendation rather than inheriting a sibling’s.

Console output does not display the alias name. The status table’s Package column and the info header both print package_name — the canonical name — so chalk-legacy and chalk both read as chalk in a scan report; only the Installed / Recommended columns (and dependency_path for transitive occurrences) tell the rows apart. ossiq-cli info <alias-name> matches on the alias name directly and opens that one occurrence; ossiq-cli info <real-name> matches every occurrence — aliased or not — and lists each as a separate Occurrence n of m block.

plan / apply cannot rewrite an alias’s inner range. The update solver still computes a per-alias recommendation as described above, but writing it back to package.json is unsupported for npm:pkg@range specifiers — the alias entry is left untouched by apply. Use the recommendation as a manual target and edit the alias range yourself.

System Behavior¶

Dependency Resolution¶

• Dependency Graph: The system operates on a flat list of dependencies resolved from a lockfile (e.g., package-lock.json).

• Transitive Dependencies: Transitive dependency resolution is not performed. The tool relies on the dependency resolution of the target project’s native package manager (e.g., npm, pip, uv).

Update Solver (plan / apply)¶

• Single pass. The solver recommends versions against the current lockfile. Applying a plan re-resolves the tree, which can surface further recommendations; re-run plan until it reports no updates (most projects converge in one or two passes).

• Cooldown. Candidate versions younger than --cooldown-period days (default 7) receive a heavy soft-penalty in the solver; recommendations that are still younger than the cooldown after solving are withheld into the plan’s Held for cooldown section and never applied.

• CVE bypass. When the installed version of a package carries a CVE, its recommendation is exempt from the cooldown hold. CVE-affected candidate versions themselves are hard-forbidden.

• New transitive dependencies. Packages entering the tree for the first time are resolved by the native package manager at apply time, outside the cooldown. The plan projects their version and age and flags entries younger than the cooldown with ⚠. Under --cutoff-date, projections exclude versions published after the cutoff for deterministic time-travel runs.

• Forced versions (--override pkg==version). Bypass the solver and the cooldown for one package. Persistence per ecosystem:

Forced packages are reported with `ConstraintType.OVERRIDE` on subsequent scans, so they remain
visible until the override is removed.

Data Provenance¶

Package metadata is sourced from ecosystem-specific repositories (e.g., npm registry, PyPI). This is handled by a set of adapters in the ossiq.adapters module (e.g., ossiq.adapters.api_npm).

Analysis Output¶

A single analysis run produces a ProjectMetrics object.

Class: ossiq.service.project.ScanResult

Description: Contains an analysis of each dependency, including version lags, time lags, and associated vulnerabilities.

Data Sources¶

OSS IQ aggregates data from the following public sources:

Outputs¶

OSS IQ produces three categories of analysis — metrics, security, and supply chain exposure — delivered across four output formats.

Metrics¶

Each dependency produces a PackageMetrics record with the following measurements:

Metrics Operationalization¶

time_lag_days and releases_lag are deterministic numbers. Teams use them to define thresholds that match their risk tolerance and enforce them automatically in CI.

A typical starting point:

Use the JSON export to evaluate thresholds in a CI step:

# Fail if any production package is more than 365 days behind
MAX_LAG_DAYS=365
jq --argjson max "$MAX_LAG_DAYS" \
  '[.production_packages[] | select(.time_lag_days != null and .time_lag_days > $max)] | length' \
  ossiq-report.json

Start with a permissive threshold to baseline your project, then tighten it incrementally as tech debt is resolved. This avoids blocking CI on day one while still creating measurable improvement targets.

For a complete GitHub Actions setup with CVE gating and outdated-package blocking, see the Version Lag and CVE Quality Gate tutorial.

Security¶

Each PackageMetrics record contains a cve array. Each entry includes:

Transitive CVEs. When a transitive dependency has CVEs, OSS IQ surfaces them in the transitive_packages array. The dependency_path field on each entry traces the ancestor chain from the project root to the affected package.

Supply Chain Exposure¶

OSS IQ surfaces constraint risk through the constraint_type field on each PackageMetrics record. Five tiers are recognized, ordered from highest to lowest concern:

For reports produced by OSS IQ before v1.2 (which lack a constraint_type field), the Explorer and export consumers fall back to heuristics on the version_constraint string: a bare semver (e.g. 1.2.3) is treated as PINNED; a specifier containing < is treated as NARROWED.

Output Formats¶

Console¶

The status command prints a project-wide report; the info command prints a deep-dive for a single package. Every section, column, and status marker of both reports is documented in Console Reports.

HTML Report¶

The ossiq-cli html command produces a self-contained HTML file embedding an interactive Vue.js single-page application. The report includes the full dependency tables and the Transitive Dependency Explorer: an interactive D3 tree that visualises the transitive_packages dependency graph.

The Explorer supports:

• Color-coded nodes by risk type — six priority tiers: CVE (red), OVERRIDE (orange dash-dot), ADDITIVE (green dotted), PINNED (orange solid-thick), NARROWED (yellow dashed), DECLARED (blue)

• Fuzzy search and toggle filters (CVE, Narrowed, Override/Pinned)

• Click to focus a node and highlight all ancestor and descendant paths

• Alt+Click to collapse or expand a subtree

• Dashed curved links between nodes sharing an identical package_name@installed_version

• Zoom and pan

For full Explorer interaction details, see EXPLORER.md.

JSON Export¶

The export --output-format json command writes a single .json file conforming to export schema v1.5 by default. The root object contains:

Since v1.5, every PackageMetrics entry (production, development, and transitive) also carries the health-score fields: gate (a {status, reason} object — pass, quarantine, or block), fitness (0–100), expected_exposure, impact, p_vuln, p_supplychain, and exposure_window_days. Any of the numeric fields may be null when the underlying signal could not be computed — this means “not computable,” never “no risk.” See Reading the output for what each field means.

CSV Export¶

The export --output-format csv command writes a folder named export_{project_name}/ containing three files and a Frictionless Data descriptor:

Since v1.5, packages.csv carries eight additional columns for the health-score fields: gate_status, gate_reason, fitness, expected_exposure, p_vuln, p_supplychain, impact, and exposure_window_days. None are required — a package where a value could not be computed leaves the cell empty.

Console Reports¶

This section describes the terminal output of ossiq-cli status (project-wide report) and ossiq-cli info (single-package report): what each part shows, what each column and status marker means, and what to do when a marker signals a problem.

status — project report¶

ossiq-cli status [PROJECT_PATH]

The report has up to six parts, printed in this order. Parts with nothing to show are omitted.

1. Header — project name, registry (npm or pypi), path, and counts: production packages, development packages, and transitive packages with an update recommendation.

2. Dependency table — one row per direct dependency, grouped into Production and Development sections.

3. Transitive Recommendations — transitive packages the solver recommends updating.

4. New transitive dependencies — packages that would enter the tree if the recommended updates were applied.

5. Peer Constraint Status — peer dependency requirements and whether the installed versions satisfy them (npm projects only).

6. Constraint Widening Opportunities — for library projects, dependency ranges that could safely be widened.

Dependency table¶

Lifecycle markers on the Installed column:

A non-passing Gate verdict adds a badge next to the package name in the Package column, plus an indented sub-row underneath naming the reason:

A row with a recommendation can carry indented sub-rows describing what applying that recommendation would do to the rest of the dependency tree:

Transitive Recommendations¶

Transitive packages — packages your direct dependencies pull in — for which the solver recommends a different version, most often because the installed version carries a CVE or is far behind. With --security, the list narrows to packages with CVEs only. To turn these recommendations into an executable update plan, run ossiq-cli plan (see Update Solver).

New transitive dependencies¶

Packages that are not in the tree today but would be pulled in by the recommended updates. Their versions are resolved by the native package manager at apply time, outside the solver’s cooldown hold, so fresh entries are flagged rather than withheld: a ⚠ before the package name means the projected version is younger than the cooldown period and deserves a look before you apply (see Cooldown as Supply-Chain Quarantine for why).

Peer Constraint Status¶

npm packages can declare peerDependencies: versions of other packages they expect to find installed next to them but do not install themselves (the classic example is a plugin declaring which framework versions it works with). npm enforces these at install time, but overrides, --legacy-peer-deps, and --force installs can leave the tree in a state npm never checked. OSS IQ re-validates every peer requirement against the lockfile on every scan. PyPI has no peer dependency mechanism, so this table only appears for npm projects.

What ✗ violation means. Two packages you ship disagree about a third. The requirer was built and tested against the declared peer range; running it against a version outside that range can fail at runtime — missing exports, changed APIs — even though installation succeeded. Typical causes: an overrides entry forcing a version out of range, an install with --legacy-peer-deps or --force, or one package updated past what its peers allow.

Recovery paths, from most to least preferred:

1. Update the requirer. A newer release of the Required By package may accept the installed version. ossiq-cli info <requirer> shows whether one exists and what constrains it.

2. Move the violated package into the range. Upgrade or downgrade it to a version inside the peer constraint — after checking that nothing else in the tree needs the version you are moving away from.

3. Remove or adjust the override when one is the cause. See Constraint Provenance for how overrides are tracked.

4. Accept it knowingly. If you have verified the pair works together, you can leave it — the row keeps appearing on every scan as a standing reminder.

Constraint Widening Opportunities¶

Shown for library projects only: dependency ranges in your manifest whose upper bound excludes versions that already exist and resolve cleanly.

When an update is blocked by a transitive constraint¶

Sometimes you cannot move a direct dependency forward even though a newer version exists. A direct dependency is one node in a graph: each of its versions declares its own requirements on transitive packages, and other parents in your tree constrain those same packages. The solver recommends a version only when the whole subtree still resolves.

A concrete case: your project depends on A and B. A 2.0 requires C >= 3, but the latest B still requires C < 3. No version of C satisfies both, so A cannot reach 2.0. The report shows A with a newer Latest, a Recommended that stays behind (or none), and a ↳ ⚠ C: … sub-row naming the collision. ✗ no actionable update found means every candidate version of A hits such a collision. [NO RESOLUTION] with ↳ no version satisfies: … is the harder variant: the constraints already contradict each other in the current tree, before any update.

Your options, roughly in order:

1. Wait for upstream. The owner of the blocking constraint (here B) has to publish a release that widens its range — you cannot fix their constraint unilaterally. This is the failure mode described in Constraint Provenance; ossiq-cli info <blocking package> shows who declares the constraint.

2. Update or replace the other parent. A newer version of B may already accept C >= 3; if B is abandoned, replacing it removes the constraint entirely.

3. Force the version: ossiq-cli apply --override pkg==version bypasses the solver for one package. You take on the compatibility risk the constraint was protecting against; the override persists in your manifest and is reported as OVERRIDE on every subsequent scan until removed (see Update Solver).

4. Stay put deliberately. The current version keeps resolving. The report keeps showing the lag, so the debt stays visible instead of silent.

info — package report¶

ossiq-cli info PACKAGE_NAME [PROJECT_PATH]

A deep-dive into one package. When the package is installed in the project, the report has the sections below, in order; empty sections are omitted. When it is not installed, the report switches to prospective mode.

Header. Package name and installed version; role tags DIRECT and/or TRANSITIVE (both, when the package appears in both roles); a lifecycle marker ([UNPUBLISHED], [YANKED], [DEPRECATED], [pre] — same meanings as in the status table); license; registry URL.

Warnings. A panel of package health findings: ✗ marks critical findings (these block ossiq-cli add unless --force is passed), ! marks notices. Examples: a package with a single published version (typosquatting risk), a single maintainer (bus-factor risk).

Health Metrics. Registry-level signals: downloads over the last month, number of published versions, maintainer count, age of the latest version, age of the recommended version (when it differs from the latest), and cooldown remaining — days until the latest release is old enough to clear the cooldown period.

For an installed package, this block also shows the channel decomposition behind its Gate and Fitness values:

Any of these can render —: it means the underlying signal could not be computed, never that the package carries no risk. See Reading the output for the full explanation of Gate vs. Expected Exposure vs. Fitness.

Occurrences. A package can appear in the tree more than once — for example as a direct dependency and, at a different version, as a transitive one. Each occurrence gets its own block of the five sections below, labelled Occurrence n of m.

Drift Status. Status (same values as the status table), installed version, latest version, time lag (red past 180 days), and how many releases behind the installed version is.

Dependency Tree. The ancestor path from the project root down to this package (← you are here). For a direct dependency the path is just root → package; for a transitive one it names every intermediate package — useful for seeing which direct dependency is responsible for pulling this package in.

Policy Compliance. How the installed version relates to the rules that produced it:

Recommendation Rationale. Why the solver picked the recommended version — and, just as important, why it rejected the others:

• Eliminated (hard constraints) — versions that can never be chosen: outside a parent’s range, affected by a CVE, yanked, or pre-release without --allow-prerelease.

• Penalised (soft constraints) — versions that remain eligible but are scored down, e.g. younger than the cooldown period.

• The closing ✓ line states the selection: the latest eligible version, or the best stable candidate when the latest was eliminated or penalised.

If the version you expected is not the recommendation, this section names the exact rule that removed it.

Peer Requirements. Every peer constraint other packages place on this one, with the same markers as the status report’s Peer Constraint Status table: ✓ satisfied, ✓ … via override, ✗ violated (the installed version is shown in red next to the violated range). The recovery paths are the same too.

Security Advisories. Known vulnerabilities in the installed version of this package: severity, advisory ID, source database, and summary — or ✓ No known vulnerabilities.

Transitive CVEs. Vulnerabilities in packages downstream of this one — exposure you carry because this package pulls the affected ones in. Grouped per affected package@version, worst severity first. Updating this package may or may not resolve them; run ossiq-cli info <affected package> to see what constrains each one.

Licenses. Listed only when the package’s occurrences carry more than one SPDX identifier; a single unambiguous license is already shown in the header.

Prospective mode¶

When the package is not installed in the project, info evaluates it as a candidate instead: the header carries a PROSPECTIVE tag and the registry description, followed by health metrics, the recommendation rationale, and security advisories. This is the same pre-installation check that ossiq-cli add runs before installing.

Agent format¶

Both commands accept --format agent, which replaces the human report with a compact JSON verdict (ok / warn / block) for AI coding agents and scripts. See AI Agent Integration.

Install Skills¶

ossiq-cli install skills [TOOL] [--github-token TOKEN] [--dev PATH]

Installs the OSS IQ skill and a local MCP server so AI coding agents check dependency health before they add or update a package. For the task-oriented walkthrough, see AI Agent Integration.

What the command writes¶

All changes are made under your home directory; the command never touches the current project.

The MCP entry registers a local stdio server — the tool launches ossiq-cli mcp as a subprocess on your machine. No remote service is involved, and nothing is sent anywhere beyond the registry and GitHub API calls a normal scan makes.

The command is idempotent — safe to re-run at any time (for example after changing the token or switching development mode on or off):

• mcp.json is merged: only the ossiq entry under mcpServers is replaced; every other server entry is preserved.

• The Copilot instructions block is delimited by <!-- ossiq-skill:start --> / <!-- ossiq-skill:end --> markers. On re-run the block between the markers is replaced; the rest of the file — including your own instructions — is untouched.

GitHub token handling¶

OSS IQ uses the token only to raise the GitHub API rate limit from 60 to 5 000 requests per hour; no scopes or permissions are needed. See GitHub Personal Access Token for how to create a read-only one.

The token is resolved in this order:

1. The --github-token / -T option.

2. An interactive prompt. Leaving it blank skips token setup entirely — everything else still installs, and you can re-run the command later to add a token.

When a token is provided, it is written to two places, in plain text:

Because both files store the token unencrypted, prefer a fine-grained token restricted to public repositories with no additional permissions. To rotate or remove a token, re-run install skills with the new value, or edit the two files directly.

Development mode (--dev)¶

When you are working on ossiq-cli itself, --dev <path> points every installed integration at your local checkout instead of the PyPI release:

ossiq-cli install skills claude --dev ~/Projects/ossiq/ossiq-cli

Two substitutions are made:

• MCP server — registered as uv run --directory <path> ossiq-cli mcp, so the server always runs your current working tree.

• SKILL.md — every uvx --from ossiq ossiq-cli invocation in the skill text is rewritten to uvx --from <path> --no-cache ossiq-cli. The --no-cache flag makes uvx rebuild from source on each call, so the agent picks up your edits without a reinstall.

To switch back to the released package, re-run the command without --dev.

Versioning & Stability Guarantees¶

OSS IQ makes four commitments to users who depend on its output in CI pipelines, scripts, or downstream tooling.

Export Schema Stability¶

Each export schema version is identified by schema_version in the metadata block (e.g. "1.4"). The export --schema-version flag pins output to a specific version.

Within a schema version:

• Existing fields are never renamed or removed.

• New optional fields may be added — existing consumers are unaffected.

When a schema version is deprecated, the previous version remains fully supported for at least one major release cycle. Deprecation is announced in the changelog before the version is removed.

CLI Interface Stability¶

Command names, flag names, and exit codes are considered stable interfaces. Changes follow the same deprecation policy as schema versions: the old form continues to work with a deprecation warning before it is removed.

Deterministic Analysis¶

Given the same lockfile and the same version of OSS IQ, a scan always produces the same output. This makes OSS IQ safe to run as a blocking CI gate and suitable for diffing results between runs.

Metric Deprecation¶

When a field or metric is deprecated, it continues to appear in exports with its original semantics until the next major schema version. Removal is always accompanied by a migration note describing the replacement field or approach.