Engineering_Controls_For_AI_Assisted_Software_Development.md

Engineering Controls for AI-Assisted Software Development

Version: 2.3.4 Date: 2026-08-27 Status: Reusable companion process guide

1. Purpose

This document defines the normal engineering controls that should surround and support AI-assisted software development.

It is a companion to the Heuristic Evaluation-Remedy-Reflection Loop. The HERR Loop tells an AI agent how to evaluate, improve, verify and reflect. This document defines the engineering guardrails that make those AI-assisted changes safe to accept into a real software product.

The core principle is:

AI may accelerate software development, but it must not replace engineering controls.

AI-generated or AI-assisted code should pass through the same discipline as human-written code:

• Version control.
• Tests.
• Continuous integration.
• Code review.
• Architecture records.
• Security review.
• Release discipline.
• Observability.
• Operational rollback.

2. Relationship to the HERR Loop

The HERR Loop is an operating method for the AI.

This document is the control system around the work.

Engineering controls
  -> define boundaries, evidence and acceptance
     -> HERR Loop
        -> evaluates, remedies, verifies and reflects
           -> engineering controls
              -> review, integrate, release and monitor

The HERR Loop should sit inside these controls. If the HERR Loop says a remedy is complete, the engineering controls still decide whether the change is acceptable for merge, release and operation.

3. Control Objectives

The engineering controls exist to ensure that software changes are:

• Traceable.
• Reviewable.
• Tested.
• Secure.
• Maintainable.
• Reversible.
• Release-ready.
• Operationally observable.

They reduce the risks that are especially common with AI-assisted work:

• Plausible but incorrect implementation.
• Hidden architectural drift.
• Missing edge-case tests.
• Undocumented contract changes.
• Overbroad refactoring.
• Security and privacy regressions.
• Unclear ownership.
• Changes that pass locally but fail in integration or production.

4. Control 1: Version Control

Version control is the base control for all software work.

4.1 Objectives

Version control must provide:

• A complete history of changes.
• A way to compare proposed changes.
• A safe way to branch, review and merge.
• A way to revert or repair mistakes.
• Traceability from requirement to implementation.

4.2 Required Practices

• All source code, migrations, tests and documentation must be kept in version control.
• AI-assisted changes must be made on a branch or otherwise isolated until reviewed.
• Commits should be focused and explain why the change exists.
• Generated or bulk changes should be clearly identified.
• Unrelated edits should not be mixed into the same change.
• Secrets must never be committed.
• Large generated artifacts should be committed only when the project expects them.

4.3 AI-Specific Rules

The AI must:

• Check the working tree before making changes when appropriate.
• Avoid overwriting user changes.
• Avoid unrelated formatting churn.
• Keep generated changes traceable to the user goal.
• Report which files were changed.
• Never use destructive version-control commands unless explicitly requested and approved.

4.4 Quality Gate

A change should not proceed to review if:

• The diff contains unrelated changes.
• The change cannot be explained.
• The branch includes accidental generated files.
• The working tree contains unresolved conflicts.
• Secrets or credentials are present.

5. Control 2: Automated Tests

Tests are the primary evidence that behaviour works as intended.

5.1 Objectives

Tests must provide confidence that:

• The changed behaviour works.
• Existing behaviour did not regress.
• Critical edge cases are covered.
• Security and permission boundaries still hold.
• Future changes can be made safely.

5.2 Test Types

Test type	Purpose
Unit tests	Verify small functions and isolated business rules.
Integration tests	Verify modules working together, often with database or API.
End-to-end tests	Verify user workflows through the full stack.
Contract tests	Verify API contracts, schemas and compatibility.
Regression tests	Lock in fixes for known bugs.
Security tests	Verify authorization, isolation and abuse cases.
Migration tests	Verify database changes apply correctly.
Performance tests	Verify latency, throughput or scale assumptions.

5.3 Required Practices

• Every behaviour change should have a test where practical.
• Bug fixes should include a regression test where practical.
• Critical paths require stronger coverage than low-risk code.
• Tests should be deterministic and maintainable.
• Tests should fail for the defect they are meant to catch.
• Tests should not depend on hidden local state.

5.4 AI-Specific Rules

The AI must:

• Prefer existing test patterns.
• Add focused tests rather than broad brittle tests.
• Run relevant tests when possible.
• Never claim tests passed unless they were run.
• Report skipped tests and residual risk.
• Avoid weakening or deleting tests to make a change pass.

