MODERNIZE FINDINGS: N
- [high|medium|low] path:line: obsolete API or behavior
  latest: exact replacement
  evidence: Pi version and current doc/source

MODERNIZE CLEAN
<funny ASCII art>

MODERNIZE OPPORTUNITIES: N
- path:line: extension responsibility or hand-rolled shape
  native: capability and introducing Pi version
  recommendation: adopt | investigate | partially replace | retire | retain, with concrete rationale
  evidence: current doc/source
  delta: observable behavior differences, benefits, and lost capabilities, or none
  constraints: compatibility, config migration, precedence, and approval needed, or none

---
name: modernize
description: "Audit the entire repository against latest Pi changes: compatibility defects plus opportunities to simplify implementation/configuration, improve behavior, adopt native capabilities, or retire extension responsibilities. Use for Pi extensions, SDK, config, prompts, skills, models, sessions, tools, TUI, providers, CLI, and terminal protocols."
disable-model-invocation: true
---

# Modernize

Audit plus workspace Pi dependency refresh.
Only dependency synchronization may modify `package-lock.json` and installed workspace dependencies.
Never edit implementation, dependency ranges, minimum Pi support, or user settings.
Two independent goals: fix obsolete behavior and take advantage of native Pi capabilities.
A clean compatibility verdict does not mean no adoption opportunities exist.

## Procedure

1. Run from the repository root:

   ```nu
   node .pi/skills/modernize/scripts/audit.mjs
   ```

2. If the command fails, stop.
   Report `MODERNIZE FAILED`, its exact reason, and local/latest versions when available.
   Do not scan, claim clean, or print celebratory art.

3. Treat JSON as collected evidence, not conclusions.
   Read both locations in `changelogs`, then inspect every entry in `candidates` and `capabilities`.
   `candidates` covers migration evidence after `candidatesAfterVersion`.
   `capabilities` includes that repository-resolved release through latest Pi, without migration-keyword filtering.
   Added, Changed, New Features, and Fixed entries can introduce capabilities; ordinary fixes and provider catalog entries are evidence to classify, not automatic findings.

4. Normalize relevant changes against latest Pi truth:
   - Read linked current documentation when present; otherwise inspect release-tag-pinned source or installed latest declarations.
   - Identify exact obsolete/replacement code shapes and native capability contracts.
   - Include CLI and settings syntax, terminal protocols, lifecycle behavior, prompt composition, and SDK APIs.
   - Check runtime exports and declared compatibility before proposing an SDK helper; an internal declaration is not necessarily a supported root export.
   - Do not discard a change merely because it is under Fixed or lacks migration keywords.

5. Map capabilities to extension responsibilities, not merely API names:
   - Inventory every extension's purpose from entrypoint, relevant README, configuration, and public-contract tests.
   - For each native capability, identify responsibilities or workflows it could replace, simplify, improve, or partially subsume.
   - Search both exact API shapes and responsibility-level shapes: tool selection, status reporting, notification delivery, auth resolution, persistence, projection, and similar work.
   - Inspect matching implementation, callers, tests, and configuration; lack of the new API's name in old code is not evidence of irrelevance.
   - Classify every change as migration, adoption opportunity, relevant overlap worth retaining, or no repository application.
   - Deduplicate shared capabilities, but inspect every affected extension before concluding no adoption opportunity exists.

6. Obtain complete scan scope from `git ls-files -z --cached --others --exclude-standard`.
   Pipe or chunk its NUL-delimited paths directly into searches; never print the full list into context.
   If enumeration fails, stop and report `MODERNIZE FAILED` with the exact reason.
   Search the complete scope for each normalized obsolete shape and derived adoption shape with `grep`, then `read` every relevant match and caller.
   Skip binary content, but never silently narrow the enumerated file set.
   Optional focus changes inspection priority only; whole-repository coverage remains mandatory.

7. Confirm a mandatory finding only with both:
   - Migration evidence from a changelog plus latest docs/source.
   - Contextual repository evidence showing obsolete behavior still applies at a precise `path:line`.

8. Confirm an opportunity or relevant overlap only with both:
   - Capability evidence from a changelog plus latest docs/source.
   - Contextual repository evidence at a precise `path:line` showing related implementation, configuration, or extension responsibility.
   Recommend adoption, bounded investigation, partial replacement, retirement, or retaining current behavior with an explicit reason.
   Behavior differences do not disqualify opportunities.
   Describe benefits, lost capabilities, observable behavior deltas, compatibility constraints, config migration, precedence changes, and approval needed.
   Distinguish drop-in simplification from intentional behavior change; never present partial overlap as an equivalent replacement.
   CLI/config syntax alignment can be useful even when no supported SDK helper removes the implementation.
   Report relevant overlap even when retaining the extension is recommended; explain why native behavior cannot fully replace it.
   Discard stylistic-only preferences and capabilities without a plausible repository application.

9. Refresh workspace Pi dependencies after completing the scan, before the final verdict.
   Preserve the initial JSON and repository-resolved version as the audit baseline; updating dependencies must not erase migration evidence.
   Enumerate root `package.json` dependency and devDependency names beginning with `@earendil-works/pi-`; root ranges remain the sole version authority.
   Run `mise tasks --all`, then `mise run //:lock` with those explicit package names, followed by `mise run //:install`.
   Do not use the unqualified lock task: installing an existing lock does not refresh its selected versions.
   Verify selected Pi versions in `package-lock.json` and installed package manifests against the latest release evidence; inspect the lock diff for unrelated changes.
   Run `mise run //:check` and `mise run //:test` against the refreshed dependencies.
   If refresh, installation, version verification, or checks fail, report `MODERNIZE FAILED` with the exact reason and changed files; never claim clean or silently revert unrelated work.
   Report dependency refresh separately from code findings, including before/after versions and verification results.
   Dependency age alone is not an obsolete-code finding, but leaving stale workspace Pi dependencies is not successful modernization.
   Do not silently raise minimum Pi support or change user configuration; implementation migrations and capability adoption remain recommendations.

## Output

Mandatory findings:

```text
MODERNIZE FINDINGS: N
- [high|medium|low] path:line: obsolete API or behavior
  latest: exact replacement
  evidence: Pi version and current doc/source
```

Order by severity, then path.
Deduplicate shared root causes.
Every finding needs `path:line`.

When no mandatory fixes exist:

```text
MODERNIZE CLEAN
<funny ASCII art>
```

Generate fresh, non-boxed ASCII art under 20 lines.
No art on failure or mandatory findings.

Append confirmed adoption opportunities and relevant overlaps after the verdict:

```text
MODERNIZE OPPORTUNITIES: N
- path:line: extension responsibility or hand-rolled shape
  native: capability and introducing Pi version
  recommendation: adopt | investigate | partially replace | retire | retain, with concrete rationale
  evidence: current doc/source
  delta: observable behavior differences, benefits, and lost capabilities, or none
  constraints: compatibility, config migration, precedence, and approval needed, or none
```

Order by path; deduplicate shared root causes.
Opportunities never change the compatibility verdict or suppress clean-verdict art.
Report both actionable adoption and relevant native overlap retained for evidenced reasons.
Do not imply that collection regression tests prove future agents' semantic judgments.