diff --git a/.agents/skills b/.agents/skills new file mode 120000 index 000000000..454b8427c --- /dev/null +++ b/.agents/skills @@ -0,0 +1 @@ +../.claude/skills \ No newline at end of file diff --git a/.claude.md b/.claude.md new file mode 100644 index 000000000..91caf61b2 --- /dev/null +++ b/.claude.md @@ -0,0 +1,14 @@ +# Global Regex and ReDoS Policy + +Whenever you are writing, modifying, or reviewing Regular Expressions (Regex) in this codebase, you **MUST** adhere to the project's structural-extraction accuracy and ReDoS immunity standards. + +1. **ReDoS Immunity & Boundary Correctness**: You must read and follow the 12 engine rules defined in `gitgalaxy/standards/how_to_add_a_language.md`. +2. **Hardening Process**: You must follow the 5-stage pipeline checklist and avoid the recurring bug classes outlined in `tests/extraction/how_to_harden_extraction.md`. +3. **Use the Tooling**: Always verify regex empirically against the real compiled regex using `tests/extraction/tools/verify_candidates.py` and run the scaling checks. Do not guess whether a payload matches or scales. +4. **Skills**: If you are deepening or fixing a language's structural-extraction accuracy (e.g. `func_start`, `args`), you must activate and follow the `harden-language-extraction` skill. + +# Core Engine Modification CI Checklist + +When you are preparing to push a fix or open a PR that touches GitGalaxy's core parsing logic (`language_standards.py`, `detector.py`, `prism.py`), you **MUST** ensure the CI validation gauntlet is handled. + +1. **Invoke the ci-push-checklist skill**: You must activate and follow the `.claude/skills/ci-push-checklist/SKILL.md` before pushing to ensure all Golden Masters, Tri-Comparison, and Tree-Sitter baselines are accurately regenerated and validated. diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 000000000..efcc4e4f2 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,11 @@ +### Description + + +### Core Engine Modification Checklist +If your PR changes the core parsing engine (`language_standards.py`, `detector.py`, `prism.py`), you **MUST** complete the following validation gauntlet before merging: + +- [ ] **Golden Master Verification**: Ran `crucible_check.py` to verify diffs, and ran `crucible_check.py --update --yes` if the baseline changed due to intentional parsing improvements. +- [ ] **Tri-Comparison Audit**: Handled by CI automatically, but you should run `python tests/tools/tri_comparison_chart.py --all --ci` locally first. If you intentionally improved precision, regenerate the baseline: `python tests/tools/tri_comparison_chart.py --regenerate --languages `. +- [ ] **Tree-Sitter Accuracy**: Ran `python tests/tools/tree_sitter_accuracy_audit.py --ci --all`. If ground truth drifted for valid reasons, regenerated the baseline with `python tests/tools/tree_sitter_accuracy_audit.py --regenerate --lang `. + +> **Note for AI Agents**: If you are an AI agent generating this PR, you MUST invoke the `ci-push-checklist` skill to ensure these steps are completed properly. diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 000000000..3aefc4882 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,14 @@ +# Global Regex and ReDoS Policy + +Whenever you are writing, modifying, or reviewing Regular Expressions (Regex) in this codebase, you **MUST** adhere to the project's structural-extraction accuracy and ReDoS immunity standards. + +1. **ReDoS Immunity & Boundary Correctness**: You must read and follow the 12 engine rules defined in `gitgalaxy/standards/how_to_add_a_language.md`. +2. **Hardening Process**: You must follow the 5-stage pipeline checklist and avoid the recurring bug classes outlined in `tests/extraction/how_to_harden_extraction.md`. +3. **Use the Tooling**: Always verify regex empirically against the real compiled regex using `tests/extraction/tools/verify_candidates.py` and run the scaling checks. Do not guess whether a payload matches or scales. +4. **Skills**: If you are deepening or fixing a language's structural-extraction accuracy (e.g. `func_start`, `args`), you must activate and follow the `harden-language-extraction` skill. + +# Core Engine Modification CI Checklist + +When you are preparing to push a fix or open a PR that touches GitGalaxy's core parsing logic (`language_standards.py`, `detector.py`, `prism.py`), you **MUST** ensure the CI validation gauntlet is handled. + +1. **Invoke the ci-push-checklist skill**: You must activate and follow the `.agents/skills/ci-push-checklist/SKILL.md` before pushing to ensure all Golden Masters, Tri-Comparison, and Tree-Sitter baselines are accurately regenerated and validated. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f12963091..40c6a5fa9 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -59,17 +59,26 @@ To ensure your contribution integrates smoothly into the Zero-Trust ecosystem: --- -## 🔒 Updating the Golden Crucible Baseline +## 🔒 CI Pipeline & Baselines -`tests/golden_master_audit.json` and `tests/golden_master_zero_dep_audit.json` are the accepted-good snapshots that every PR's output is diffed against (see the `crucible-audit` check). A failing diff means GitGalaxy's output changed -- that's either a bug you should fix, or an intentional improvement whose new baseline needs to be deliberately re-blessed. +When you modify GitGalaxy's core engine, several CI workflows will rigorously test your changes against established baselines. If your changes intentionally improve parsing precision, you must regenerate the corresponding baselines. -**Never** hand-copy fresh output over these files. Always use: +1. **Golden Crucible Baselines (`tests/golden_master_audit.json`)** + This validates exact extraction output. + - Run `python tests/tools/crucible_check.py` to view structural drift. + - To re-bless the new state: `python tests/tools/crucible_check.py --update --yes` -``` -python tests/tools/update_golden_master.py -``` +2. **Tri-Comparison Ledger (`docs/self_scan/tri_comparison_ledger.json`)** + This compares GitGalaxy precision against ctags and tree-sitter. + - Run `python tests/tools/tri_comparison_chart.py --all --ci` to test. + - If you improved precision, lock it in: `python tests/tools/tri_comparison_chart.py --regenerate --languages ` + +3. **Tree-Sitter Accuracy (`docs/self_scan/tree_sitter_accuracy_history.csv`)** + This audits AST accuracy against tree-sitter ground truth. + - Run `python tests/tools/tree_sitter_accuracy_audit.py --ci --all`. + - If your regex fix legitimately drops false positives causing ground truth drift, regenerate the baseline: `python tests/tools/tree_sitter_accuracy_audit.py --regenerate --lang ` -It shows you exactly what's about to change before writing anything, and requires explicit confirmation. If your PR touches either fixture, **explain why in the PR description** (e.g. "improved the Rust parser, now correctly detects async trait bounds") -- a CI check flags any PR that modifies these files so it's never invisible in a large diff. +If your PR touches any baseline fixtures, **explain why in the PR description** (e.g. "improved the Rust parser, now correctly detects async trait bounds"). A CI check flags any PR that modifies these files so it's never invisible in a large diff. ---