[okorzh-amd]

• Description: what and why

  Someone who finds an upstream PR (a framework or kernel-library change) has three questions before taking it up for an AMD deployment: does my deployment run the code it changes on my GPU architecture and dtype; is the change already in the tree I measure, through this PR or another one; and should I take it now, carry it as a patch, wait, or drop it. Nothing in this repo answers them. review-pr is built for this repo's own PRs, and check-prior-art answers a different question ("is my planned change already upstream?"). An upstream PR is reviewed and measured on its author's platform, so a reader tends to take its benchmark, its green CI and "merged" as facts about their own deployment.

  What this PR changes: three files, all Markdown.

  • .claude/skills/analyze-upstream-pr/SKILL.md (new, 280 lines): the procedure.
  • .claude/skills/analyze-upstream-pr/references/dimensions.md (new, 91 lines): the six risk lenses.
  • AGENTS.md: one row in the "Where things are documented" table.

  It adds no script and no test, and it changes none of check-prior-art's files. The scripts this skill runs (read.sh, its lib.sh, and the inclusion probe) belong to feat(skills): add check-prior-art, a contributor skill that finds a planned change upstream #1850 and feat(pr_knowledge): probe whether an upstream PR is in a local git tree #1847 and keep the output they have there.

  Like review-pr and check-prior-art, the skill is written for an agent to run top to bottom. Every step writes an artifact into a work directory. A step that cannot run is recorded as SKIPPED and carried into the report, and every claim is refuted once before the report is written. The skill reads GitHub and never posts to it, and it never starts a server, a benchmark or a GPU job. It reuses check-prior-art for collection, for the inclusion probe and for the search for other PRs, and it cites that skill's gotchas (G3-G7).

  Inputs. target.txt holds:

  • the PR's repository and number;
  • the target GPU architecture (for example gfx942 or gfx950), dtypes and quantization method;
  • the deployment: model, parallelism, concurrency, sequence lengths, server flags and environment;
  • a local tree of the PR's repository (or a fork) and the commit the deployment runs;
  • selection: a second tree and commit for the code that selects the changed code when the PR's tree does not hold it, such as the framework that calls a kernel library's op;
  • the local patches on top.

  Step 0 asks the user for whatever is missing before collecting: a deployment with no model or flags, a tree, and, for a kernel-library PR, the selection tree. Without a tree, the on-path, inclusion and apply checks are SKIPPED.

  Collection (SKILL.md lines 89-94) is check-prior-art's read.sh plus two gh commands, and a third when GitHub refuses the diff:

  • read.sh writes four files:
    • pr.json: number, title, state, isDraft, mergedAt, mergeCommit (null until the PR merges), changedFiles, body, comments, reviews and url;
    • files.txt: every changed path with its status and line counts;
    • diff.txt, or a SKIPPED: diff line when GitHub will not render the diff;
    • xrefs.tsv: every PR that links to this one, with its state and title.
  • gh pr view --json headRefOid,baseRefName,statusCheckRollup writes checks.json: the head sha, the base branch and every check at the head.
  • gh api --paginate .../pulls/<N>/comments --jq ... writes inline.jsonl, one JSON object per inline review comment, with its author association. gh pr view has no field for inline review comments, so pr.json lacks them.
  • Only when diff.txt is a SKIPPED: diff line, gh api --paginate .../pulls/<N>/files --jq ... writes hunks.txt, each file's hunks. GitHub refuses a diff past 300 files, but its files endpoint still lists up to 3,000 files with each one's patch (none for a binary file). So hunks.txt stands in wherever the diff is read, though not where it is applied.

  Comments stay JSON. An untrusted-input section treats every title, body, comment, diff and hunk as data. It reads a comment's authorAssociation as whose word the comment is, not as proof that it holds.

  Steps, one artifact each:

  1. mechanism.txt: two sentences from the diff, naming path:symbol. Then the step reads xrefs.tsv and the comments:
     • A merged PR titled as a revert of this one is a revert.
     • A PR that either PR's title, body or comments call this one's replacement or reland is a successor. check-prior-art's SUPERSEDED class likewise rests on a named replacement.
     • A PR stacked on this one or following it up is not a successor.
     • An open or merged successor is recorded as SUCCESSOR: <ref> <state>. The agent asks the user about it, and it goes to Step 9.
  2. operating_point.txt: hardware, model, dtype, batch, lengths, parallelism, flags and reported results. Each is a verbatim quote with its source, or NOT STATED. Then one GAP line for each dimension that differs from the target.
  3. on_path.txt: each changed source path starts UNKNOWN. It moves to ON-PATH or OFF-PATH only on a cited selection site at the target commit: platform, arch, capability and dtype checks, backend registries, environment reads, tuning tables. The walk uses the selection tree when that tree holds the site.
  4. inclusion.txt: check-prior-art's Step 5 snippet runs once for the PR and once for each merged revert, with the merge commit from pr.json.
     • The probe exits 0 for included and 3 for unknown.
     • Exit 1 (a crash) or 2 (a usage error) is no answer. It becomes SKIPPED: inclusion with the probe's error.
     • unknown means nothing in local git showed the PR. It never means the PR is absent.
  5. effect.txt: the metric, the direction at the target and why. It is always labelled predicted. The author's numbers reach the report as quoted.
  6. conflicts.txt:
     • Other PRs. check-prior-art runs through its verdict (its Steps 0 to 7) in its own work directory, $WORK/prior-art, with this PR's mechanism, tree, commit and changed paths. Its search and path scan also find the PR under analysis, and any PR stacked on it. One sentence tells the agent to keep those out of the shortlist and classes it writes. The verdict line goes into conflicts.txt. When the verdict says -- incomplete, check-prior-art's Coverage goes into the report.
     • The diff at the target. git apply --check of diff.txt runs every time, in a scratch worktree at the target commit.
       • The result is APPLIES, or FAILS with the first failing hunk.
       • After a failure, a diff that applies with --reverse means the tree already has the change. That settles an unknown inclusion as included.
       • Each local patch is then applied in the worktree and the diff is checked again. A failure that only appears after a patch goes through the same --reverse check. If the diff applies backwards, the line is local:<patch> REVERSE: the patch already carries the PR, and inclusion becomes included. A failure in both directions is a CONFLICT, as for a patch that carries an older head of the PR. Any other failure is drift.
       • GitHub abbreviates a binary file's index, so a Binary files ... differ stanza never applies. Every check therefore passes $BIN, an --exclude for each binary stanza's old and new path, and records each such path as SKIPPED: apply -- <path>: binary.
       • The worktree is removed afterwards. Nothing is applied in the user's tree.
  7. risks.txt: one line per lens in references/dimensions.md.
  8. measure.md (optional): a plan the user runs, never the skill. It has:
     • two arms that differ by the PR alone;
     • the control arm run twice, for the noise floor;
     • accuracy checked before timing when numerics change;
     • the operating point;
     • a decision rule written before the first run;
     • proof that the changed code ran;
     • results labelled measured.
  9. refutations.txt: one FINDING / ATTEMPT / OUTCOME block for each of these: risk, on-path line, gap, unknown inclusion, effect, check-prior-art verdict, conflict, merged revert and successor.
     • An unknown inclusion is attacked in the tree's own history, as check-prior-art's Step 6 does.
     • A successor is attacked in both PRs' bodies, because a stacked or follow-up PR does not replace this one.
  10. report.md: the recommendation, the mechanism, the evidence rows, Coverage and the next step, plus the head sha and base branch from checks.json. Each evidence row is labelled verified, quoted, predicted, measured or inferred.

  Recommendation (SKILL.md lines 25-39). One table with ten rows. The first row that applies wins, the last row takes every case left, and each row carries its next step:

  1. NOT-APPLICABLE -- reverted by <ref>: a merged revert survived refutation.
     • It adds , relanded in <ref> when there is a merged reland, and the next step is to analyze that reland.
     • When the tree carries the PR and not its revert, the next step says so: the tree runs a change that upstream backed out.
  2. NOT-APPLICABLE -- already in tree: the probe or the reverse apply found the PR. It reads -- already in tree via <patch> when the reverse apply after a local patch found it. It reads -- already in tree via <ref> when check-prior-art's verdict is EXISTS-MERGED -- in your tree or EXISTS-OPEN -- in your tree, because then the tree already runs the change through another PR.
  3. NOT-APPLICABLE -- merged as <ref>: the PR is not merged, and check-prior-art's verdict is EXISTS-MERGED -- inclusion unchecked. The next step is to analyze <ref> instead.
  4. NOT-APPLICABLE -- superseded by <ref>: the PR is not merged and either:
     • an open or merged successor survived refutation; or
     • the PR closed unmerged and check-prior-art's verdict is EXISTS-OPEN -- inclusion unchecked.
  5. NOT-APPLICABLE -- off path: <condition>: every changed path is OFF-PATH.
  6. NEEDS-MEASUREMENT: an on-path line the effect rests on stayed UNKNOWN, or a blocking risk that only a run can settle survived.
  7. WAIT-FOR-MERGE -- <risk>: the PR is open and upstream is settling a surviving risk. That risk is changes requested, an open design question, a check failing at the head, or a competing open PR (check-prior-art's EXISTS-OPEN -- inclusion unchecked).
  8. ADOPT-NOW: merged, on path, no blocking risk survived. It adds -- inclusion unchecked when the probe answered unknown or was SKIPPED.
  9. CARRY-AS-PATCH: open, or closed unmerged with no surviving successor; on path; no blocking risk survived. It adds -- conflicts with <patch> from Step 6.
  10. NOT-APPLICABLE -- <lens>: <condition>: everything else, such as a confirmed blocking risk.

  ADOPT-NOW and CARRY-AS-PATCH also add -- does not apply at <commit> when the apply check failed. Their next step then starts by resolving the hunk it names.

  Risk lenses. references/dimensions.md holds six lenses. Each is a way a change that is right on its author's platform turns out wrong, slower or inert on a ROCm deployment. What the change does, which paths reach it and whether it is in the tree are covered by Steps 1 to 4. Each lens says where to look, what makes it a risk and when it stays clear. Like review-pr's rules, each cites the public upstream PR it was learned from:

  • L1, parity with the CUDA path: [Bugfix] Fix ROCm UVA CPU weight offloading broken by #32993 vllm-project/vllm#34543, #57425;
  • L2, weights and quantization: #56359;
  • L3, numeric formats and bounds (FP8 e4m3fnuz on gfx942 against OCP e4m3fn on gfx950, and offset width): #46730, #39953;
  • L4, collectives and parallelism: #16010;
  • L5, tests and whether ROCm CI ran them: #48654;
  • L6, dependency pins: #48155, #47072.

  Dependency. This PR depends on feat(skills): add check-prior-art, a contributor skill that finds a planned change upstream #1850 ("feat(skills): add check-prior-art, a contributor skill that finds a planned change upstream"). This skill uses that PR's read.sh, its Step 5 snippet, its procedure through the verdict, and its gotchas. feat(skills): add check-prior-art, a contributor skill that finds a planned change upstream #1850 in turn depends on feat(pr_knowledge): probe whether an upstream PR is in a local git tree #1847, the inclusion probe. The kernel-names refactor that feat(pr_knowledge): probe whether an upstream PR is in a local git tree #1847 used to stack on has landed in main as refactor(kb_store): move derive_kernel_names into kb_store.identity.kernel_names #2028. This PR no longer carries that refactor.

  Every PR in the stack targets main. Until feat(pr_knowledge): probe whether an upstream PR is in a local git tree #1847 and feat(skills): add check-prior-art, a contributor skill that finds a planned change upstream #1850 merge, this diff also carries their commits: 10 from feat(pr_knowledge): probe whether an upstream PR is in a local git tree #1847, 16 from feat(skills): add check-prior-art, a contributor skill that finds a planned change upstream #1850 and 14 from this PR. Against main that is 17 files, +1967/-20. feat(skills): add check-prior-art, a contributor skill that finds a planned change upstream #1850's head 75d77c943 is an ancestor of this head, and git diff 75d77c943 6cc661136 touches only the three files above (+372/-0).

• Linked issue(s): none.

• Tests: added/updated? commands run? (what to test; if a test was replaced, where its assertions live now):

  No test is added, because this PR adds no script and no Python: its three files are Markdown. The collection it runs is check-prior-art's read.sh, which scripts/tests/test_check_prior_art.py in feat(skills): add check-prior-art, a contributor skill that finds a planned change upstream #1850 pins, plus three gh commands and one awk line written out in SKILL.md. read.sh keeps comments as the JSON that gh pr view returns, and inline.jsonl is JSON too, so there is no rendered comment format for a test to pin.

  scripts/check_cli_references.py checks the python -m modules and src/ script paths in every SKILL.md. This one names neither, so nothing checks its read.sh path or its gh and awk commands automatically. They were checked by running them, below.

  Commands run at head 6cc661136 (main 7ac8c1229):

  • pytest scripts/tests/test_check_prior_art.py scripts/tests/test_check_cli_references.py src/kernelforge/tests/knowledge/pr_knowledge/test_inclusion.py: 47 passed (10 + 4 + 33).
  • pytest -n 16 scripts/tests: 742 tests, 738 passed. Main has 732, 728 passed. The 10 extra tests are test_check_prior_art.py from feat(skills): add check-prior-art, a contributor skill that finds a planned change upstream #1850. The same 4 test_code_metrics.py fork-comment tests fail on both, from the host: a package.json with "type": "module" above the pytest temp directory makes Node.js load their harness.js as an ES module (ReferenceError: require is not defined).
  • pre-commit run --files on the three files passed these hooks: trailing whitespace, end of file, merge conflicts, large files, private key, line endings, reuse, gitleaks, codespell and check-cli-references.
  • python scripts/check_cli_references.py: exit 0.
  • lint-imports: 10 kept, 0 broken.
  • python scripts/code_metrics.py:
    • with --base-ref set to feat(skills): add check-prior-art, a contributor skill that finds a planned change upstream #1850's head: PASSED, 3 files judged;
    • with --base-ref origin/main, which includes the stacked PRs: PASSED, 17 files judged.
  • ruff check, ruff format --check and scripts/check_broad_suppress.py on the 7 Python files the stacked PRs change: clean. This PR changes no Python file.

  Live, read-only run against public vLLM PRs, at 88bd0be46; the last commit changes only how Step 6 reads a failure after a local patch. The tree was a local vLLM fork at a9b39d6dcb, a commit from 2026-08-05, and the probe ran from this source tree.

  • Step 0 on [Bugfix][ROCm] Alias SparseAttnIndexerKpool.forward_cuda to forward_native (GLM-5.3-Flash boot crash) vllm-project/vllm#57425:
    • It wrote pr.json, files.txt, diff.txt and xrefs.tsv.
    • It wrote checks.json with the head sha, base main and 87 checks.
    • It wrote inline.jsonl with the 3 inline review comments, which pr.json does not carry.
  • gh pr view --json statusCheckRollup returned the same number of check contexts as GraphQL's totalCount for six PRs. They had 10 to 254 contexts each; #50243's 254 is more than one GraphQL page of 100.
  • Step 0 on [Misc] Add SPDX-License-Identifier headers to python source files vllm-project/vllm#12628, which changes 1012 files: read.sh wrote SKIPPED: diff (GitHub's HTTP 406 past 300 files), and the hunks.txt command wrote hunks for all 1012 paths, exit 0. On #50243, whose diff GitHub renders, the command wrote nothing and exited 0.
  • Step 4's snippet:
    • #51131, which the tree carries: included, method subject, exit 0.
    • #46730 and #57425, which the tree does not carry: unknown, method none, exit 3.
  • Step 6's apply check, run as written in SKILL.md:
    • #51131: FAILS forward and applies with --reverse, so the tree has it.
    • #46730: FAILS both forward and with --reverse, because the tree's copy of fused_indexer_q.py differs from the PR's base. The qualifier is -- does not apply at a9b39d6dcb.
    • #57425: FAILS, because its path is absent at that commit.
    • #50243, which changes a PNG. Without $BIN, the diff fails at the PR's parent, on the binary stanza alone ("cannot apply binary patch ... without full index line"). With $BIN, it applies at the parent, and applies with --reverse at the merge commit.
    • A scratch repository with binary files added, deleted, modified, and renamed with a change: with $BIN, the diff applies forward at the parent and with --reverse at the child. Excluding only the new name fails the reverse check on the rename.
    • A scratch repository whose local patch is the PR's own diff, at 6cc661136: the diff applies at the commit and the patch is OVERLAP. After the patch, the forward check fails with "patch failed: m.py:1" and the --reverse check applies, so the line is local:<patch> REVERSE, not CONFLICT. With a patch that changes the same line differently, both directions fail: CONFLICT.
    • Afterwards the scratch worktree was removed, and the tree's worktree list no longer named it.
  • check-prior-art's search.sh, run with two terms for #57425's mechanism (SparseAttnIndexerKpool forward_native and forward_cuda forward_native ROCm), listed #57425 itself among its 18 candidates. That is the case the Step 6 exclusion sentence covers.

• Size/complexity triggers crossed: split, or why the shape is right: none.

  • This PR adds no Python. pr-hygiene's CI count is taken against origin/main and reports 253 production Python lines. All of them come from feat(pr_knowledge): probe whether an upstream PR is in a local git tree #1847: its head alone gives 253. feat(skills): add check-prior-art, a contributor skill that finds a planned change upstream #1850 and this PR give 0 (0 against feat(skills): add check-prior-art, a contributor skill that finds a planned change upstream #1850's head).
  • The three files add 372 lines:
    • SKILL.md is 280 lines and states 280 as its budget, as review-pr (350) and check-prior-art (240) state theirs.
    • The lenses are in references/dimensions.md (91 lines), which is opened only at Step 7.
    • The search for other PRs, the collection, the probe snippet and the gotchas belong to check-prior-art; this skill references them and does not restate them.
    • The AGENTS.md row is one line.