5.5 Quality Gate

A change should not proceed if:

• Relevant tests fail.
• A critical change has no verification plan.
• Tests were changed to match incorrect behaviour.
• A security-sensitive path lacks adversarial testing.

6. Control 3: Continuous Integration

Continuous integration checks that proposed changes work in a clean, repeatable environment.

6.1 Objectives

CI should verify:

• Build success.
• Test success.
• Type correctness.
• Lint and formatting rules.
• Dependency health.
• Security scans where applicable.
• Migration validity.
• Artifact generation.

6.2 Required Practices

• Main branches should be protected by CI.
• CI should run on every pull request or merge request.
• CI should fail on test failure, build failure or critical security failure.
• CI should use clean environments, not a developer's local machine state.
• CI configuration should be versioned.
• Flaky tests should be fixed or isolated, not ignored.

6.3 AI-Specific Rules

The AI must:

• Prefer commands that mirror CI.
• Report local checks separately from CI checks.
• Not assume CI will pass because local checks passed.
• Not ignore CI failures without diagnosis.
• Treat new CI failures as in-scope unless proven unrelated.

6.4 Quality Gate

A change should not merge if:

• Required CI jobs fail.
• CI is skipped without explicit approval.
• Build artifacts differ unexpectedly.
• Migration or deployment checks fail.

7. Control 4: Code Review

Code review is a human and technical control. It catches defects that tests may miss.

7.1 Objectives

Code review should verify:

• The change solves the right problem.
• The implementation is understandable.
• The design fits the existing system.
• Edge cases are considered.
• Tests are appropriate.
• Security and privacy concerns are addressed.
• Documentation is updated where needed.

7.2 Required Practices

• Non-trivial changes should be reviewed before merge.
• Review should focus on correctness, maintainability and risk.
• Review comments should be specific and actionable.
• The author or AI operator should respond to review comments.
• High-risk changes should receive deeper review.

7.3 AI-Specific Rules

The AI should make review easier by reporting:

• Goal of the change.
• Files changed.
• Key design choices.
• Verification performed.
• Known limitations.
• Assumptions.
• Areas where reviewer attention is needed.

The AI must not hide uncertainty. Reviewers should be told when a decision was inferred, when verification was incomplete or when external facts were not checked.

7.4 Quality Gate

A change should not merge if:

• Review comments identify unresolved high-risk issues.
• The reviewer cannot understand the change.
• The change has no clear relation to the stated goal.
• Risky assumptions remain hidden.

8. Control 5: Architecture Records

Architecture records preserve the reasoning behind important design decisions.

8.1 Objectives

Architecture records should explain:

• What decision was made.
• Why it was made.
• What alternatives were considered.
• What consequences follow.
• When the decision should be revisited.

8.2 Required Practices

Use an architecture decision record when a change affects:

• System boundaries.
• Data model.
• Technology stack.
• Security model.
• Deployment topology.
• Integration patterns.
• Public API.
• Module ownership.
• Long-term maintainability.

8.3 AI-Specific Rules

The AI must:

• Check existing architecture records before proposing architectural changes.
• Avoid creating new architecture by accident during feature work.
• Record new architectural decisions when appropriate.
• Update or supersede stale records when a decision changes.
• Distinguish implementation detail from architecture decision.

8.4 Quality Gate

A major design change should not merge if:

• The architectural rationale is not recorded.
• Existing architecture records are contradicted without explanation.
• The long-term consequences are not understood.

9. Control 6: Security Review

Security review ensures changes do not weaken trust boundaries.

9.1 Objectives

Security review should verify:

• Authentication remains correct.
• Authorization remains correct.
• Tenant or user isolation is preserved.
• Sensitive data is protected.
• Secrets are handled safely.
• Inputs are validated.
• Outputs are encoded safely.
• Logs do not leak sensitive data.
• External integrations are controlled.

9.2 Required Practices

Security review is required for changes involving:

• Authentication.
• Authorization.
• Roles and permissions.
• Tenant isolation.
• Cryptography.
• Secrets.
• File upload or download.
• External APIs.
• Payment or financial data.
• Personal data.
• Administrative functions.
• Audit logging.
• Dependency updates with security implications.

9.3 AI-Specific Rules

The AI must:

• Treat security-sensitive changes as high risk.
• Add adversarial tests where practical.
• Never invent security guarantees.
• Never log secrets or sensitive data.
• Never hard-code credentials.
• Use established project security patterns.
• Report residual security risk.

