Skip to content

code-generation-policy.md

Latest commit

 

History

History
106 lines (78 loc) · 5.53 KB

code-generation-policy.md

File metadata and controls

106 lines (78 loc) · 5.53 KB
Raw

Code Generation Policy (Engineering Policy A)

This document establishes the canonical policy regarding the use of AI Assistants, Autonomous Coding Agents, Code Generation Systems, Automated Refactoring Tools, and any Future AI-assisted development systems within the Nexus Forge repository. This policy remains valid regardless of future tooling and is permanent.

1. AI Scaffolding Policy

Automated systems and code generators may be utilized to accelerate development under strict constraints:

  • Allowed: Initial repository scaffolding, directory tree generation, and boilerplate interface stubs.
  • Allowed: Throwaway experimental prototypes that live entirely outside of the src/ capability directories.
  • Forbidden: Generating or modifying production code by repeatedly executing sweeping generator scripts (e.g., generate_shared.py).

2. Production Code Ownership

The moment code is committed into the src/ directory, it crosses the boundary from scaffolding to production code.

  • Production code is the single source of truth.
  • All subsequent features, hardening passes, and architectural refinements must be authored as direct file modifications.
  • You may not overwrite or regenerate production modules using external generative scripts.

3. Definition of Production Code

Production code includes every source file under the official application source tree (e.g., src/) and any code executed as part of the Nexus Forge application.

Production code must satisfy all of the following criteria:

  • Architecture compliance
  • Public Interface compliance
  • Repository Invariants
  • Unit testing requirements
  • Documentation requirements
  • Static analysis requirements
  • Code review requirements

Production code evolves only through reviewed changesets and never through bulk regeneration.

4. AI Responsibility

AI tools are engineering assistants. They are not authoritative sources.

The human or AI contributor remains fully responsible for:

  • Correctness
  • Architectural compliance
  • Security
  • Performance
  • Licensing
  • Maintainability

Using AI or automated generation never transfers engineering responsibility away from the contributor submitting the change.

5. Forbidden Practices

The following practices are strictly prohibited within the Nexus Forge repository:

  • Blind regeneration of production modules: Wipes out historical context and manual hardening passes.
  • Large-scale rewrites without architectural review: Bypasses established governance and design intent.
  • Circumventing Repository Invariants: Destroys capability isolation and boundary enforcement.
  • Introducing undocumented dependencies: Compromises vendor independence and security.
  • Bypassing review through generated code: Assumes generated code is inherently correct, which is false.
  • Mixing prototype code into production: Degrades system stability and architectural purity.
  • Modifying generated historical artifacts and treating them as production: Historical scaffolding scripts (e.g., in scripts/archive/) must remain retired.

6. Human Review Requirements

While automated systems may author direct modifications via pull requests, reviewers must evaluate every change against the:

  1. Product Definition
  2. Architecture Design
  3. Architecture Enforcement Strategy

If a generated PR attempts to resolve a domain bug by wrapping the entire domain in a new generative script or executing a sweeping rewrite without justification, it must be rejected.

7. AI Pull Request Traceability

Every AI-generated Pull Request must include explicit traceability to ensure reviewers can understand why the AI changed something, rather than only what changed.

The Pull Request must include:

  • Purpose: The explicit reason for the modification.
  • Summary of changes: A high-level overview of the implementation.
  • Files modified: Explicit listing of the impact radius.
  • Architectural impact: How this aligns with or affects the established architecture.
  • Linked Requirement, ADR, or Issue: The upstream source of the change.
  • Test evidence: Proof of behavioral coverage and correctness.
  • Documentation updates (if applicable): Necessary updates to interface or domain documentation.

8. Rules for Accepting AI-Generated Pull Requests

Every AI-generated Pull Request must additionally satisfy the following strict code standards:

  • Architectural compliance
  • Public interface compatibility
  • No undocumented dependencies
  • Test coverage
  • Documentation updates
  • No business logic inside infrastructure
  • No violation of Repository Invariants

AI-generated code receives the same rigorous review standards as human-authored code. AI-generated code is never exempt from architectural review.

  • The PR must consist of fine-grained, deliberate edits (e.g., diffs) against the existing src/ tree.
  • The PR must not contain commands that blindly rewrite entire directories to bypass refactoring.

9. Rules for Future Contributors

  • If you find an archive of generator scripts in scripts/archive/, do not run them. They are historical artifacts.
  • When expanding the Shared Kernel or any module, author your code directly and write corresponding unit tests.

10. Governance

  • This document is the canonical policy governing AI-assisted development within Nexus Forge.
  • Any modification to this policy requires explicit architectural approval.
  • Future contributor guides must reference this document rather than duplicate its rules.
  • This policy remains in force unless superseded by a formally approved Architecture Decision Record (ADR).