rule-analyzer

What It Does

Turns prose rules into a reviewable contract. For every bullet under docs/instructions/rules/** it:

• Embeds an opaque, stable <!-- @rule RL-<hash> --> marker (idempotent — reruns cause no churn).
• Classifies verifiability:
  • deterministic — a script can decide pass/fail (e.g. "no debugger statements").
  • heuristic — a script can flag candidates; humans/LLM adjudicate (e.g. "business logic belongs in hooks").
  • unverifiable — with a reason (e.g. "coherence is judgment-dependent").
• Records pre-existing enforcers in enforced_by so no duplicate script is generated.
• Detects contradictory rules and surfaces them via the Decision Pause Contract before any script work.

It writes a draft docs/instructions/rules/rule-script-map.yml. The user reviews this map before generate rule scripts.

Use This When

• A user prompt matches the priority-225 router rule analyze rules.
• After adding or editing several rules and you need to re-classify the rule set.
• Before generate rule scripts on a fresh project — generation reads this map.

Inputs

• All markdown rule files under docs/instructions/rules/** (the .yml registries are not prose rules and are skipped).
• The project's existing enforcers, read to populate enforced_by: eslint.config.js / .eslintrc.*, tsconfig.json strictness flags, Prettier config, and existing paqad infra (module-health, design-test, pentest).
• The prior rule-script-map.yml if present (script entries are carried over for unchanged rules).

Procedure

1. Embed markers + collect the inventory:

   node scripts/analyze.mjs [project-root]
   

   Prints { inventory, files, rule_files_hash, changed_files }. The script has already written the markers back into the rule files on disk.
2. Detect existing enforcers per rule. Read eslint.config.js/.eslintrc.*, tsconfig.json, Prettier config. A rule covered by an existing enforcer gets enforced_by: ["eslint:no-debugger"] and no script — see references/classification-guide.md.
3. Classify each remaining rule deterministic / heuristic / unverifiable. Use references/classification-guide.md for the decision rubric. unverifiable requires a reason.
4. Run the conflict pass. For any pair of contradictory rules (e.g. "always named exports" vs "components use default exports"), record them and surface a Decision Pause packet quoting both rules; await resolution before writing the map. Record conflicts into drift.json so the dashboard + planning gate see them:

   node scripts/record-conflicts.mjs <project-root> <conflicts.json>
   

   where conflicts.json is [{ "rule_ids": ["RL-…","RL-…"], "message": "…" }, ...]. This emits RS-CONFLICT findings.
5. Write the draft map through the single writer:

   node scripts/write-map.mjs <project-root> <classifications.json>
   

   where classifications.json is [{ "id", "verifiability": { "kind", "reason"? }, "enforced_by": [] }, ...].
6. Present the ## Analysis Summary block and tell the user to review the map, then type generate rule scripts.