9.4 Quality Gate

A security-sensitive change should not merge if:

• Authorization is untested.
• Tenant isolation is untested.
• Secrets are exposed.
• Sensitive data handling is unclear.
• A reviewer has not assessed the security impact.

10. Control 7: Privacy and Data Protection

Privacy controls protect personal and sensitive data.

10.1 Objectives

Privacy review should verify:

• The system collects only necessary data.
• Sensitive data has a lawful and documented purpose.
• Retention behaviour is understood.
• Access is limited to appropriate roles.
• Read and write access are auditable where needed.
• Data exports are controlled.
• Test data avoids real personal data.

10.2 Required Practices

Privacy review is required for changes involving:

• Personal data.
• Health data.
• User identity data.
• Audit logs.
• Data export.
• Data deletion.
• Analytics or benchmarking.
• AI processing of user or customer data.

10.3 AI-Specific Rules

The AI must:

• Avoid introducing unnecessary personal data.
• Avoid using production personal data in tests.
• Identify privacy implications in proposed remedies.
• Report when data retention or erasure behaviour is unclear.

10.4 Quality Gate

A privacy-sensitive change should not merge if:

• Data purpose is unclear.
• Access control is unclear.
• Retention or deletion behaviour is undefined.
• Test data contains real sensitive data without approval.

10.5 Security and Privacy Drift Addendum

For authentication, authorization and tenant-isolation changes, review must include:

• Role and permission matrix, policy definitions and deny-by-default behaviour.
• Allow paths, deny paths, cross-tenant access attempts and privilege-escalation cases.
• Tenant/workspace/org scoping in APIs, database queries, background jobs, caches, search indexes, queues, exports and admin tooling.
• Administrative, impersonation, support-access and break-glass workflows.
• Authorization, isolation, adversarial and regression tests.

For sensitive-data, logging and audit changes, review must include:

• Data classification, minimization, masking, encryption, retention, erasure and export controls.
• Logs, metrics, traces, analytics, screenshots and error reports checked for secret or sensitive-data leakage.
• Audit event actor, subject, action, timestamp, correlation ID, before/after values and tamper-resistance expectations.
• Privacy notices, consent/legal basis and data-subject rights where relevant.
• Test data, fixtures, screenshots and recordings checked for real sensitive data.

A security/privacy-sensitive change should not merge or release if deny paths, tenant boundaries, sensitive-data exposure, audit evidence or required adversarial tests are unclear or unverified.

11. Control 8: Release Discipline

Release discipline controls how changes reach users.

11.1 Objectives

Release discipline should ensure:

• Only reviewed and verified changes are released.
• Release scope is understood.
• Rollback or forward-fix options exist.
• Users and operators know what changed.
• Migrations are safe.
• Monitoring is ready.

11.2 Required Practices

• Maintain a clear release process.
• Use versioning appropriate to the product.
• Record release notes.
• Separate deploy from release when feature flags make that useful.
• Plan rollback for risky changes.
• Smoke test after deployment.
• Monitor error rates and critical workflows after release.

11.3 AI-Specific Rules

The AI must:

• Identify when a change has release implications.
• Note required migration or configuration steps.
• Avoid assuming deployment is automatic.
• Avoid claiming production success without deployment evidence.
• Report feature flags or rollout controls needed.

11.4 Quality Gate

A change should not release if:

• Migration risk is unmanaged.
• Rollback is impossible or unplanned for a risky change.
• Configuration is missing.
• Operators do not know what changed.
• Critical monitoring is absent.

12. Control 9: Documentation and Contract Alignment

Documentation is a control when it describes contracts, operations or decisions.

12.1 Objectives

Documentation should keep aligned:

• Requirements.
• Architecture.
• API contracts.
• Data model.
• User workflows.
• Operational procedures.
• Security assumptions.
• Release notes.

12.2 Required Practices

• Update documentation when public behaviour changes.
• Update API docs when request or response shapes change.
• Update architecture records when design decisions change.
• Update runbooks when operational steps change.
• Keep examples accurate.

12.3 AI-Specific Rules

The AI must:

• Check whether docs need updates after code changes.
• Avoid documenting behaviour that was not implemented.
• Avoid changing docs to hide implementation drift.
• Mark unresolved assumptions clearly.

12.4 Quality Gate

A change should not merge if:

• Documentation contradicts implementation.
• Public API docs are stale.
• Required configuration is undocumented.
• Operational steps are hidden.

