Skip to content

feat(rules): expand kind taxonomy to 9 values + backfill CLI#77

Open
csacsi wants to merge 12 commits into
mainfrom
feature/newKinds
Open

feat(rules): expand kind taxonomy to 9 values + backfill CLI#77
csacsi wants to merge 12 commits into
mainfrom
feature/newKinds

Conversation

@csacsi
Copy link
Copy Markdown
Collaborator

@csacsi csacsi commented May 23, 2026

Summary

  • Expand rule kind taxonomy from 6 → 9 values: tradeoff, layering, infrastructure carved out as their own kinds (previously lumped under semantic_pattern / coding_practice).
  • New archie/standalone/rule_kinds.py — single source of truth (KINDS, KIND_DESCRIPTIONS, is_valid_kind, classify_kind).
  • New backfill_kinds.py CLI — heuristic classifier populates missing/invalid `kind` on legacy `.archie/rules.json` (90% of real-world rules were missing it).
  • Updated both rule-producing prompts (`/archie-deep-scan` step-6 + `/archie-scan`) to the new 9-kind taxonomy.
  • `migrate_blueprint_rules.py`: `infrastructure_rules` → new `infrastructure` kind (was `coding_practice`).

Motivation

Survey of 642 rules across 7 real projects showed:

  • 579 of 642 had no `kind` field at all → viewer rendered them as "unknown"
  • The old 6-kind taxonomy lumped `tradeoff` into `semantic_pattern` (despite different `severity_class`) and `layering` was the largest natural group (106 rules) buried under generic catch-alls.

The new 9-kind taxonomy reflects what id-prefixes the AI was already choosing organically (`layer-`, `tradeoff-`, `chain-`, `pattern-`, etc.).

Validation

  • 597 tests pass (43 new across `test_rule_kinds.py`, `test_backfill_kinds.py`, `test_migrate_blueprint_rules.py`)
  • `scripts/verify_sync.py` clean (32 scripts, 7 commands in sync)
  • Dry-run backfill across 7 real projects — files unchanged, distributions reasonable for projects with semantic id prefixes (8–23% `coding_practice`); projects with generic ID schemes (e.g. `R01`–`R35`) fall through to `coding_practice` as designed — those get clean kinds on next `/archie-scan`.

Known limitations (by design)

  • Backfill is a safety net for legacy files. The authoritative path to good kinds is re-running `/archie-scan` or `/archie-deep-scan` with the new prompt.
  • Two follow-ups tracked from final review (non-blocking):
    • Unify `_atomic_write_json` between `backfill_kinds.py` and `migrate_blueprint_rules.py` (trailing-newline drift)
    • Add end-to-end integration test bridging migrate → backfill

Plan

`docs/superpowers/plans/2026-05-23-rule-kinds-taxonomy.md` (8 tasks, all done via subagent-driven TDD).

Test plan

  • CI green
  • `python -m pytest tests/ -v` locally
  • `python3 scripts/verify_sync.py`
  • Spot-check: `python3 archie/standalone/backfill_kinds.py --dry-run` on a real project

🤖 Generated with Claude Code

csacsi and others added 12 commits May 23, 2026 22:08
Introduces rule_kinds.py with KINDS tuple, KIND_DESCRIPTIONS dict,
and is_valid_kind() — single-sourced taxonomy for the rule `kind` field,
importable by all later tasks in the rule-kinds-taxonomy plan.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
…ion_signals

Mirror the truthiness guards already applied to forbidden_imports and
allowed_dirs: an empty string pattern_name and an empty violation_signals
list now fall through to coding_practice instead of firing the branch.
Adds 6 tests (36 total) covering both fix directions and infra field paths.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
…n failure

- main() now catches json.JSONDecodeError and prints a friendly message instead of a traceback
- _atomic_write_json appends \\n (POSIX trailing newline) and unlinks the .tmp file on any failure
- Two new tests cover the JSONDecodeError path and the trailing-newline contract (9 passed)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Add required `kind` field to the scan rule schema and output template,
with the full 9-value enum and a reference to Step-6 for definitions.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
…npm-package/assets

Copies two new Python scripts (rule_kinds.py, backfill_kinds.py) and
updated canonical files (migrate_blueprint_rules.py, step-6-rule-synthesis.md,
archie-scan.md) to npm-package/assets/, and registers the two new scripts in
the archie.mjs install-time copy list.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@vercel
Copy link
Copy Markdown

vercel Bot commented May 23, 2026

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated (UTC)
archie Ready Ready Preview, Comment May 23, 2026 9:03pm

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant