lineth-monorepo: Skill for Codex

Dependency Maintenance

Use this workflow to maximize safe dependency progress without changing the repository's package-manager contract or hiding remaining risk.

Preflight

1. Read repo instructions first: AGENTS.md, CLAUDE.md, package-specific instructions, and CONTRIBUTING.md.
2. Detect the package-manager contract from lockfiles, packageManager, CI, deploy config, and package-manager guard scripts:
   • npm repo: use npm, preserve package-lock.json, and validate with npm ci.
   • pnpm repo: use pnpm, preserve pnpm-lock.yaml, pnpm-workspace.yaml, catalogs, and overrides.
   • Do not introduce a different lockfile, workspace file, package-manager metadata, or install command.
3. Check branch and worktree state with git status --short --branch. If unrelated changes are present, use an isolated worktree or avoid touching those files.
4. Read .nvmrc, .node-version, engines, .npmrc, deploy config, dependabot.yml, and the GitHub Actions pins in .github/workflows/*.yml and .github/actions/**/action.yml.
5. Capture the baseline: outdated report, audit report, lockfile state, and relevant validation commands.

Policy

• Treat release-age and cooldown rules as hard gates. Compute exact cutoff timestamps before selecting versions.
• In pnpm repos, minimumReleaseAge is a maturity window in minutes. Treat the configured minimumReleaseAgeExclude list as read-only: respect the existing entries, but never add or widen it to push a fresher version through — the maturity window is a hard gate, not a hurdle to bypass.
• Treat npm/pnpm dependency updates as owned by this skill. Do not re-enable Dependabot npm/pnpm package-ecosystem jobs unless the user explicitly asks.
• GitHub Actions are in scope for manual/agent sweeps and for policy enforcement, but Dependabot keeps opening the routine github-actions PRs: its cooldown in dependabot.yml (7 days) matches the action maturity window, so leave that job enabled and let the two coexist. Docker and other non-JavaScript ecosystems also stay under Dependabot.
• Pin GitHub Actions to a full 40-character commit SHA, never a tag or branch ref (@v4, @main). A movable ref lets the upstream repo change what runs in CI without review. Append the human-readable version as an end-of-line comment (uses: actions/checkout@<sha> # v7.0.0) and update that comment on every bump so the SHA stays auditable.
• Gate GitHub Actions on release age: only adopt a SHA whose release (tag) is older than 7 days. Actions use a longer 7-day window than the JS/npm/pnpm gate because an action runs with repository scope in CI, so a fresh release is higher-risk supply-chain surface. Treat the window as a hard gate, not a suggestion.
• Pin exact versions (mandatory). Every npm/pnpm dependencies/devDependencies specifier must be an exact pin, never a ^ caret or ~ tilde range. Floating ranges silently pull unreviewed releases and widen the supply-chain attack surface, so a single exact version is the only safe and reproducible default. When a bump touches a manifest, also tighten any pre-existing ^/~ range on that package to an exact pin. The exception is peerDependencies: those declare the version range a consumer must satisfy (the package never installs them itself), so pinning them exact invents false incompatibilities — leave intentional peer ranges as ranges.
• Preserve reference style otherwise: keep catalog: references, workspace: references, and repo-specific package placement unchanged. Pin the concrete version at the catalog definition so consumers stay on catalog:.
• Default PR scope is eligible patch and minor updates. Major upgrades, risky transitive fixes, and broad migrations get tracking issues unless the user explicitly approves doing them now.
• Prefer official migration guides, changelogs, package registry metadata, and advisory pages for decisions that affect risk.