feat(aidd-dev): audit codebase compliance against project rules

Open
#864 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
45/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Active
Tech stack
markdown
Domain
devtools, tooling

Research direction

Start with plugins/aidd-dev/skills/04-audit/SKILL.md and its existing actions, then read 05-review/SKILL.md and actions/03-review-relevancy.md to trace Rule discovery and report conventions. Define the optional audit flow within the existing report and findings table, covering repository-wide code and the four required outcomes. Done means the acceptance criteria hold without adding a skill or pillar or changing 05-review.

Written by the indexing model from the issue text.

Description

Problem

aidd-dev:05-review discovers declared project Rules at runtime and checks conformance, but only for a diff. aidd-dev:04-audit assesses the existing codebase read-only, but its current quality pillars do not explicitly cover compliance with project Rules.

There is therefore no explicit repository-wide workflow that answers: does the existing codebase comply with all applicable project Rules? This leaves legacy code, Rules introduced after code was written, code created outside AIDD, and code never included in a reviewed diff without that assessment.

Scope
  • Implement this as an optional rule-conformance action within aidd-dev:04-audit, reusing the existing audit report and findings table.
  • Discover applicable project Rules at runtime and determine their scope before applying them, using the existing Rule-discovery approach from 05-review.
  • Evaluate existing repository code, not only a diff, against those Rules.
  • Produce one outcome for each applicable Rule: compliant, confirmed violation with the Rule plus affected file:line and supporting evidence, interpretation-dependent, or not verifiable from repository evidence.
  • Produce a global clean result only when all applicable Rules that are verifiable from repository evidence are compliant.
  • Keep this within aidd-dev: it must not depend on aidd-context or call a skill from another plugin. aidd-dev evaluates code conformance; aidd-context owns Rule content and context health (placement, scope, duplication, conflicts, and loading). Both inspect project artifacts directly, and neither plugin calls the other.
  • Do not introduce a new skill or audit pillar, and do not change the existing diff-only contract of 05-review.
Acceptance criteria
  • The optional 04-audit action discovers declared project Rules at runtime and determines applicability before evaluating code, reusing the approach used by 05-review.
  • It evaluates existing repository code, including code outside the current diff.
  • It reuses the existing audit report and findings table.
  • It produces exactly one outcome for each applicable Rule, using one of: compliant, confirmed violation, interpretation-dependent, or not verifiable from repository evidence.
  • Each confirmed violation identifies the Rule, affected file:line, and repository evidence.
  • Interpretation-dependent findings are distinct from confirmed violations.
  • A Rule that cannot reasonably be verified from repository evidence is reported as not verifiable from repository evidence, not asserted as a violation.
  • A global clean result is possible only when every applicable, verifiable Rule is compliant.
  • The default workflow is read-only and does not modify Rules or application code.
  • The implementation adds neither a new skill nor a new audit pillar, creates no aidd-dev to aidd-context dependency or cross-plugin call, and does not change the existing diff-only 05-review contract.
Prior art in this repo
  • 04-audit/SKILL.md#L3-L33 is the read-only codebase audit, but its seven listed pillars do not explicitly include compliance with project Rules.
  • 05-review/SKILL.md#L3-L27 defines a read-only review of a diff; review-relevancy is its Rule-conformance axis.
  • 03-review-relevancy.md#L3-L24 discovers declared Rules at runtime, evaluates a diff, cites violated Rules, and writes None. when clean.
  • docs/ARCHITECTURE.md#L85-L109 assigns code transformation to aidd-dev and places a missing capability with the plugin whose concern owns it; this makes aidd-dev the appropriate scope without requiring a new skill or audit pillar.
  • #791 is candidate Rule to existing Rules during Rule generation; #792 is Rules to Rules; #793 is context artifacts to ownership and placement; #796 is Rule to development decision to artifact. None evaluates existing Rules against the existing codebase.

I checked the current main contracts and searched open and closed issues and pull requests for codebase Rule compliance, Rule conformance, and equivalent wording. No duplicate was found.

Out of scope
  • Automatically fixing violations or modifying Rules or application code.
  • Auditing Rule quality, conflicts, duplication, or drift; that is #792.
  • Auditing context-artifact ownership or placement; that is #793.
  • Tracing a Rule's influence on development decisions; that is #796.
  • Defining universal Rule precedence across AI hosts.
  • Treating every Rule as statically verifiable.
Dominant language
TypeScript
Stars
481
Forks
45
Avg merge
17h 40m
Merged PRs (30d)
106

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from ai-driven-dev/framework

All issues in ai-driven-dev/framework

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.