| name | code-review |
| description | Review numan-registry pull requests against REVIEW.md severity labels, trust invariants, intake rules, and CI gates. Use for Copilot code review, PR review requests, and any pull-request or diff review in this repository. |
numan-registry code review
When reviewing a pull request or diff in this repository, follow the canonical
guide at REVIEW.md. Prefer that file over paraphrased
memory. AGENTS.md remains the source for toolchain and
CI commands.
How to review
- Read the PR description and changed files; stay within the stated scope.
- Apply severity labels from
REVIEW.md (P0–P3). Lead with P0/P1 findings.
- Flag any violation of the trust and intake invariants listed below.
- For catalog or index changes, verify digests came from download, parser
parity, and Stage 1 evidence expectations for activatable packages.
- Leave actionable comments with concrete fixes. Do not approve or request
changes as a human gate; report findings only.
CI gates (must pass)
Use python (matches CI / Windows). From a clean checkout the index signature is an
intentional PLACEHOLDER, so unsigned validation is the local gate; full
signature verify requires a staging ephemeral sign or production deploy (do not
overwrite the committed placeholder).
python scripts/scan_for_secrets.pypython scripts/preflight.pypython scripts/validate.py --index registry/index.json --schema schemas/index-v1.json --skip-signature (add --skip-artifacts when offline)- Signature path: ephemeral sign via
scripts/ci-sign.py (as in staging), then python scripts/validate.py --index registry/index.json --sig PATH/TO/temp.sig --pub PATH/TO/temp.pub --schema schemas/index-v1.json
cargo run --locked --manifest-path tools/numan-parser-check/Cargo.toml -- registry/index.json- For CI-built plugins (sibling checkout):
python scripts/lint-manifest-index.py --index registry/index.json --manifest numan-plugins/manifest.json
- Script unit tests:
python -m unittest discover -s scripts -p "test_*.py" -v (see .github/workflows/repo-safety.yml)
Severity labels
| Label | Meaning |
|---|
| P0 | Trust bypass, private-key material, unsigned-production fallback, hand-typed artifact hashes, silent index corruption |
| P1 | Incorrect intake/validation on happy path, missing lifecycle evidence for activatable packages, schema/parser mismatch |
| P2 | Doc/intake-state drift, misleading checklists, maintainability of scripts |
| P3 | Style, naming, non-blocking suggestions |
Architecture invariants (flag violations)
- No private keys in tree — never commit
*.key, *.pem, or private-key material; secret scan must stay green.
- Placeholder signature is intentional — committed
registry/index.json.sig may be PLACEHOLDER; production signing happens only in the protected deployment workflow. Do not treat the placeholder as an unsigned-production fallback or replace it with a local "real" signature in source.
- Hashes from download only — artifact digests come from
scripts/add-package.py (download + compute). Never hand-type SHA256 values into the index or specs.
- Source builds stay out — reject
kind: source and unsupported archive suffixes at intake; binary artifacts only for official catalog promotion.
- Provenance preserved — CI-built plugin intake must keep
source.rev (immutable upstream commit) and human-facing tag provenance from the plugins handoff.
- Stage 1 evidence before promote — activatable packages need lifecycle-prove evidence (or an explicit deferral with reason). See
docs/lifecycle-prove.md.
- Human review before production sign — protected
production.yml + reviewer approval; scripts must not auto-publish to the trust root.
- Parser parity — index changes must parse with Numan's production Rust registry parser (
tools/numan-parser-check).
Review checklist
Intake-specific notes
- Follow the PR template checklist for new or changed packages.
- Staging may sign with ephemeral keys; that path must not overwrite committed production placeholder material.
scripts/lifecycle-prove.py is a maintainer Stage 1 gate, not a substitute for repo-safety CI.