• If this simplifies or refactors: which mechanism was removed, which contract was preserved, and the tests that show it: not a refactor; a new skill.

• Observable effect: what an operator will now see, and what the old behaviour cost them (if none, why the change is unobservable):

  • The runtime, the CLI and the shipped package do not change. check-prior-art's scripts and their artifacts do not change either.
  • A contributor working in this repository with Claude Code now has an analyze-upstream-pr skill, listed in AGENTS.md. Given an upstream PR and a target deployment, it writes a work directory that ends in report.md, with one of the ten recommendations and its next step.
  • These are the effects the recommendation rows decide:
    • A PR whose change upstream merged through another PR is reported NOT-APPLICABLE -- merged as <ref>, with "analyze <ref> instead". It is not reported CARRY-AS-PATCH.
    • A PR with a surviving replacement or reland, or one that closed unmerged while an equivalent PR is open, is reported NOT-APPLICABLE -- superseded by <ref>.
    • A tree that already runs another PR doing the same thing gets NOT-APPLICABLE -- already in tree via <ref>.
    • A deployment that already carries the PR as a local patch gets NOT-APPLICABLE -- already in tree via <patch>. It is not told the PR conflicts with its own patch and to apply diff.txt a second time. CARRY-AS-PATCH creates such a patch, so a rerun after it reaches this case.
    • A PR whose every changed path is excluded at the target by a cited selection site is reported NOT-APPLICABLE -- off path: <condition>.
    • An open PR competing with another open one waits (WAIT-FOR-MERGE).
    • When the PR's diff does not apply at the target commit, ADOPT-NOW and CARRY-AS-PATCH say so (-- does not apply at <commit>). They no longer tell the user to apply a diff that fails.
  • A PR that changes a binary file is judged by its text hunks, and each binary path is listed as SKIPPED: apply. Without the exclusion, git apply would read every such PR as -- does not apply, and the reverse check could not show that the tree already has it.
  • A PR past GitHub's 300-file diff limit still has its mechanism, effect and risks read from each file's hunks. The apply check is then SKIPPED, which the report's Coverage shows.
  • An open PR is not reported superseded by a PR stacked on it or following it up (Step 1). A PR stacked on it does not hold it at WAIT-FOR-MERGE either, because Step 6 keeps that PR out of check-prior-art's shortlist and classes. An example is [ROCm][Perf][Qwen3.8] Mono decode layer for Qwen3.8 on MI355X vllm-project/vllm#60833 and #61271, a draft stacked on it.
  • A probe that crashes or is misused is reported as SKIPPED: inclusion with its error. It is not read as an answer.
  • Step 0 asks for the tree, and for a kernel-library PR the framework tree, before collecting. Without that, the report would end with every on-path line UNKNOWN.
  • Costs:
    • Step 6 runs check-prior-art's full keyword search and open-PR path scan, which takes minutes on a large upstream repository.
    • Step 6 registers a temporary worktree in the user's tree (git worktree add, then git worktree remove).
    • The skill needs jq and gh, and gh must be authenticated because check-prior-art's path scan uses GraphQL.
  • Before this change, the analysis was manual and its evidence went unrecorded. A green upstream CI, an author's benchmark or "merged" could be taken as facts about an AMD deployment that never ran the changed code, or that already had the change.

