@adlc/model-ratchet

Scheduled re-prosecution of hot paths — ADLC C12.

Every frontier model release is a free re-audit of the existing codebase: new models find what old ones missed. model-ratchet identifies the most valuable files to re-prosecute (high churn × high criticality), then either prints a prosecution plan or drives your review command over them, appending verified findings to the shared .adlc/findings ledger.

Run on every model release (or monthly) to ratchet codebase quality monotonically upward for the cost of a scheduled job.

When run from any subdirectory of a git repository, candidate files, churn metrics, and the findings ledger resolve relative to the repository root. Relative file paths are normalized to forward-slash separators across platforms, ensuring consistent matching between churn metrics, import graph analysis, and candidate files on Windows.

ADLC Phase

C12 / D1–D3 maintenance ratchet. Pairs with:

• C8 review-calibration — calibrate the new model's recall first, then aim it at hot paths.
• C9 lesson-foundry — verified findings become lessons that compound into skills.

Installation

npm install -g @adlc/model-ratchet   # or use npx

Usage

model-ratchet [--top <n>] [--review-cmd <cmd>] [--timeout-ms <n>] [--churn-limit <n>] [--dry-run] [--allow-empty] [--json]

Flags

Hot Score Formula

SCORE = churn(limit)[file] × (1 + inDegree)

• churn(limit)[file] — number of distinct commits touching the file in the last --churn-limit commits (via git log).
• inDegree — number of repo source files (.mjs/.js/.ts/.tsx/.py/.cjs/.mts/.cts/.jsx, walk skips node_modules/, .git/, dist/) whose import/require/from specifiers resolve (relative resolution, try extensions) to this file.

Test/spec files (.test.*, .spec.*, test/, __tests__/) and non-source files (.md, .json, lock files) are excluded from both the candidate set and the import graph.

Default Mode (no --review-cmd, or with --dry-run)

Prints the prosecution plan table and suggested charter lines per file:

model-ratchet — Prosecution Plan
====================================================================
FILE                        CHURN  IN-DEGREE  SCORE
--------------------------  -----  ---------  -----
src/auth.mjs                   42          3    168
src/db/query.mjs               31          5    186
src/utils.mjs                  25          1     50

Suggested charter lines:
  Refute correctness of src/auth.mjs — hotspot: changed 42 times, imported by 3 files
  ...

Review Mode (--review-cmd)

Runs the command for each selected file with {file} substituted. Captures stdout and parses findings:

• Lines matching /\S+:\d+/ (e.g. src/foo.js:42: missing null check)
• Lines starting with - (bullet items)

Each finding is appended to .adlc/findings.jsonl:

{
  "ts": "2026-01-01T00:00:00.000Z",
  "tool": "model-ratchet",
  "file": "src/auth.mjs",
  "line": 42,
  "category": "ratchet",
  "severity": "unknown",
  "desc": "src/auth.mjs:42: missing null check"
}

Exit code 2 from review-cmd is treated as "findings present" (not an error). Exit codes other than 0 or 2, a run killed by --timeout-ms, or a run killed by a signal cause an operational error (tool exits 1); the remaining files are still reviewed.

Exit Codes

Examples

# Print prosecution plan for top 10 hot files
model-ratchet

# Top 5 files, last 500 commits
model-ratchet --top 5 --churn-limit 500

# Dry-run plan even if review-cmd is provided
model-ratchet --top 10 --review-cmd "adversarial-review {file}" --dry-run

# Run adversarial review and append findings
model-ratchet --review-cmd "adversarial-review --file {file}"

# Machine-readable output for orchestrators
model-ratchet --top 5 --json

# Run a custom linter as the reviewer
model-ratchet --review-cmd "eslint {file} --format compact"

Cron and CI Examples

GitHub Actions — on every model release

# .github/workflows/model-ratchet.yml
name: model-ratchet

on:
  # Manually trigger when a new model is released
  workflow_dispatch:
  # Or run monthly
  schedule:
    - cron: '0 9 1 * *'

jobs:
  ratchet:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0  # needed for full churn history
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - name: Run model-ratchet
        run: |
          npx @adlc/model-ratchet \
            --top 10 \
            --review-cmd "npx @adlc/adversarial-review --file {file}" \
            --json > ratchet-results.json
      - uses: actions/upload-artifact@v4
        with:
          name: ratchet-findings
          path: .adlc/findings.jsonl

Cron (shell)

# Run on every model release — add to crontab or a release script
# crontab entry: run on the 1st of every month at 09:00
# 0 9 1 * * cd /path/to/repo && model-ratchet --top 10 --review-cmd "adversarial-review {file}" --json >> .adlc/ratchet-runs.log 2>&1

# Or run manually after a model upgrade:
model-ratchet --top 20 --review-cmd "adversarial-review --file {file}" --json

CI gate (plan-only, no API key required)

- name: Print hot paths prosecution plan
  run: npx @adlc/model-ratchet --top 10 --json

Core Gaps

None. Uses churn(), isGitRepo(), appendEntry(), parseArgs(), opError(), pass(), printJson() from @adlc/core. All hot-score logic, import-graph walking, and finding parsing live in lib/.

Relationship to Sibling Tools

• adversarial-review — natural choice for --review-cmd; model-ratchet aims it at the highest-value files.
• review-calibration (C8) — calibrate first, then ratchet.
• lesson-foundry (C9) — consume the .adlc/findings ledger entries that model-ratchet appends.
• gate-manifest (C11) — findings from ratchet runs appear in the shared findings ledger that manifests track.