12.5 API and Database Drift Addendum

For API changes, documentation and contract alignment must include:

• Public route and handler behaviour.
• Request and response schemas.
• Status codes, headers, pagination, sorting and filtering.
• Error codes and retry semantics.
• OpenAPI or equivalent contract documentation.
• Generated clients, SDKs, mocks and typed consumers.
• Compatibility, versioning, deprecation and migration guidance.

For database changes, documentation and operational alignment must include:

• Migration ordering and deployment ordering.
• Rollback or forward-fix strategy.
• Backfill plan, batching, locking and expected runtime when data movement is needed.
• Data model, ORM/query layer and API resource mapping.
• Index, constraint, uniqueness and foreign-key effects.
• Tenant isolation, audit, soft delete, retention and erasure behaviour.
• Release notes, monitoring and runbook updates for risky migrations.

A coupled API/database change should not merge or release if the API contract, database migration, generated clients, tests, documentation and release plan disagree.

13. Control 10: Dependency Management

Dependencies introduce supply-chain and maintenance risk.

13.1 Objectives

Dependency controls should ensure:

• Dependencies are necessary.
• Versions are tracked.
• Licenses are acceptable.
• Known vulnerabilities are addressed.
• Updates are tested.
• The project can be built reproducibly.

13.2 Required Practices

• Prefer existing dependencies before adding new ones.
• Add dependencies only for clear value.
• Pin versions through lockfiles where appropriate.
• Review license and security impact.
• Run tests after dependency changes.
• Keep dependency updates separate from unrelated feature work where possible.

13.3 AI-Specific Rules

The AI must:

• Not invent package names.
• Not add dependencies without checking project conventions.
• Not bypass package management.
• Explain why a new dependency is needed.
• Report network or installation failures honestly.

13.4 Quality Gate

A dependency change should not merge if:

• The dependency is unnecessary.
• Security or license status is unacceptable.
• Lockfiles are inconsistent.
• Tests were not run after the change.

14. Control 11: Observability and Operations

Software must be diagnosable after release.

14.1 Objectives

Operational controls should ensure:

• Important failures are logged.
• Metrics exist for critical behaviours.
• Alerts exist for critical failures.
• Operators can trace incidents.
• Rollback or recovery procedures exist.

14.2 Required Practices

For important backend or workflow changes, consider:

• Structured logs.
• Error tracking.
• Metrics.
• Health checks.
• Audit events.
• Admin visibility.
• Runbook updates.

14.3 AI-Specific Rules

The AI must:

• Identify when observability is needed.
• Avoid excessive or sensitive logging.
• Include error context that helps diagnosis.
• Report when operational visibility is missing.

14.4 Quality Gate

A critical change should not release if:

• Failures would be silent.
• Operators cannot diagnose issues.
• Sensitive data would appear in logs.
• No alert exists for high-impact failures.

15. Control 12: Change Size and Scope Control

AI can produce large changes quickly. This makes scope control essential.

15.1 Objectives

Scope control should ensure:

• Changes remain reviewable.
• Risk remains bounded.
• The goal is not diluted.
• Reviewers can understand the diff.

15.2 Required Practices

• Prefer small pull requests.
• Separate refactoring from feature changes where possible.
• Separate dependency updates from behaviour changes where possible.
• Keep formatting-only changes isolated.
• Avoid drive-by cleanup.

15.3 AI-Specific Rules

The AI must:

• Avoid broad rewrites unless explicitly requested.
• Explain why each changed file was touched.
• Stop and ask before expanding scope materially.
• Preserve local style.

15.4 Quality Gate

A change should be split if:

• Reviewers cannot understand it in one pass.
• It mixes unrelated concerns.
• It changes architecture and feature behaviour together without need.
• It includes formatting churn across unrelated files.

16. Control Matrix

Use this matrix to decide which controls apply.

Change type	Required controls
Small bug fix	Version control, focused test, review, CI.
New feature	Version control, tests, CI, review, documentation, release notes.
Database change	Migration test, rollback plan, schema review, data protection review where relevant.
API change	Contract update, client impact review, tests, documentation.
Coupled API/database change	API contract update, migration safety review, generated-client check, consumer impact review, deployment-ordering plan, tests and release notes.
Authentication or authorization	Security review, adversarial tests, code review, CI.
Tenant isolation or permission change	Role/permission matrix review, cross-tenant deny tests, query-scope review, audit review and security review.
Sensitive data, logging or audit change	Privacy review, data-classification check, log/redaction check, audit-event review, retention/erasure review and adversarial tests where relevant.
User-facing UI change	UI testing, accessibility check, review, documentation if workflow changes.
Architecture change	Architecture record, review, tests or proof-of-concept, release planning.
Dependency change	Dependency review, lockfile check, CI, security scan where applicable.
Production release	CI, release notes, deployment plan, smoke test, monitoring, rollback plan.