• Breaking changes: no. The PR only adds files and one AGENTS.md row. check-prior-art's read.sh, lib.sh and their outputs are unchanged.

• PR addresses single concern: yes. The skill is one capability. The other commits in the diff belong to the stacked PRs beneath it, feat(pr_knowledge): probe whether an upstream PR is in a local git tree #1847 and feat(skills): add check-prior-art, a contributor skill that finds a planned change upstream #1850.

• Root cause is upstream (Magpie/TraceLens/GEAK/IntelliKit/AgentKernelArena), ticket filed: no; not applicable.

[chaojhou]

Thanks @okorzh-amd. The scripts are sound:

• References parsed from comments are validated before any gh api call.
• The header-forgery normalisation matches the description.
• The probe gets its arguments as an array.

One must-fix, in the procedure:

Step 6 never excludes the PR under analysis from the check-prior-art run.

• analyze-upstream-pr/SKILL.md:208-210 sends the open-PR question to check-prior-art, with files.txt as the planned paths, and carries back its DUPLICATE and OVERLAPPING classes.
• overlap.sh has no exclusion, and check-prior-art defines DUPLICATE as "does what the mechanism says, in the same code path".
• For an open PR, the PR itself is an overlap.tsv row that matches every planned path. Followed literally, it comes back as its own DUPLICATE, and the WAIT-FOR-MERGE row ("a competing open PR") can fire instead of CARRY-AS-PATCH.
• review-pr's fetch.sh drops the PR itself ($1 == self), and that is the check this step replaces.
• Please say in Step 6 to leave <owner/name>#<N> out of the shortlist and the classes, or give overlap.sh an exclusion.

