📝 CollabQualityEnforcer_2.4_Roadmap.md

CollabQualityEnforcer 2.4 Roadmap

Document: CollabQualityEnforcer_2.4_Roadmap.md
Product: Collabware
Project: Collabware Code Quality Program
Target Module: CollabQualityEnforcer.py
Current Version: 2.3.0
Target Version: 2.4.0
Status: IMPLEMENTATION SPECIFICATION

1. Audience and Instruction

This document is addressed specifically to the programming AIs responsible for implementing and reviewing CollabQualityEnforcer 2.4.

Primary implementation and review participants:

All contributors are subject to the same quality standards enforced by CollabQualityEnforcer.

No contributor, human or AI, is exempt from quality analysis.

The origin of code must not affect:

2. Current State

CollabQualityEnforcer 2.3.0 provides a functioning quality enforcement framework.

The existing architecture includes:

Source Discovery
       |
       v
Rule Registry
       |
       v
Independent Quality Rules
       |
       v
Finding Model
       |
       v
Suppression Processing
       |
       v
Quality Score
       |
       v
Quality Gate
       |
       v
Human Report + JSON Report

The current implementation also provides:

Existing backup behaviour:

file.py
file.py.bak
file.py.bak2
file.py.bak3
...

Existing implemented rules:

DOC-001
Collabware documentation header detection

SEC-001
Potential hard-coded secret detection

CRD-001
Collaboration credit validation

3. Primary Rule for Version 2.4

DO NOT REWRITE COLLABQUALITYENFORCER

CollabQualityEnforcer 2.3.0 already has the required core framework.

Version 2.4 must extend the existing architecture.

Do not replace the existing:

unless modification is necessary to support the requirements in this specification.

The preferred design principle is:

Extend the framework. Do not redesign the framework.

4. Version 2.4 Objectives

Version 2.4 has three primary objectives.

Objective A — Complete Documentation Validation

Upgrade DOC-001.

The current implementation only verifies the presence of:

PRODUCT: Collabware

This is insufficient.

Version 2.4 must validate the complete Collabware documentation header.

Objective B — Add Hard-Coded Configuration Detection

The current SEC-001 rule detects only a limited class of hard-coded secrets.

Version 2.4 must distinguish between:

SECRET
ENVIRONMENT-SPECIFIC VALUE
CONFIGURATION CANDIDATE
MAGIC NUMBER
LEGITIMATE CONSTANT

Not all literals are defects.

Objective C — Introduce Reusable Python AST Analysis

Version 2.4 must introduce a reusable Python AST analysis layer.

The AST layer is intended to become a foundation for later versions.

It should support future analysis of:

Do not implement the entire future rule set in 2.4.

Build the AST foundation cleanly.

5. Required Architecture

The target architecture after Version 2.4 should resemble:

CollabQualityEnforcer
        |
        +-- Source Discovery
        |
        +-- Language Analysis
        |        |
        |        +-- Python AST Adapter
        |
        +-- Rule Registry
        |        |
        |        +-- Documentation Rules
        |        |
        |        +-- Security Rules
        |        |
        |        +-- Configuration Rules
        |
        +-- Finding Manager
        |
        +-- Remediation Engine
        |
        +-- Quality Gate
        |
        +-- Report Generator

The AST infrastructure should be reusable by future rule modules.

Do not embed AST parsing logic independently inside every rule.

6. DOC-001 — Complete Documentation Header Validation

Current Problem

The existing rule only verifies that a source file contains:

PRODUCT: Collabware

This permits incomplete headers to pass.

Required Header Fields

Version 2.4 must validate:

PRODUCT
PROJECT
MODULE
MODULE_VERSION
PURPOSE
FUNCTION
DEPENDENCIES
STATUS
LAST_MODIFIED
COLLABORATION

Required Rule Behaviour

The rule must:

  1. Detect the Collabware documentation header.
  2. Identify all header fields.
  3. Detect missing required fields.
  4. Detect empty required fields.
  5. Validate selected fields.
  6. Report findings independently where practical.
  7. Avoid unnecessary duplicate findings.

PRODUCT Validation

Expected value:

Collabware

