aif-rules-check

name	aif-rules-check
description	Run a standalone read-only rules compliance gate against changed files or a git ref. Use when you need a dedicated project-rules check without a full review or verify pass.
argument-hint	[git ref | empty]
allowed-tools	Read Glob Grep Bash(git *) AskUserQuestion
disable-model-invocation	false
metadata	{"author":"AI Factory","version":"1.0","category":"quality"}

Rules Compliance Gate

Run a standalone read-only rules gate for project rules. This command checks rule compliance only; it does not replace $aif-review or $aif-verify.

Step 0: Load Contract

• Read references/RULES-CHECK-CONTRACT.md first.
• Treat it as the canonical source for verdict semantics and report structure.
• If examples in this file drift from the reference, follow the reference.

Step 1: Load Config

FIRST: Read .ai-factory/config.yaml if it exists to resolve:

• paths.rules_file
• paths.rules
• paths.plan
• paths.plans
• language.ui
• git.enabled
• git.base_branch
• rules.base
• named rules.<area> entries
• workflow.plan_id_format (default: slug) — used by the optional branch-based plan-context lookup in Step 2.3. Active values: slug and sequential. Plan context may be a root full-plan file or direct child ultra index.md; numbered lookup covers both shapes. timestamp and uuid are reserved values and currently behave like slug. Treat any unknown value as slug.

If config is missing or partial, use defaults:

• paths.rules_file: .ai-factory/RULES.md
• paths.rules: .ai-factory/rules/
• paths.plan: .ai-factory/PLAN.md
• paths.plans: .ai-factory/plans/
• git.enabled: true
• git.base_branch: detect the repo default branch from git metadata; fall back to main only when detection is unavailable
• rules.base: .ai-factory/rules/base.md
• workflow.plan_id_format: slug

If paths.rules_file is missing from config, default to .ai-factory/RULES.md instead of treating config as incomplete. If git.base_branch is missing from config, resolve the repository default branch from git metadata when possible; use main only as the final fallback.

Step 1.1: Load Skill Context

Read .ai-factory/skill-context/aif-rules-check/SKILL.md - MANDATORY if the file exists.

This file contains project-specific rules accumulated by $aif-evolve from patches, codebase conventions, and tech-stack analysis. These rules are tailored to the current project.

How to apply skill-context rules:

• Treat them as project-level overrides for this skill's general instructions.
• When a skill-context rule conflicts with a general rule in this file, the skill-context rule wins.
• When there is no conflict, apply both.
• Skill-context rules apply to all outputs of this skill, including verdict wording and report structure.

Enforcement: Before presenting the final report, verify it against all skill-context rules and fix any drift.

Step 2: Resolve Inputs

Resolve two inputs before checking any rule:

1. Changed scope - the diff and file list you are evaluating
2. Resolved rule sources - the rule artifacts that may apply to that scope

Step 2.1: Resolve Changed Scope

If the user provided a git ref:

1. Validate it first:

   git rev-parse --verify <argument>
   

2. If valid, use:

   git diff --name-only <argument>...HEAD
   git diff <argument>...HEAD
   

3. If invalid, ask:

   AskUserQuestion: `<argument>` is not a valid git ref. What should I check instead?
   
   Options:
   1. Check staged / working-tree changes
   2. Cancel
   

Without arguments:

1. Prefer staged work:

   git diff --cached --name-only
   git diff --cached
   

2. If nothing is staged, fall back to working tree:

   git diff --name-only
   git diff
   

3. If there is still no local diff and git.enabled = true, fall back to branch diff:

   git diff --name-only <resolved-base-branch>...HEAD
   git diff <resolved-base-branch>...HEAD
   

If there are still no changed files, return WARN rather than a hard failure.

Step 2.2: Resolve Rule Sources

Load rule sources in this order:

1. The resolved paths.rules_file artifact
2. The resolved rules.base file
3. Any named rules.<area> files from config that clearly match the changed scope

Area rules are optional and scoped:

• Use changed file paths, folder names, and optional plan context to judge relevance.
• If relevance is ambiguous, mention the rule source as uncertain and keep the outcome at WARN, not FAIL.

If no rules sources resolve, return WARN rather than a hard failure.

Step 2.3: Optional Plan Context