This PR also contains #1847, whose must-fix applies here too.

[github-actions]

Gate job conclusion: success (run) on 6cc661136dcc50d35990983c06ef2247c4f2b5c6, as reported by GitHub.

The report below was uploaded by that run; the conclusion above is the result.

---

Code metrics gate: PASSED

Judged: the 17 files this change touches. Files it does not touch never fail it; anything found there is listed under Outside this change for information.

Dimension	Limit	New	Worse	Baseline out of date	Baseline entries	vs base
Cyclomatic complexity	fails > 20	0	0	0	59	+0
Cognitive complexity	fails > 30	0	0	0	245	+0
Function length (lines)	fails > 80	0	0	0	390	+0
Nested block depth	fails > 5	0	0	0	24	+0
Parameter count	fails > 5	0	0	0	95	+0
Module length (lines)	warns > 800, fails > 1200	0	0	0	50	+0
Duplicated lines per file	fails > 0	0	0	0	96	+0
Dead code (vulture)	fails > 0	0	0	0	2	+0

Check	Findings	Effect
Comments	0
English only	0
Production code imports test code	0
Repeated literals	0
A1 Private name of another package	0
A8 Flag argument	0
A9 Tuple return	0
A10 Raw vocabulary comparison	0
A11 Hidden global write	0
A12 Pure forwarder	0
A12 Single-implementation abstraction	0