Failure should generate:

Rule: DOC-001
Severity: MAJOR
Category: DOCUMENTATION

PROJECT Validation

The field must exist and must not be empty.

Example:

PROJECT: Collabware Code Quality Program

MODULE Validation

The field must exist and must not be empty.

Where practical, the system may compare the declared module name with the source filename.

Example:

MODULE: collabware_quality_core

A filename mismatch should initially be reported as:

Severity: MINOR

Do not automatically change the module name unless explicitly supported by safe remediation rules.

MODULE_VERSION Validation

The field must exist and must not be empty.

Version 2.4 should support basic semantic version format validation:

MAJOR.MINOR.PATCH

Example:

2.4.0

Invalid version format should produce a documentation finding.

PURPOSE Validation

The field must:

Do not attempt excessive semantic judgement in Version 2.4.

FUNCTION Validation

The field must:

The purpose is to describe the primary function or responsibility of the module.

DEPENDENCIES Validation

The field must exist.

Accepted initial values may include:

None

or a dependency list.

Actual dependency comparison is not required for Version 2.4 unless implementation can be cleanly achieved using the AST infrastructure.

Dependency comparison should not delay Version 2.4.

STATUS Validation

The field must exist and must not be empty.

Recommended values:

DEVELOPMENT
TESTING
ACTIVE
DEPRECATED
RETIRED

Unknown values may initially generate:

Severity: INFORMATION

rather than failure.

LAST_MODIFIED Validation

The field must exist.

The expected date format is:

YYYY-MM-DD

Example:

2026-08-31

Invalid date format should generate a documentation finding.

Do not attempt to verify whether the date accurately corresponds to source control history in Version 2.4.

COLLABORATION Validation

The existing CRD-001 rule must remain compatible.

The documentation rule should verify that the field exists.

CRD-001 should continue to verify that the collaboration line includes:

Andrew
Claude
ChatGPT
Gemini

Do not require an exact literal match.

Reasonable variations in role names, API naming, version notation, and punctuation must be tolerated.

7. Documentation Header Parsing

Do not create a large collection of unrelated regular expressions scattered across rules.

Create a reusable header extraction mechanism.

Conceptually:

Source File
     |
     v
Locate Module Documentation Block
     |
     v
Extract Header Fields
     |
     v
{
    PRODUCT: ...,
    PROJECT: ...,
    MODULE: ...,
    ...
}
     |
     v
Documentation Rules

Recommended conceptual API:

header = extract_collabware_header(source_unit)

The returned structure should support:

header.exists
header.fields
header.field_locations
header.raw_content

Example conceptual structure:

{
    "exists": True,
    "fields": {
        "PRODUCT": "Collabware",
        "PROJECT": "Collabware Code Quality Program",
        "MODULE": "collabware_quality_core",
        "MODULE_VERSION": "2.4.0",
        "PURPOSE": "...",
        "FUNCTION": "...",
        "DEPENDENCIES": "...",
        "STATUS": "ACTIVE",
        "LAST_MODIFIED": "2026-08-31",
        "COLLABORATION": "..."
    },
    "field_locations": {
        "PRODUCT": 7,
        "PROJECT": 8
    }
}

The actual implementation may differ.

The objective is reusable structured extraction.

8. CONFIG Rule Family

Version 2.4 must introduce a configuration analysis category.

Recommended category:

CONFIGURATION

The new rules should distinguish between:

Hard-coded secret
        |
        v
SECURITY finding

Hard-coded environment value
        |
        v
CONFIGURATION finding

Hard-coded configuration candidate
        |
        v
CONFIGURATION finding

Magic number
        |
        v
CONFIGURATION or STRUCTURE finding

Legitimate constant
        |
        v
No finding

9. Hard-Coded Environment Values

The system should identify likely environment-specific values such as:

Examples:

DATABASE_HOST = "192.168.1.10"

API_URL = "https://api.example.com"

SERVICE_PORT = 8080

DATA_PATH = "/opt/collabware/data"

These should generally generate:

Severity: MINOR or MAJOR
Category: CONFIGURATION

Severity should depend on confidence and context.

Do not automatically assume every URL or path is wrong.