Optional plan context: use the active plan file only when it helps interpret scope or area relevance; absence of a plan is never a failure.

Plan resolution order:

1. Compute the canonical branch stem the same way as $aif-plan, $aif-implement, and $aif-improve:
   • get current branch via git branch --show-current (git mode only);
   • branch_stem = current branch with every / replaced by - (for example feature/user-auth → feature-user-auth).
2. Branch-based lookup using <branch_stem>:
   • when workflow.plan_id_format = sequential, glob both paths.plans/[0-9][0-9][0-9][0-9]_<branch_stem>.md and paths.plans/[0-9][0-9][0-9][0-9]_<branch_stem>/index.md; Read every directory candidate and retain it only when it contains exactly one <!-- aif:plan-mode:ultra -->, then pick the highest-numbered valid artifact and warn when multiple valid candidates exist; prefer ultra if both shapes share the highest prefix;
   • otherwise/fallback check paths.plans/<branch_stem>/index.md and paths.plans/<branch_stem>.md; Read the directory entrypoint first, ignore it unless it contains exactly one ultra marker, and warn/prefer ultra if both valid shapes exist.
3. A single named artifact in paths.plans: count root *.md full plans and direct child */index.md entrypoints containing <!-- aif:plan-mode:ultra -->; exclude the resolved fast-plan path and never count phase files.
4. The fast plan at paths.plan.

For ultra, read index.md first and only the linked phase files relevant to the changed area when extra scope detail is needed. Do not fail the rules check because a plan artifact is missing or ambiguous. An automatically discovered directory entrypoint counts only when it contains exactly one <!-- aif:plan-mode:ultra -->; ignore unrelated */index.md files.

Step 3: Evaluate Rules

Read the changed files from the resolved scope and compare them against the resolved rules.

Classification rules:

• PASS when at least one applicable rule was checked and no clear violations were found.
• WARN when no applicable rules were resolved, the evidence is ambiguous, or there are no changed files to evaluate.
• FAIL when an explicit hard rule is clearly violated by the inspected diff or changed files.

Only return FAIL when an explicit hard rule is clearly violated by the inspected diff or changed files.

Evidence rules:

• Tie every blocking violation to specific rule text and at least one concrete file/path or diff hunk.
• If a rule sounds like a preference, is too vague, or cannot be verified confidently from the diff, do not escalate it past WARN.
• Missing optional files or partially configured rules hierarchy are WARN, not FAIL.

Step 4: Read-Only Boundary

This command is read-only: do not edit RULES.md, rules/base.md, rules.<area>, plan files, or source code.

If rules are missing, stale, or need refinement:

• Suggest $aif-rules <rule text> for axioms
• Suggest $aif-rules area:<name> for area-specific rules

Step 5: Output

Use the exact verdict semantics and section order from references/RULES-CHECK-CONTRACT.md.

Required content:

• overall verdict
• files checked
• gate results
• blocking violations
• suggested fixes
• suggested rule updates
• final machine-readable aif-gate-result fenced JSON block

When useful, suggest the next best workflow:

• $aif-review for broader code review
• $aif-verify for full plan-completeness verification
• $aif-rules when the underlying rules need to be captured or corrected

Machine-readable gate result:

• Append one final fenced aif-gate-result JSON block after the human-readable rules report.
• Use "gate": "rules".
• Map the human rules verdict exactly: PASS -> pass, WARN -> warn, and FAIL -> fail.
• Use "blocking": true|false; set it to true only for explicit hard-rule violations that produce a human FAIL.
• Include only hard-rule violations in "blockers": [.
• Include changed or inspected paths in "affected_files": [.
• Set "suggested_next": { to $aif-rules when rules should be added or clarified, $aif-fix when code must change, or null when no allowed next command fits.
• Do not use $aif-review in the JSON suggested_next.command; it may appear only in human-readable workflow suggestions.

{
  "schema_version": 1,
  "gate": "rules",
  "status": "warn",
  "blocking": false,
  "blockers": [],
  "affected_files": [],
  "suggested_next": {
    "command": "$aif-rules",
    "reason": "Rules are missing or ambiguous for the changed scope."
  }
}

Schema reminder: "status": "pass|warn|fail", "blocking": true|false, "blockers": [, "affected_files": [, "suggested_next": {.