116 findings in files this change does not touch

Outside this change (informational): 116

Unit	Dimension	Baseline	Now
src/hyperloom/orchestrator/state/shared_state.py resolve_graded_comparison	Cognitive complexity	absent	34
src/hyperloom_kb/collect/mapping.py _experience	Cognitive complexity	absent	31
src/hyperloom_kb/schema.py FieldDeclaration.__post_init__	Cognitive complexity	absent	32
src/kernelforge/cli/forge_loop_command.py _prepare_measurement_driver	Cognitive complexity	absent	36
src/kernelforge/cli/forge_loop_command.py _read_kb_warm_start	Cognitive complexity	absent	40
src/kernelforge/cli/forge_loop_command.py forge_loop	Cognitive complexity	absent	31
src/kernelforge/loop/runner.py IterationLoop._collect_session_candidate	Cognitive complexity	absent	44
src/kernelforge/loop/runner.py IterationLoop._rule_on_attempt	Cognitive complexity	absent	38
src/hyperloom/inference_optimizer/cli/__init__.py _reexport_session_environment	Function length (lines)	absent	111
src/hyperloom/inference_optimizer/cli/__init__.py _resolve_agent_lineup	Function length (lines)	absent	89
src/hyperloom/inference_optimizer/cli/__init__.py _resolve_run_topology	Function length (lines)	absent	92
src/hyperloom/inference_optimizer/cli/__init__.py _resume_session	Function length (lines)	absent	170
src/hyperloom/inference_optimizer/cli/__init__.py _seed_fresh_session	Function length (lines)	absent	170
src/hyperloom/inference_optimizer/multi_node/cli.py _restart_multinode	Function length (lines)	absent	107
src/hyperloom/inference_optimizer/multi_node/scripts/launch_multinode.py _build_parser	Function length (lines)	absent	84
src/hyperloom/inference_optimizer/multi_node/scripts/launch_multinode.py _spawn_rank_actors	Function length (lines)	absent	84
src/hyperloom_kb/sync.py GlobalSync.pull	Function length (lines)	absent	84
src/kernelforge/cli/forge_loop_command.py _RunReporter.build_result	Function length (lines)	absent	92
src/kernelforge/cli/forge_loop_command.py _prepare_measurement_driver	Function length (lines)	absent	136
src/kernelforge/cli/forge_loop_command.py _read_kb_warm_start	Function length (lines)	absent	149
src/kernelforge/loop/runner.py IterationLoop._close_iteration	Function length (lines)	absent	117
src/kernelforge/loop/runner.py IterationLoop._collect_session_candidate	Function length (lines)	absent	185
src/kernelforge/loop/runner.py IterationLoop._implementer_history	Function length (lines)	absent	112
src/kernelforge/loop/runner.py IterationLoop._rule_on_attempt	Function length (lines)	absent	102
src/kernelforge/loop/runner.py IterationLoop._source_attempt	Function length (lines)	absent	175

...and 91 more; the job log lists every row.

Verdict computed by the gate scripts in /home/runner/work/_temp/code-metrics-gate, not by this tree's copy.

_{Thresholds and sources: [tool.hyperloom.code_metrics] in pyproject.toml. Tools: complexipy 8.0.1, jscpd 5.4.1, ruff 0.16.2, vulture 2.16.}

[chaojhou]

PR #1851 -- feat(skills): add analyze-upstream-pr to judge an upstream PR for an AMD deployment

What it does: Adds a contributor skill (.claude/skills/analyze-upstream-pr/) that takes an upstream framework or kernel-library PR plus a target AMD deployment and writes a report on whether the deployment runs the changed code, whether the local tree already has it, and one of five recommendations. It collects upstream-only data with fetch_upstream.sh, reuses check-prior-art for duplicate PRs (drop_self.sh keeps the PR out of its own check), and moves the shared comment and PR-state jq into check-prior-art/lib.sh. The GitHub diff also carries the stacked #1850 (check-prior-art) and #1847 (inclusion probe).

Blocking issues: 1

1. [X2] Description is stale after the last commit: "14 tests" and no drop_self.sh [verified]
   Problem: the body says test_analyze_upstream_pr.py has 14 tests and never mentions drop_self.sh, but head commit 9e3cf82 adds .claude/skills/analyze-upstream-pr/drop_self.sh and five more tests, 19 in total. scripts/tests/test_analyze_upstream_pr.py:400
   Impact: the description no longer matches the diff at head: a reader misses a new script that rewrites check-prior-art's candidates.tsv and overlap.tsv, and the stated test count is wrong.
   Action: update the body: add drop_self.sh to the collection/Step 6 description, list the two drop_self tests it pins, and change "14 tests" to 19.

