107 lines
3.6 KiB
Markdown
107 lines
3.6 KiB
Markdown
# Contributing a New AI-ism — internals
|
|
|
|
The routed procedure lives in `references/commands/contribute.md`. This
|
|
exhaustive companion covers every command flag, the redaction discipline, the
|
|
row-diff verification, and the non-maintainer fork path. Keep it offline until
|
|
the user has approved both publication and the final PR body.
|
|
|
|
## 1. Precheck
|
|
|
|
```bash
|
|
python3 scripts/contribute.py precheck /absolute/path/to/snippet.txt
|
|
```
|
|
|
|
If the snippet is already flagged, the command exits 3 and prints the covering
|
|
patterns/categories. Stop there. Add a REC example instead of a new
|
|
false-negative example.
|
|
|
|
## 2. User Confirmation Gate #1
|
|
|
|
Show the exact snippet to the user and ask whether it may be published in a
|
|
public repo. Offer redaction hints from:
|
|
|
|
```bash
|
|
python3 scripts/extract_constraints.py < /absolute/path/to/snippet.txt
|
|
```
|
|
|
|
Redact names, numbers, or private details only with explicit approval. The tell
|
|
must remain byte-for-byte intact.
|
|
|
|
## 3. Scaffold
|
|
|
|
```bash
|
|
python3 scripts/contribute.py scaffold \
|
|
--snippet /absolute/path/to/snippet.txt \
|
|
--tell "exact substring" \
|
|
--category significance_inflation \
|
|
--pattern-name exact-substring-slug \
|
|
--redact "Alice=NAME"
|
|
```
|
|
|
|
The bundle is written under `.unslop/contrib/<slug>/`. Do not publish it. It is
|
|
working material for the agent and reviewer.
|
|
|
|
## 4. Implement the Pattern
|
|
|
|
Follow `references/maintenance.md` in this order:
|
|
|
|
1. Copy `.unslop/contrib/<slug>/row_fn.json` into
|
|
`evals/fixtures/contracts/scanner-examples.json`.
|
|
2. Renumber the copied example from the live maxima in that table; do not keep
|
|
the `CONTRIB-FN-*` bundle id in the committed contract. Set `exact_total` to
|
|
the resulting `examples` array length.
|
|
3. Add the literal-use FP example for the category, and add a REC example if an existing
|
|
word is being gated behind collocations.
|
|
4. Run the scanner contract before implementation and confirm the FN example is
|
|
red while the FP and any REC examples encode the intended boundary.
|
|
5. Update the scanner and `references/taboo-phrases.md`.
|
|
6. Re-run `python3 scripts/contribute.py verify --bundle .unslop/contrib/<slug>`.
|
|
7. Before treating the example as ready, diff it against
|
|
`.unslop/contrib/<slug>/row_fn.json` and verify that only expected suite
|
|
fields changed, such as the id, category grouping, or row ordering; the
|
|
specimen stdin and assertion intent must still match because redaction or
|
|
implementation work does not authorize a silent change to the reported tell.
|
|
|
|
## 5. Verify
|
|
|
|
```bash
|
|
python3 scripts/contribute.py verify --bundle .unslop/contrib/<slug>
|
|
```
|
|
|
|
Verify refuses reports with TODO markers, checks specimen fidelity, captures the
|
|
red-to-green transition for the FN row, and records offline gate tails.
|
|
|
|
## 6. Run the Full Gate Battery
|
|
|
|
```bash
|
|
python3 evals/check.py --full
|
|
```
|
|
|
|
## 7. Render the Report
|
|
|
|
```bash
|
|
python3 scripts/contribute.py report --bundle .unslop/contrib/<slug> > /tmp/pr-body.md
|
|
```
|
|
|
|
## 8. User Confirmation Gate #2
|
|
|
|
Show the final PR body to the user. Only after the user approves publication:
|
|
|
|
```bash
|
|
git switch -c add-<slug>
|
|
git add evals/fixtures/contracts/scanner-examples.json scripts/banned_phrase_scan.py references/taboo-phrases.md
|
|
git commit -m "Add <slug> AI-ism pattern"
|
|
gh pr create --title "Add <category> pattern: <tell>" --body-file /tmp/pr-body.md
|
|
```
|
|
|
|
For non-maintainers:
|
|
|
|
```bash
|
|
gh repo fork --remote
|
|
git push --set-upstream <fork-remote> add-<slug>
|
|
gh pr create --repo <upstream-owner>/unslop --head <fork-owner>:add-<slug> --body-file /tmp/pr-body.md
|
|
```
|
|
|
|
The `gh` commands are for the host agent after approval. Scripts and evals must
|
|
never call `gh` or any network command.
|