Some values are legitimately fixed constants.

10. Magic Number Detection

Version 2.4 should implement an initial conservative magic-number rule.

Potential candidates:

if retries > 7:
timeout = 600
for index in range(42):

Do not flag universally accepted values such as:

0
1
-1

The initial implementation must be conservative.

False positives are worse than failing to identify every possible magic number.

Recommended rule:

CONFIG-002
Potential magic number or configuration constant

Recommended initial severity:

MINOR

11. AST Infrastructure

Purpose

Python AST analysis must become the reusable analysis foundation.

Conceptually:

Python Source
     |
     v
ast.parse()
     |
     +----------------+
     |                |
     v                v
Parse Success     Parse Failure
     |                |
     v                v
Python AST      STRUCT finding
     |
     v
Reusable AST Context

Parse Failure

If Python source cannot be parsed:

Rule: STRUCT-001
Category: STRUCTURE
Severity: MAJOR
Message:
Python source could not be parsed successfully.

The finding should include parser error information where safe and useful.

Do not expose unnecessary internal tracebacks.

AST Context

Recommended conceptual structure:

class PythonAnalysisContext:

    source_unit
    source_text
    ast_tree

    assignments
    functions
    classes
    imports
    constants

The exact design is flexible.

The objective is to parse once and reuse the result.

12. Rule Execution Context

The existing rule signature is approximately:

rule(unit, config)

Version 2.4 may evolve this if necessary.

A preferred future-oriented approach is:

rule(unit, analysis_context, config)

However:

Do not introduce unnecessary breaking changes.

If modifying the rule interface would require significant rewrites, introduce a context mechanism compatible with existing rules.

For example:

analysis_context = AnalysisContext.for_unit(unit)

The implementation must ensure that AST parsing is not unnecessarily repeated for every rule.

13. Initial AST-Assisted Configuration Analysis

The new configuration rules should prefer AST analysis over regex-only analysis where possible.

For example:

API_URL = "https://example.com"

should be understood as:

Assignment
    Variable: API_URL
    Value: String Constant

rather than merely matching text.

This should allow future rules to consider:

14. Rule IDs

The following IDs are recommended for Version 2.4.

DOC-001
Complete Collabware documentation header validation

CRD-001
Collaboration credit validation

SEC-001
Potential hard-coded secret detection

CONFIG-001
Potential hard-coded environment-specific configuration

CONFIG-002
Potential magic number or configuration constant

STRUCT-001
Python source could not be parsed

Do not renumber existing rules.

Existing rule IDs are stable identifiers.

15. Remediation Requirements

Auto-remediation must remain conservative.

DOC-001

The existing header injection/remediation behaviour may be extended.

If a header is missing, automatic insertion is permitted.

If individual fields are missing, automatic insertion may be permitted only when a safe value is known.

Examples of potentially safe defaults:

PRODUCT: Collabware
MODULE: <derived from filename>
MODULE_VERSION: 1.0.0
STATUS: ACTIVE
LAST_MODIFIED: <current UTC date>
COLLABORATION: <standard team credit>

Examples that should not be guessed without explicit instruction:

PROJECT
PURPOSE
FUNCTION
DEPENDENCIES

Do not automatically invent meaningful project metadata.

CONFIG Rules

Version 2.4 should not automatically rewrite hard-coded configuration values.

Find and report them.

Do not attempt automatic configuration refactoring in Version 2.4.

Secrets

Never:

Mask sensitive values.

16. Quality Gate

The existing quality gate should remain intact.

The system should continue to fail when active findings include:

BLOCKER
CRITICAL

Major findings remain governed by:

max_major_findings

Quality score remains governed by:

minimum_quality_score

Do not change scoring weights without explicit approval.

17. Reporting Requirements

All new findings must integrate with both existing report formats.

Human Report

The live report must show:

Processing: module.py

  WARNING MAJOR [DOC-001]
  Missing required field: PURPOSE
      -> Add a concise description of the module's purpose.

  MINOR [CONFIG-001]
  Possible hard-coded environment-specific URL.
      -> Consider moving this value to project configuration.

JSON Report