SKIPPED: V4 -- PARTIAL overlap for #1032, #1154, #1276, #1675 (each cut at its first 100 files), overlap there unchecked

Checked: analyze-upstream-pr/{SKILL.md Step 6 and recommendation table, drop_self.sh, fetch_upstream.sh}, check-prior-art/{lib.sh PR_JQ/render_comments/replace_file, search.sh, overlap.sh, SKILL.md Steps 2-4}, AGENTS.md row, .importlinter, test_analyze_upstream_pr.py at head and head~1, body.txt, comments.txt, openprs.txt, ci.txt; earlier self-duplicate hypothesis rechecked and fixed at head | Ran: hl_fetch.py 1851; git show of head files; python ..\pr_tools\c901.py on the 7 changed src/kernelforge units (max head complexity 10); shell scripts reviewed statically, nothing run; gh run list --commit 9e3cf82 after approving the fork runs (9 workflows success, the 2 label-gated E2E skipped) | Base: 1a444f6 | Head: 9e3cf82

[chaojhou]

PR #1851 -- feat(skills): add analyze-upstream-pr to judge an upstream PR for an AMD deployment

What it does: Adds .claude/skills/analyze-upstream-pr/, a procedure that takes an upstream framework or kernel-library PR plus a target AMD deployment and writes a report: does the deployment run the changed code, is the change already in the tree, and one of five recommendations. It collects with review-pr's fetch.sh plus a new fetch_upstream.sh, reuses check-prior-art for duplicate PRs (with drop_self.sh to keep the PR out of its own check), and moves the shared comment and PR-state jq into check-prior-art's lib.sh. The diff also carries the stacked #1850 and #1847.

Blocking issues: 2

1. [free:merged-duplicate] A PR whose change already landed through another PR comes out CARRY-AS-PATCH [verified]
   Problem: Step 6 carries check-prior-art's DUPLICATE and OVERLAPPING classes into conflicts.txt (SKILL.md:206-211), but the recommendation table reads another PR only as "a competing open PR" under WAIT-FOR-MERGE (SKILL.md:29); no row handles a merged DUPLICATE, and Step 4 checks the inclusion of this PR only. An open PR that is ON-PATH with no surviving blocking risk therefore falls to CARRY-AS-PATCH. .claude/skills/analyze-upstream-pr/SKILL.md:31
   Impact: the user is told to apply the PR's diff as a local patch (SKILL.md:54) although upstream already merged the change through another PR, which the tree may already run or can take with ADOPT-NOW.
   Action: run check-prior-art through its verdict and map it into the table: EXISTS-MERGED-INCLUDED -> NOT-APPLICABLE -- already in tree via <ref>, EXISTS-MERGED-NOT-IN-TREE -> analyze <ref> instead, EXISTS-OPEN -> WAIT-FOR-MERGE.

2. [X2] The description is stale after the last commit [verified]
   Problem: unchanged since the last round at this head: it says test_analyze_upstream_pr.py has "14 tests" and never mentions drop_self.sh; head 9e3cf82 adds drop_self.sh and five more test cases, 19 in total. scripts/tests/test_analyze_upstream_pr.py:400
   Impact: the description does not match the diff at the head.
   Action: update the body to the final shape (if drop_self.sh goes as suggested below, describe that instead).

---

Design review (requested by the maintainer; beyond the blocking bar)

The aim of this section is a smaller PR, not more guards: each point says what to delete or merge.

Purpose, route, files. Skill files: SKILL.md (292 lines), references/dimensions.md (lenses L1-L11), references/measurement.md; scripts fetch_upstream.sh and drop_self.sh; tests scripts/tests/test_analyze_upstream_pr.py (19 cases); check-prior-art's lib.sh gains the shared helpers and read.sh / search.sh use them; one AGENTS.md row.

1. Completeness. Item 1. Step 6 notices when the PR's diff no longer applies to the target commit (SKILL.md:216-218), but no row or qualifier reads that, and CARRY-AS-PATCH then tells the user to apply that same diff; with no local patches the check does not run at all (:219) -- always run git apply --check against the target commit. For a kernel-library PR the code that selects the kernel lives in the framework, but target.txt holds one tree, so on-path and inclusion cannot both be checked. When GitHub refuses the diff, fetch.sh exits before writing files.txt, and Steps 1 and 6 lose their input with only SKIPPED: fetch in the report. Without a tree every on-path line stays UNKNOWN; ask for a tree at Step 0.

2. Simpler / smaller.

• Collection: check-prior-art's read.sh already writes the state lines, comments, cross-references, per-file counts and a diff with its own SKIPPED line, through the same lib.sh functions; only CI at the head commit is missing (two gh api lines). Using it removes fetch_upstream.sh's comment, state and timeline parts and the fetch.sh-then-read.sh fallback.
• linked.txt: only reverted-by and superseded-by are read (SKILL.md:26-27); closes (a separate GraphQL call), supersedes and reverts are only described, and Step 9 re-proves a revert from its diff anyway. Reading the titles in xrefs.tsv and the comments is enough.
• drop_self.sh: delete it. The sentence at SKILL.md:210 ("keep <owner/name>#<N> out of the shortlist and classes") is sufficient because the agent writes the shortlist, and the script both misses the third source (pathlog.txt) and rewrites another skill's tables. My earlier must-fix offered "a sentence, or an exclusion in overlap.sh"; the sentence is the right one.
• Lenses: L2 repeats Steps 1-2, L3, L4 and L10 repeat Step 3's caller walk, L11 overlaps WAIT-FOR-MERGE. Keep the AMD-specific L5-L9 plus a dependency-pin lens, each citing the PR it was learned from, as review-pr requires of its rules; fold measurement.md into Step 8.

