refactor(skills): collapse redundant Cairo modules and sync upstream optimization

[omarespejel]

Summary

This PR collapses redundant Cairo skill modules and syncs optimization content with the latest upstream source.

Changes

• Remove redundant openzeppelin-cairo/ skill module.
• Expand cairo-contract-authoring:
  • Add references/language.md (language fundamentals from PR #295 context).
  • Add component wiring checklist, cross-contract dispatcher guidance, and OZ hardening checklist in references/legacy-full.md.
  • Update SKILL metadata/router/workflow references.
• Update cairo-optimization with latest feltroidprime content:
  • Replace references/legacy-full.md with rules 1-12 + BoundedInt updates.
  • Add references/profiling.md from benchmarking-cairo.
  • Add scripts: scripts/profile.py, scripts/bounded_int_calc.py.
  • Add upstream metadata fields: upstream, upstream_commit, sync_date, upstream_paths, permission_ref.
• Add attribution/governance docs:
  • New THIRD_PARTY.md.
  • Update README.md and CONTRIBUTING.md with third-party attribution/sync rules.
• Update root routing docs:
  • SKILL.md, README.md, llms.txt.

Validation

• .venv/bin/python scripts/quality/validate_skills.py
  • Result: OK: validated 8 SKILL.md files

Note

This is the default-branch-targeted version of the earlier branch-targeted PR so review tooling can run against main.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: fbe044ac-f904-43f7-8f39-81be3d1886b3

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch codex/cairo-skill-collapse-main

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[greptile-apps]

Greptile Summary

This PR consolidates the openzeppelin-cairo skill module into cairo-contract-authoring, expands the cairo-optimization module with upstream feltroidprime content (Rule 12, profiling reference, and two new Python scripts), adds Cairo language fundamentals in a new language.md reference, and introduces a THIRD_PARTY.md governance file for external content attribution.

Key findings:

• Logic regression in Rule 11 example (cairo-optimization/references/legacy-full.md): the "GOOD" code example was simplified from let (hash, _, _) = hades_permutation(x, y, 2) to let h = hades_permutation(x, y, 2), dropping the required tuple destructuring. hades_permutation returns (felt252, felt252, felt252), so h now holds a 3-tuple rather than a felt252; code copied from this example will fail to compile when the hash is used downstream.
• No input-range validation in bounded_int_calc.py: the calc_* functions do not assert lo ≤ hi for either operand, so inverted inputs silently produce inverted BoundedInt bounds that the Sierra specialiser rejects with a cryptic error rather than a clear tool-level message.
• Loose package resolution in profile.py: _find_package_dir falls back to the repo root when packages/<package>/Scarb.toml is absent, without verifying that the top-level Scarb.toml actually declares the requested package name, potentially profiling the wrong package silently.
• The openzeppelin-cairo removal is internally consistent — all routing references (SKILL.md, README.md, llms.txt) are updated and OZ content has been re-homed in cairo-contract-authoring.
• The new language.md reference and the extended legacy-full.md content (component wiring checklist, dispatcher guidance, OZ hardening checks) are accurate and well-structured.

Confidence Score: 3/5

• Mostly safe to merge after fixing the hades_permutation destructuring regression and the two Python script validation gaps.
• The majority of changes are documentation and well-structured reference content. However, the Rule 11 GOOD example now produces a tuple instead of a felt252 — a correctness regression in a high-visibility optimization pattern that users are likely to copy verbatim. The two Python utility scripts also have logic gaps (missing range validation, unverified package fallback) that could silently produce wrong output. These issues lower confidence below a clean merge.
• cairo-optimization/references/legacy-full.md (hades_permutation example), cairo-optimization/scripts/bounded_int_calc.py (input range validation), cairo-optimization/scripts/profile.py (package name verification).

Important Files Changed

Filename	Overview
cairo-optimization/references/legacy-full.md	Adds Rule 12 (felt252→BoundedInt via u128 decomposition) and attribution header; introduces a correctness regression in the Rule 11 GOOD example by dropping the required tuple destructuring of hades_permutation's return value.
cairo-optimization/scripts/bounded_int_calc.py	New CLI tool to compute Cairo BoundedInt trait impl bounds; functional for well-formed inputs but lacks validation that lo ≤ hi for each operand range, allowing silently inverted bounds to be generated.
cairo-optimization/scripts/profile.py	New deterministic Cairo profiling pipeline (snforge + scarb modes); package resolution fallback does not verify the package name against the top-level Scarb.toml, which can silently profile the wrong package.
cairo-contract-authoring/references/language.md	New Cairo language fundamentals reference; code examples are accurate for Cairo 2.x (linear types, snapshots, refs, collections, error handling, modules).
cairo-contract-authoring/references/legacy-full.md	Adds component wiring checklist, cross-contract dispatcher guidance, and OZ hardening checklist; relative path fixes are correct; content is accurate.
cairo-optimization/references/profiling.md	New profiling reference covering CLI usage, exit codes, pitfalls, and tool installation; installation instructions use curl-pipe-to-sh patterns which is standard for these tools but worth acknowledging.
THIRD_PARTY.md	New third-party attribution registry; correctly documents feltroidprime as upstream author of cairo-optimization with commit hash and permission reference.
openzeppelin-cairo/SKILL.md	Deleted — OZ Cairo module collapsed into cairo-contract-authoring; all routing references (SKILL.md, README.md, llms.txt) have been updated consistently.

Sequence Diagram

sequenceDiagram
    participant User
    participant profile.py
    participant snforge/scarb
    participant cairo-profiler
    participant pprof

    User->>profile.py: python3 profile.py profile --mode snforge/scarb ...
    profile.py->>profile.py: _find_repo_root() + _find_package_dir()
    profile.py->>snforge/scarb: snforge test --save-trace-data OR scarb execute --save-profiler-trace-data
    snforge/scarb-->>profile.py: exit code (fail → exit 2)
    profile.py->>profile.py: _find_trace_snforge() / _find_trace_scarb()
    Note over profile.py: exit 3 if trace not found
    profile.py->>cairo-profiler: cairo-profiler build-profile <trace.json> --show-libfuncs
    cairo-profiler-->>profile.py: <name>.pb.gz (fail → exit 4)
    profile.py->>cairo-profiler: cairo-profiler view <name>.pb.gz --sample <metric> --limit 20
    cairo-profiler-->>User: top-20 functions printed
    profile.py->>pprof: pprof -png -sample_index=<metric> -output <name>.png <name>.pb.gz
    pprof-->>profile.py: <name>.png (fail → exit 5)
    profile.py-->>User: Profile path + PNG path summary (exit 0)

Loading

Comments Outside Diff (3)

1. cairo-optimization/references/legacy-full.md, line 688-689 (link)

   Rule 11 GOOD example drops required tuple destructuring

   hades_permutation returns (felt252, felt252, felt252), not a bare felt252. The previous code correctly destructured the result:

   let (hash, _, _) = hades_permutation(x, y, 2);

   The new code let h = hades_permutation(x, y, 2) binds the full 3-tuple to h. Any downstream code that passes h where a felt252 is expected will fail to compile. This is a regression in a high-visibility example that users are likely to copy directly.

2. cairo-optimization/scripts/bounded_int_calc.py, line 1068-1079 (link)

   No validation that input ranges are well-ordered (lo ≤ hi)

   None of the calc_* functions check that a_lo ≤ a_hi or b_lo ≤ b_hi. Inverted input ranges silently propagate to generated Cairo code with inverted BoundedInt bounds (e.g., BoundedInt<50, 0>), which the Sierra specialiser will reject with a cryptic error rather than a clear user message from this tool.

   The most dangerous case is calc_sub: if a_lo > a_hi, the formula result_lo = a_lo - b_hi and result_hi = a_hi - b_lo can produce a result_lo > result_hi bound without any warning.

   Consider adding an early guard in each function, for example:

   def calc_add(a_lo: int, a_hi: int, b_lo: int, b_hi: int) -> tuple[int, int]:
       if a_lo > a_hi:
           print(f"ERROR: First operand range is inverted: [{a_lo}, {a_hi}]", file=sys.stderr)
           sys.exit(1)
       if b_lo > b_hi:
           print(f"ERROR: Second operand range is inverted: [{b_lo}, {b_hi}]", file=sys.stderr)
           sys.exit(1)
       ...

   The same guard should be applied to calc_sub, calc_mul, and calc_div.

3. cairo-optimization/scripts/profile.py, line 1372-1381 (link)

   Fallback to repo root does not verify the package name

   When packages/<package>/Scarb.toml is not found, the function falls back to repo_root if any top-level Scarb.toml exists — without checking that the package declared in that file actually matches args.package. This means a user running --package falcon against a repo whose root is a package named my_project will silently profile the wrong package instead of getting a clear error.

   Consider parsing the Scarb.toml to confirm the [package] name field, or at minimum pass --package <name> to the snforge/scarb invocation so the tool itself enforces the match.

_{Last reviewed commit: ae1b91d}

[omarespejel]

Addressed all current bot findings in follow-up commit cbf34b7:

• Restored Rule 11 detail section in cairo-optimization/references/legacy-full.md and numbered Rule 12 heading for table/section consistency.
• Fixed metadata date mismatch:
  • cairo-optimization/SKILL.md: sync_date + permission_ref -> 2026-03-08
  • THIRD_PARTY.md: permission reference aligned to 2026-03-08
• Simplified dead conditional in cairo-optimization/scripts/bounded_int_calc.py (format_bound).
• Moved _find_repo_root() above main() in cairo-optimization/scripts/profile.py to match helper ordering.
• Removed unsupported tools key in .coderabbit.yaml to clear config-schema warning.

Validation rerun:

• .venv/bin/python scripts/quality/validate_skills.py -> OK: validated 8 SKILL.md files
• .venv/bin/python -m py_compile cairo-optimization/scripts/profile.py cairo-optimization/scripts/bounded_int_calc.py