17. AI-Assisted Change Acceptance Checklist

Before accepting an AI-assisted change, check:

• The goal is clear.
• The diff is scoped to the goal.
• The AI inspected real project files.
• Assumptions are stated.
• Tests or checks were run.
• Test failures are explained.
• Security impact was considered.
• Privacy impact was considered.
• Documentation impact was considered.
• Release impact was considered.
• The change can be reviewed.
• The change can be reverted or repaired.

18. Final Report Template

Each AI-assisted change should produce a final report:

Goal:
  [What the change was meant to achieve.]

Scope:
  [What was touched.]

Changes:
  [Summary of implementation.]

Engineering controls applied:
  [Version control, tests, CI, review, architecture record, security review, release checks.]

Verification:
  [Commands, checks and results.]

Security/privacy impact:
  [None, or describe.]

Documentation/release impact:
  [None, or describe.]

Residual risk:
  [Known uncertainty.]

Reviewer focus:
  [Where human review should pay attention.]

19. Recommended Default Prompt

Use this prompt when asking an AI to perform software development work under engineering controls:

Use the HERR Loop and respect the engineering controls.

Goal:
[state the goal]

Scope:
[state scope]

Acceptance criteria:
[state criteria]

Engineering controls:
- Use version-control awareness.
- Add or run relevant tests.
- Preserve existing architecture unless a change is required.
- Identify security, privacy, documentation and release impacts.
- Keep the diff scoped and reviewable.
- Report verification and residual risk.

20. Multi-Cycle and Evidence Controls

Projects adopting run eval 30 cycles must treat the number as a maximum and enforce run-level time, diff-size, cost and checkpoint limits. Run/cycle state belongs in the schema-2 HERR_Cycles/cycle-ledger.jsonl, not in chat memory. Atomic claims, unique IDs, leases, recovery, one terminal event per cycle and explicit run closure are CI-verifiable controls. A run that finished the work it registered, below budget and with nothing unresolved, closes scope-complete; a run that ran out of evidence closes exhaustion, and one waiting on a human closes owner-gate.

Terms, gaps, gates and tripwires use stable IDs. Objective evidence records units, targets, a minimum meaningful change and uncertainty. baseline-established and gap-closed are distinct from no-change and excluded from exhaustion. Every remedy records whether it was accepted, reverted, retained with justification or isolated pending an owner; degraded work is restored to a verified safe checkpoint when feasible.

Persist only decisive sanitized evidence or an access-controlled reference. Never place secrets, authentication material, unnecessary personal data, production payloads, full raw logs or prompt transcripts in cycle records. Evidence classification, access, retention and erasure follow the project's data policy.

CI should run the static bundle verifier and negative state-machine tests. Tests must reject missing fields, duplicate or mismatched IDs, invalid event order, duplicate terminal events, incomplete gate/tripwire results and false stop conditions.

21. Model and Decision Governance

For a model, score, rank, recommendation or automated decision, controls must cover explicit model version, input provenance, evidence-based calibration, reproducibility, explainability, boundary tests, privacy/security/fairness review and human oversight. The model also needs outcome feedback: stored decisions must be compared with real results against a baseline and feed a governed recalibration path. Missing outcome feedback is a gap, not a reason to trust a static score.

HERR heuristic scores are ordinal diagnostics with project anchors. Their composite is never a release or completion gate and is meaningful only with coverage and a locked applicability set.

22. Best-Practice Assessment

These controls are best practice for AI-assisted software development because they compensate for the main weaknesses of AI-generated work:

• AI can produce plausible but wrong code, so tests and review are required.
• AI can drift across architecture and documentation, so architecture records and documentation alignment are required.
• AI can make broad changes quickly, so scope control is required.
• AI can miss security and privacy implications, so explicit review gates are required.
• AI can claim more certainty than evidence supports, so CI, verification and final reporting are required.

The correct model is not:

AI writes code -> ship it

The correct model is:

AI assists development -> engineering controls verify, constrain and release the work

That is the robust pattern.