3. Redundancy and silent failure. Comments are fetched twice (fetch.sh and fetch_upstream.sh), open PRs are scanned twice (openprs.txt and check-prior-art), the merge commit is read three ways, the probe is called two ways, and the PR is excluded in three places. A failed reference lookup, rate limit included, becomes an unresolved row with no retry and is not listed in coverage, so a failed "Reverted by #N" lookup cannot trigger the reverted row; a probe crash (exit 1 or 2) is recorded and the script still exits 0, and SKILL.md never names that outcome.

4. Docs and comments. Item 2; fetch_upstream.sh:18-19 says anything that cannot be collected exits non-zero except an unresolvable reference, but :149-152 record a failed probe and carry on; SKILL.md:109 says read.sh's files.txt "still lists every path", but read.sh writes it under prs/<owner>/<name>/<N>/ with extra columns, not the $WORK/files.txt that Steps 3 and 6 read.

5. Tests. Keep two and move them into test_check_prior_art.py, run against read.sh: the forged-header test (test_analyze_upstream_pr.py:189) and the ordering-and-roles test (:132). Both pin render_comments, which read.sh now depends on and test_check_prior_art.py checks only by its first line. The rest pin incidental detail or duplicate other tests: the exact 14-row table (:227), the repeated "#41" case (:297), the merge-commit rule already pinned in test_check_prior_art.py (:319), a literal string (:341), the unused GraphQL call (:349), usage messages (:356, :416), printf padding (:409), and the drop_self.sh tests if the script goes.

Starting from zero. A skill with no scripts of its own: read.sh plus one CI command for collection, one probe snippet for the PR and for each merged revert, Steps 1-5 and 9-10, and about 50 lines of AMD-specific lenses. It is worth a separate skill: the on-path step, the operating-point gaps and the recommendation table do not fit check-prior-art's search-driven flow.

Change list, in order of impact:

1. Item 1: run check-prior-art through its verdict and map it into the table.
2. Delete drop_self.sh and its tests; keep the one-sentence exclusion.
3. Collect with read.sh plus one CI command; delete fetch_upstream.sh's comment, state and timeline parts and stop using fetch.sh (SKILL.md:64-65, 93-110, 204-205).
4. Replace linked.txt with xrefs.tsv plus one sentence; drop closes, supersedes, reverts and the GraphQL call (or, if a helper stays, list its unresolved rows under coverage).
5. One probe snippet; treat exit 1 and 2 as SKIPPED.
6. Close the gaps in point 1: always git apply --check against the target commit and qualify the recommendation; an input for the tree that holds the selection code; ask for a tree at Step 0.
7. Cut dimensions.md to the AMD-specific lenses with their source PRs; fold measurement.md into Step 8.
8. Move the two comment tests; delete the others; revert lib.sh:5.
9. Rewrite the description (item 2).

Checked: SKILL.md (recommendation and next-step tables, Step 6), drop_self.sh, fetch_upstream.sh, references/dimensions.md and measurement.md, check-prior-art's lib.sh / read.sh / SKILL.md Steps 4-7, test_analyze_upstream_pr.py, the description against the head | Ran: static review only (no bash or jq on this host); no test suite | Base: 1a444f6 | Head: 9e3cf82

[chaojhou]

PR #1851 -- feat(skills): add analyze-upstream-pr to judge an upstream PR for an AMD deployment

What it does: PR #1851 adds a contributor skill, .claude/skills/analyze-upstream-pr/ (SKILL.md plus references/dimensions.md, and one row in the AGENTS.md table). The skill judges an upstream framework or kernel-library PR against an AMD deployment and ends in one recommendation. It collects the PR with check-prior-art's read.sh plus two gh calls, finds the selection site that decides whether the deployment runs the changed code, probes the local tree with the pr_knowledge inclusion probe, runs check-prior-art for competing PRs, runs git apply --check on the diff at the target commit, checks six AMD-specific risk lenses, refutes each claim, and maps the result to one row of the recommendation table. It is cleanly stacked on #1850: origin/pr-1850 (56702fb) is an ancestor of the head, and git diff origin/pr-1850 origin/pr-1851 touches only those three files, so the check-prior-art files, the inclusion probe and test_check_prior_art.py are identical to #1850 and belong to that PR's review.

Blocking issues: 1

