Add architecture guardrails derivation command for existing repos

[Copilot]

This adds a lightweight repo-level command to derive architecture guardrails from the current codebase and store them under .ai.code.files/. The goal is to give future AI coding sessions a compact, practical map of module boundaries, dependency rules, ownership, and required validation without imposing a heavier architecture framework.

• New command

  • Adds ai-code-derive-architecture-guardrails as an interactive command in ai-code-discussion.el
  • Requires a git repo context
  • Creates .ai.code.files/architecture/guardrails.org if it does not already exist
  • Sends a repo-focused prompt to the configured AI backend to update that file in place

• Prompt behavior

  • Instructs the AI to infer guardrails from current code, tests, docs, and filenames
  • Explicitly avoids idealized architecture proposals and large refactor suggestions
  • Keeps the output concise and marks uncertainty explicitly
  • Targets a stable, reusable output file for future prompt injection
  • Requests Org-mode output for the guardrails document

• Menu integration

  • Adds a transient menu entry:
    • A → Derive Architecture Guardrails

• File bootstrap behavior

  • Seeds the target Org file with a compact structure:
    • Purpose
    • Important Modules / Areas
    • Dependency Rules
    • State and Ownership Rules
    • AI Change Rules
    • Required Validation
    • Notes and Uncertainties
  • Preserves existing file contents if the file already exists

• Behavioral coverage

  • Adds focused tests for:
    • file creation and prompt generation
    • non-git error handling
    • preserving existing guardrails content
    • cancellation behavior
    • menu exposure

Example prompt shape:

(ai-code-derive-architecture-guardrails)

;; prompts the backend with instructions like:
;; - derive guardrails from current code, tests, docs, and filenames
;; - do not invent an ideal architecture
;; - write/update @.ai.code.files/architecture/guardrails.org in Org-mode format

> [!WARNING]
>
>

[tninja]

@copilot I prefer to put to .ai.code.files/architecture/guardrails.org, it is a org-mode format file.

[Copilot]

Updated in 2dc0081. The guardrails file now lives at .ai.code.files/architecture/guardrails.org, uses an Org template, and the prompt/tests/README were adjusted to match.

[Copilot]

Just as a heads up, I was blocked by some firewall rules while working on your feedback. Expand below for details.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• dl.google.com
  • Triggering command: /usr/lib/apt/methods/https /usr/lib/apt/methods/https (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

[Copilot]

Pull request overview

Adds a repo-level command for deriving and maintaining concise architecture guardrails under .ai.code.files/, helping future AI coding sessions reuse project-specific boundaries and validation expectations.

Changes:

• Adds ai-code-derive-architecture-guardrails and helper functions/templates in ai-code-discussion.el.
• Exposes the command from the transient menu via C-c a A.
• Documents the workflow and adds focused ERT coverage for file creation, prompting, preservation, cancellation, and menu exposure.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.

File	Description
ai-code-discussion.el	Adds guardrails file path/template helpers and the interactive derivation command.
ai-code.el	Adds the new command to the transient menu.
README.org	Documents the repo guardrails capture workflow.
test/test_ai-code-discussion.el	Adds tests for the new command behavior and menu entry.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 2dc0081fd6

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Delay guardrails file creation until prompt is confirmed

Calling ai-code--ensure-architecture-guardrails-file before reading user input causes a filesystem side effect even when the request is canceled (for example, aborting at the Prompt: minibuffer). In a repo that does not already have this file, ai-code-derive-architecture-guardrails will still create .ai.code.files/architecture/guardrails.org, leaving the worktree dirty despite no prompt being sent; this is unexpected for a canceled action and should be gated on successful prompt confirmation.

Useful? React with 👍 / 👎.