Code Review Guidelines

Relevant source files

The following files were used as context for generating this wiki page:

• REVIEW.md
• AGENTS.md
• README.md
• SECURITY.md
• scripts/test_workflow_safety.py
• scripts/validate_candidate.py

Code review within the Numan Registry project is a critical gatekeeping process designed to maintain the integrity of the signed registry index. Because this is a data-only repository, the primary focus of reviews is ensuring the security of the trust root, the accuracy of artifact digests, and the structural validity of the index.json file. Reviews are conducted by both human contributors and automated agents to enforce architecture invariants and prevent the accidental inclusion of sensitive materials.

Sources: AGENTS.md:4-7, README.md:3-8, REVIEW.md:3-5

Review Severity Labels

The project utilizes a tiered severity system to categorize issues found during pull request (PR) reviews. These labels allow reviewers to communicate the impact of a finding clearly, ranging from critical trust bypasses to minor stylistic suggestions.

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.

Sources: REVIEW.md:27-33

Mandatory CI Gates

Every pull request must pass a specific set of Continuous Integration (CI) checks. These scripts validate various aspects of the repository, from secret scanning to production parser parity.

Automated Validation Flow

The following diagram illustrates the sequence of automated checks that a PR must clear before being considered for a human review.

The CI process ensures that script logic is sound and that the index remains compatible with Numan's production Rust registry parser.

Sources: AGENTS.md:14-25, REVIEW.md:7-19

Key Validation Commands

• python scripts/scan_for_secrets.py: Scans git-tracked files for private-key material.
• python scripts/preflight.py: Key and workflow consistency checks (network-less).
• python scripts/validate.py --index registry/index.json --schema schemas/index-v1.json: Validates schema, canonical JSON, and signatures.
• cargo run --locked --manifest-path tools/numan-parser-check/Cargo.toml: Ensures index changes parse with the production Rust registry parser.

Sources: AGENTS.md:14-25, REVIEW.md:10-17

Architecture Invariants

Reviewers must flag any violation of these core architectural rules. These invariants are non-negotiable and designed to prevent trust degradation or security breaches.

1. No Private Keys in Tree: Never commit *.key, *.pem, or private-key material. The secret scanner must remain green.
2. Intentional Placeholder Signature: The committed registry/index.json.sig is often a PLACEHOLDER. Production signing occurs only in protected workflows; do not replace the placeholder with a "real" local signature in the source tree.
3. Hashes from Download Only: Artifact SHA256 digests must be generated via scripts/add-package.py. Hand-typed hashes are strictly prohibited (P0).
4. Binary Artifacts Only: Reject kind: source and unsupported archive suffixes at intake. Only binary artifacts are permitted for catalog promotion.
5. Provenance Preservation: Intake for CI-built plugins must retain the source.rev (immutable upstream commit) and original tag provenance.
6. Stage 1 Evidence: Activatable packages (plugins and certain modules) require successful lifecycle-prove evidence recorded in the verified_with field before promotion.
7. Human Approval for Production: The production.yml workflow requires manual approval; scripts must never auto-publish to the trust root.

Sources: REVIEW.md:35-50, SECURITY.md:52-60, scripts/validate_candidate.py:65-71

Review Checklist for Contributors

Reviewers and PR authors should use the following checklist to ensure all project requirements are met:

• Secrets: No secrets or private-key paths added (even via force-adds).
• Validation: Index/schema changes validated; Numan parser check passed.
• Artifacts: URLs and digests produced by add-package.py, not edited by hand.
• Compatibility: For numan-plugins, nu_version agrees with manifest.json.
• Documentation: docs/intake-state.json and intake-candidates.md remain consistent with catalog changes.
• Scope: Changes match the PR description; no unrelated catalog churn in tooling PRs.

Sources: REVIEW.md:52-60, README.md:104-118

Workflow Safety Requirements

The project enforces strict safety rules for its GitHub Actions workflows to prevent supply chain attacks and unauthorized access to production secrets.

• Action Pinning: Every GitHub Action must be pinned to a 40-character commit SHA, not a tag or branch.
• Permission Hardening: Workflows must default to permissions: contents: read.
• Secret Isolation: Production secrets (like NUMAN_REGISTRY_PRIVATE_KEY) must only be accessible within the protected sign-and-publish job in production.yml, and only after successful validation.

Sources: scripts/test_workflow_safety.py:35-62, README.md:92-100

Conclusion

The Numan Registry code review process prioritizes security and data integrity above all else. By strictly enforcing binary-only artifacts, automated hash generation, and commit-level action pinning, the project ensures that the registry remains a trustworthy source for Nushell package management.

Sources: REVIEW.md:3-5, SECURITY.md:52-60