1. [desync-body-describes-removed-design] The PR description still describes the earlier design: fetch_upstream.sh, a 14-test file, measurement.md, the lib.sh lift and a new comments.txt shape, none of which exist at head [verified]
   Problem: The live body (checked with gh at head f8bc23d, updated 2026-10-20) describes a design that later commits replaced. Commits 100feb6 ('collect an upstream PR with check-prior-art's read.sh and one probe snippet') and d6b3c78 ('keep only the AMD-specific risk lenses') did the replacing.

What the body says:

• Collection uses review-pr's fetch.sh plus a new fetch_upstream.sh, which writes comments_untrusted.txt, linked.txt and inclusion.txt.
• It adds scripts/tests/test_analyze_upstream_pr.py with 14 tests.
• It adds references/measurement.md.
• It lifts the comment collection and the PR-state jq into check-prior-art's lib.sh.
• check-prior-art's read.sh comments.txt changes shape (the 'Observable effect' section).
• There are 'eleven risk lenses' and SKILL.md is 292 lines.
• It gives a five-row recommendation list.

What the head has:

• Collection is read.sh plus a gh pr view call for checks.json and a gh api call for inline.jsonl (SKILL.md:89-94).
• None of those scripts, tests or files exist (git ls-tree origin/pr-1851 lists only SKILL.md and dimensions.md under analyze-upstream-pr).
• lib.sh and read.sh are byte-identical to #1850. read.sh writes no comments.txt at all.
• dimensions.md has six lenses (L1-L6).
• SKILL.md is 280 lines.
• The recommendation table (SKILL.md:25-39) adds four NOT-APPLICABLE rows the body omits: already in tree, merged as, superseded by, and off path. It also adds the -- does not apply at <commit> qualifier. .claude/skills/analyze-upstream-pr/SKILL.md:89
  Impact: The 'Observable effect' and 'Breaking changes' sections claim that check-prior-art's per-PR comments.txt changes shape, which this PR does not do. The 'Tests' section claims 14 tests that the PR does not add. A reviewer or the release notes would describe scripts, artifacts and a refactor that do not ship, and would miss the recommendation rows that actually decide the outcome.
  Action: Rewrite the body for the head:
• Name the three files.
• Describe collection as read.sh plus checks.json and inline.jsonl.
• Say the PR adds no scripts or tests, and why (only markdown procedure; scripts are #1850's).
• Give the six lenses.
• Give the ten-row recommendation table and its qualifiers.
• Drop the lib.sh, comments.txt and fetch_upstream.sh paragraphs.
• Name #1850 explicitly as the dependency.

Checked: I read the following:

• At head: the full analyze-upstream-pr/SKILL.md and references/dimensions.md, and the AGENTS.md diff.
• check-prior-art read.sh, lib.sh, SKILL.md (Steps 4-7 and the verdict table) and the gotchas G1-G8 headings.
• inclusion.py at head against main's kernelforge.llm.git git/git_bytes signatures.
• The live PR body via gh, plus body.txt, files.txt, numstat.txt, commits.txt, comments.txt (earlier review cards) and ci.txt (all green; label-gated E2E skipped).

I ran the following:

• git merge-base --is-ancestor origin/pr-1850 origin/pr-1851: stacked.
• git diff --stat origin/pr-1850 origin/pr-1851: 3 files.
• git merge-tree origin/main origin/pr-1851: clean.
• The inclusion probe on an archive of the merged tree: exit 3, works.
• The Step 6 binary-exclusion awk plus git apply --check in a scratch repo: the binary stanza fails without $BIN and passes with it.

Not run: pytest (Windows) and the shell procedure end to end against a real upstream PR.

Base b7004d1, head f8bc23d, main 1cdc6ff. | Base: b7004d1 | Head: f8bc23d

[okorzh-amd]

@chaojhou Thanks for the review. The description is now rewritten against 6cc6611, and it covers each item in your Action list:

• It names the three files and says the PR adds no script or test, because it is Markdown only. The scripts it runs belong to feat(skills): add check-prior-art, a contributor skill that finds a planned change upstream #1850 and feat(pr_knowledge): probe whether an upstream PR is in a local git tree #1847.
• It describes collection as read.sh plus checks.json and inline.jsonl, with hunks.txt only when GitHub refuses the diff (SKILL.md:89-94).
• It lists the six lenses L1-L6 and all ten recommendation rows (SKILL.md:25-39), with their qualifiers: via <ref>, via <patch>, , relanded in <ref>, -- inclusion unchecked, -- conflicts with <patch> and -- does not apply at <commit>.
• The lib.sh, comments.txt and fetch_upstream.sh paragraphs are gone, and "Breaking changes" now says check-prior-art's files and their outputs are unchanged.
• feat(skills): add check-prior-art, a contributor skill that finds a planned change upstream #1850 is named as the dependency, and feat(pr_knowledge): probe whether an upstream PR is in a local git tree #1847 beneath it.
  I rebased onto main 7ac8c12 with no conflicts and no change to the skill's files. The rebase's only substantive effect is that the kernel-names refactor that feat(pr_knowledge): probe whether an upstream PR is in a local git tree #1847 stacked on landed as refactor(kb_store): move derive_kernel_names into kb_store.identity.kernel_names #2028, so this diff no longer carries it: 40 commits, 17 files, +1967/-20, 253 production Python lines, all from feat(pr_knowledge): probe whether an upstream PR is in a local git tree #1847. I re-ran the gates and tests at 6cc6611 and the live vLLM checks at 88bd0be; 6cc6611 only changes how Step 6 reads a diff that fails after a local patch, so a patch that already carries the PR reads as in tree rather than as a conflict. The counts in the body come from those runs. I agree with every point in the review.

Resolved at the current head; see the follow-up review comment.

[chaojhou]

PR #1851 -- feat(skills): add analyze-upstream-pr to judge an upstream PR for an AMD deployment

What it does: adds the analyze-upstream-pr skill as three Markdown files: SKILL.md, references/dimensions.md and one AGENTS.md row. The skill collects an upstream PR through the check-prior-art read.sh plus gh pr view / gh api, then judges it for an AMD deployment. It adds no script and no test, and changes none of the check-prior-art files. The branch carries #1847 and #1850 and merges after them, as the description states.

Blocking issues: none

The earlier blocker ([desync-body-describes-removed-design] at f8bc23d: the description described fetch_upstream.sh, a 14-test file, measurement.md and the lib.sh lift) is resolved. The description now lists the three Markdown files the PR actually adds.

Checked: the PR's own three files at 6cc6611. Also the check-prior-art scripts and test it carries from #1850, with the same CI-safety result: they call only gh, jq, awk, sort and sleep, write under the work directory and a trapped temp directory, and the tests use a stub gh | Ran: git merge-tree --write-tree origin/main 6cc661136 (clean); CI approved and running at this head | Head: 6cc6611

LGTM

[chaojhou]

Approving per the review comment above (resolved at 6cc6611; CI green; merged after #1847 and #1850).