[lyfne123]

Summary

The user plugin reads a PyPTO program at two altitudes — IR lowering, and one
kernel's in-core instruction stream — with nothing that explains a whole run's
makespan. critical-path-analysis adds that level. It resolves the rank
directories under a run tree, invokes the wheel's critical-path tool, and gates
every conclusion on evidence the tool itself emits before classifying the run
as dependency-bound, resource-bound, or compute-bound. A reader comes away with
a bounding classification and the stall kind that supports it, or with a named
validation failure — not with a percentage of unknown provenance.

Changes

• plugins/pypto-user/skills/critical-path-analysis/: the skill. Artifact
  resolution over both run layouts, invocation and the meaning of each exit
  status, four validation gates (the compute-plus-stall tiling check must read
  exact; kernel families must have resolved names rather than cid<N>;
  capture reconciliation must report no dropped records; every rank must
  appear), and an interpretation table that maps each signal to where to act —
  data-wait to the upstream producer, core-wait to resource serialization,
  front-gap to launch cost rather than to any kernel.
• plugins/pypto-user/lib/dfx/capture.md: the capture contract, shared by
  every analysis over the same artifacts and following the developer plugin's
  lib/github pattern. It records the two facts that decide whether the
  numbers mean anything: split capture leaves the dependency graph and the
  timing in different directories while the tool has no flag to join across
  them, and a multi-round run collects on the first round only, so the analyzed
  makespan carries warm-up cost.
• plugins/pypto-user/.codex-plugin/plugin.json: the long description now
  covers the fourth workflow. No version bump — that belongs to the release
  workflow, from a clean tree on the default branch.
• tests/: register the skill in EXPECTED_USER_SKILLS, and extend
  DEPLOYABLE_ROOTS so the banned-text portability guard covers the user
  plugin's lib as well as its skills.

No behavior changes to any existing skill, and no migration step for anyone who
has the plugin installed; the new skill is additive.

Verification

• python -m unittest discover -s tests: 232 tests, OK. Run inside the push
  transaction at each pushed commit, together with ruff check tests,
  ruff format --check tests, and pyright — all clean, 0 errors.
• On-device walk (a2a3, under the shared device queue). A 64-producer /
  64-consumer explicit-fanin scene test, captured with --enable-dep-gen --enable-chip-swimlane, then analyzed by following the skill literally: the
  paired capture produced the artifact triple plus a merged trace; the analysis
  exited 0 over one rank, wrote its report beside the records, emitted both
  Perfetto traces, and passed the gates — 128 tasks, 4096 happens-before edges,
  tiling check ... (exact), resolved kernel names. It classified the run as
  resource-bound on the evidence the skill asks for: a static CPM path at 11.6%
  of the makespan with 37.7% core-wait stall.
• That walk falsified one gate, fixed in the second commit. The
  reconciliation check as first written returned nothing on a demonstrably
  clean capture, because the confirming line is info-level. See that commit
  message for what the run actually prints.
• A level-1 capture was re-run and confirmed to carry no AICPU task records
  while still producing a complete report, so the lowest-level recommendation
  is measured.
• python -m simpler_setup.tools.critical_path error paths, each confirming
  what the skill states: --report given a path exits 2; a missing root exits
  2; a directory without the artifact triple exits 2 naming the capture flag; a
  missing merged trace warns and still exits 0; an incomplete name map renders
  families as cid<N>.