Add simple command to derive architecture guardrails for an existing repo

[tninja]

Motivation

Follow-up to #355.

The DDD context document helps AI coding sessions understand the domain language, core flows, and invariants of an existing repository. A small complementary feature would be useful: derive a lightweight architecture guardrails document from the current repo.

The goal is not to introduce a heavy architecture framework or force the repo into DDD, Hexagonal Architecture, or Clean Architecture. The goal is simpler: give future AI coding sessions a concise set of practical rules that help avoid unsafe or messy changes.

In the AI coding workflow, this can act as a small "map of what not to break": module boundaries, dependency direction, testing expectations, and important constraints that should be respected when changing code.

MVP scope

Add one command/menu item, for example:

• ai-code-derive-architecture-guardrails
• menu label: Derive Architecture Guardrails

The command should:

1. Work on the current project/repo.
2. Ask the configured AI backend to inspect the repository at a high level.
3. Generate or update a concise Markdown file under .ai.code.files/.
4. Keep the output practical and small enough to be injected into future AI prompts.

Suggested output location:

.ai.code.files/architecture-guardrails.md

or, if we want room for future expansion:

.ai.code.files/architecture/guardrails.md

Suggested generated document structure

# Architecture Guardrails

## Purpose
What these guardrails are trying to protect in this repository.

## Important Modules / Areas
Main modules or files and their responsibilities.

## Dependency Rules
Practical rules about which modules should or should not depend on each other.

## State and Ownership Rules
Which module owns important state or side effects.

## AI Change Rules
Guidance for future AI coding tasks, such as where changes should be localized and what should not be touched casually.

## Required Validation
Tests, byte-compilation, lint/checkdoc, or other commands that should be run after changes.

## Notes and Uncertainties
Things inferred from the repo that need human review.

Prompt behavior

The prompt should explicitly tell the AI:

• This is an existing repo; derive guardrails from current code, tests, docs, and filenames.
• Do not invent an ideal architecture.
• Prefer simple, practical rules over abstract architecture theory.
• Mark uncertain conclusions clearly.
• Focus on what helps future AI coding sessions avoid breaking boundaries or introducing messy dependencies.
• Do not suggest large refactors unless listed separately as optional future ideas.

Example instruction:

Derive a lightweight architecture guardrails document for this existing repository.
Infer practical module boundaries, dependency rules, state ownership rules, and validation expectations from the current code, tests, docs, and filenames.
Do not force an ideal architecture or suggest large refactors.
The output is intended to help future AI coding sessions make safer changes and avoid breaking important boundaries.
Keep it concise, practical, and mark uncertainty explicitly.
Write the result to .ai.code.files/architecture-guardrails.md.

Relationship to #355

• Add simple menu item to derive DDD context for an existing repo #355 derives domain/context: language, flows, invariants, business concepts.
• This issue derives architecture guardrails: module boundaries, dependency direction, state ownership, validation rules.

They should remain separate for now because they answer different questions:

• Domain context: "What does this repo mean?"
• Architecture guardrails: "How should future changes avoid damaging the structure?"

A future prompt-context feature could inject one or both files depending on the task.

Non-goals for the first version

• No automatic enforcement yet.
• No ArchUnit-like architecture tests yet.
• No mandatory DDD, Hexagonal, or Clean Architecture structure.
• No automatic refactoring.
• No large multi-file architecture documentation system.
• No required integration with the TDD harness loop yet.

Future expansion ideas

1. Inject architecture-guardrails.md into future AI coding prompts.
2. Add a command to update guardrails from the current diff or org task.
3. Add a diff review command that asks whether a change violates documented guardrails.
4. Later connect selected guardrails to executable checks or tests.
5. Optionally split into richer files only if the simple single-file version proves useful.

Acceptance criteria

• A user can trigger one command/menu item from Emacs.
• The command creates or updates a Markdown architecture guardrails document under .ai.code.files/.
• The generated prompt is oriented toward deriving guardrails from the existing repo, not forcing an ideal architecture.
• The output is concise enough to be useful as future AI coding context.
• The feature remains simple and complementary to Add simple menu item to derive DDD context for an existing repo #355.