New rules must automatically appear in the existing JSON finding structure.

Example:

{
    "rule_id": "CONFIG-001",
    "severity": "MINOR",
    "category": "CONFIGURATION",
    "file": "module.py",
    "line": 42,
    "message": "Potential hard-coded environment-specific configuration.",
    "confidence": 0.87,
    "recommendation": "Consider moving this value to configuration.",
    "fixable": false
}

18. Testing Requirements

Version 2.4 must include tests.

At minimum, test the following.

Documentation Header Tests

Valid complete header

Expected:

No DOC-001 findings

Missing header

Expected:

DOC-001 finding

Missing individual field

Expected:

Documentation finding identifying the missing field

Empty field

Expected:

Documentation finding

Invalid module version

Expected:

Documentation finding

Invalid date format

Expected:

Documentation finding

AST Tests

Valid Python

Expected:

Successful AST analysis

Invalid Python

Expected:

STRUCT-001 finding

Configuration Tests

Test:

URL
IPv4 address
Hostname
Absolute path
Port
Magic number
0
1
-1

The accepted constants:

0
1
-1

should not generate magic-number findings by default.

Regression Tests

The following existing behaviour must continue to work:

19. Non-Goals for Version 2.4

The following are explicitly outside the required scope of Version 2.4.

Do not delay Version 2.4 attempting to implement them.

Duplicate code detection

Near-duplicate code detection

CollabCore reuse matching

Semantic similarity analysis

Loop termination analysis

Infinite-loop proof

Cyclomatic complexity analysis

Deep structural analysis

SQL injection analysis

Command injection analysis

Path traversal analysis

Unsafe deserialisation analysis

Authentication analysis

Authorisation analysis

Automatic configuration refactoring

Multi-language parsing

These are planned future rule families.

20. Version 2.4 Acceptance Criteria

Version 2.4 is complete when all of the following are true.

Architecture

Documentation

Configuration

Security

Reporting

Remediation

Testing

21. Collaboration Workflow

Gemini

Primary responsibilities:

Gemini must not assume existing code is correct merely because it already exists.

Existing code remains subject to review.

Claude

Primary responsibilities:

Claude should report findings against the specification rather than rewriting the implementation unnecessarily.

ChatGPT

Primary responsibilities:

Andrew.human

Final authority for:

22. Mandatory Implementation Principles

All implementation work must follow these principles.

Preserve the Framework

Do not replace working architecture unnecessarily.

Prefer Structured Analysis

Prefer AST analysis over regex when AST analysis is appropriate.

Regex remains acceptable for:

Do not force AST analysis where it adds no value.

Be Conservative

The system must not generate enormous numbers of low-value findings.

Prefer:

High-confidence findings

over:

Large volumes of speculative warnings

Evidence-Based Findings

Every finding should be explainable.

The report should make clear:

What was found
Where it was found
Why it was flagged
How confident the checker is
What should be considered next

Do Not Pretend Heuristics Are Proof

Use confidence and appropriate wording.

Examples:

Potential hard-coded configuration

rather than:

Incorrect configuration

unless the problem can actually be proven.

23. Final Instruction

Implement Version 2.4 as an incremental extension of CollabQualityEnforcer 2.3.0.

The implementation priority is:

1. Preserve existing architecture
        |
        v
2. Complete DOC-001
        |
        v
3. Build reusable header extraction
        |
        v
4. Introduce reusable Python AST analysis
        |
        v
5. Add CONFIG-001
        |
        v
6. Add CONFIG-002
        |
        v
7. Add STRUCT-001 parse failure handling
        |
        v
8. Add tests
        |
        v
9. Regression review
        |
        v
10. Independent review

Do not attempt to implement future versions prematurely.

Version 2.4 should establish a clean foundation for:

2.5
Structure and loop analysis

2.6
Duplicate detection and CollabCore reuse analysis

2.7
Expanded security analysis

The objective is not to produce the largest possible number of checks.

The objective is to produce a reliable, extensible, evidence-based code quality enforcement system that can progressively analyse all Collabware code — regardless of whether that code was written by Andrew.human, Claude, ChatGPT, Gemini, or any future contributor.