# Rule: AI behavior

Rationale and mental model: [docs/workflow/ai-principles.md](../docs/workflow/ai-principles.md).

## Constraints

AI executes within explicit repository constraints:

- Read `AGENTS.md`, `rules/`, current commit plan batch, and accepted ADRs first
- Generate docs before code
- Scaffold only approved directory structure
- Stop after the planned batch
- Do not add speculative frameworks, utilities, or files without clear need

## ADR significance scan

Before routine implementation, scan proposals for ADR significance — see `rules/10-adr-significance-scan.md`.

If a change appears ADR-worthy, ask whether to create a new ADR, supersede an existing one, or proceed because the decision is already covered.

## A2C pre-commit hooks

Follow `rules/12-a2c-pre-commit-hooks.md`:

- **Bootstrap:** add `a2c-pre-commit-hooks` (tag-pinned) and `check-changelog` to `.pre-commit-config.yaml`
- **Edit config:** preserve A2C hooks entry and required hook ids; add only non-conflicting stack hooks
- **Exceptions:** cite a project ADR or propose one — do not silently remove required hooks

## Changelog

Follow `rules/11-changelog-policy.md`:

- **Bootstrap:** create root `CHANGELOG.md` from `templates/changelog/CHANGELOG-template.md` if missing
- **Release-worthy work:** propose `[Unreleased]` updates; apply when approved
- **Release flow:** ensure the version entry matches semver and notable changes
- **Routine internal work:** do not update changelog unless release-relevant

## External web sources

Follow `rules/15-web-source-tags.md` when adding external references to ADRs or docs under `docs/`:

- Use `[web:NNN]` tags with entries in `docs/web-source-mapping.md`
- **Intake:** proposals from other tools may use footnotes, raw URLs, or foreign tags — **normalize to A2C format before commit** (see [prompts/phases/adr-create-update.md](../prompts/phases/adr-create-update.md))
- Run `python scripts/check_web_source_tags.py` before committing doc changes
- On lint failure for unmapped tags, run [prompts/maintenance/web-source-recovery.md](../prompts/maintenance/web-source-recovery.md) (propose only; human confirms)

## Product architecture

Follow `rules/14-product-architecture.md` when bootstrapping or editing **`a2c-workflow`** / **`a2c-vscode-extension`**:

- **Two repos only** for the product; AI workflows in **`a2c-workflow`** (`a2c_core`)
- **Three packages** (`a2c_core`, `a2c_cli`, `a2c_tui`) — lockstep versioning
- **Extension** thin client with bundled CLI — no engine logic in extension code
- **Implement product:** one milestone per batch — `docs/architecture/implementation-plan.md`, `package-boundaries.md`, `initial-contracts.md`

## CI release flow

Follow `rules/13-ci-release-flow.md`:

- **Bootstrap:** add `scripts/bump_release.py`, `scripts/verify_release_version.py`, and CI `release:verify` from reference repos/templates
- **Edit CI / release scripts:** preserve bump → ff-merge `master` → push `vX.Y.Z` → verify semantics
- **Prepare release:** curate `[Unreleased]`; use `bump_release.py` with maintainer-confirmed bump level
- **Fundamental changes:** propose an ADR — do not silently change release policy
- **Tags:** do not create tags that bypass `verify_release_version.py` unless explicitly asked

## When uncertain

1. State what is unknown
2. Propose options with trade-offs
3. Prefer updating docs or a Proposed ADR over guessing
4. Do not proceed with implementation until the contract is clear

## ADR edits (mandatory)

- Accepted/Rejected ADRs are **immutable in substance** — see `rules/08-adr-editing-evolution.md`
- Only non-semantic maintenance (typos, broken links, same-intent paths) may be edited in place
- Meaning changes require a **new superseding ADR** — never silently rewrite Decision/Context/Consequences
- If unsure whether an edit is maintenance or semantic: **stop** and ask, or propose a superseding ADR

## Prohibited

- Big-bang generation of entire codebases
- Silent policy forks in shared workflow files
- Semantic in-place edits to Accepted/Rejected ADRs
- Bypassing git hooks unless explicitly authorized
- Bot-only Git author without human operator

## Footers

Include `AI: yes` or `AI: mixed` in commits when AI-assisted.