70 lines
3.4 KiB
Markdown
70 lines
3.4 KiB
Markdown
# Agent Constraints
|
|
|
|
This document records **persistent behavioral constraints** for agents working on this repository.
|
|
It is distinct from `docs/requirements-log.md`, which records **project/product requirements**.
|
|
|
|
## Scope
|
|
|
|
- Applies to all AI agents and automation that modify this repo.
|
|
- Supplements (does not replace) `docs/agents.md` and `docs/workflow.md`.
|
|
|
|
## Persistent Rules
|
|
|
|
1. **Workflow enforcement**
|
|
- Follow `docs/workflow.md` for all changes.
|
|
- Before any Gitea issue/PR/comment operation, read `docs/commands.md` and `docs/workflow.md` troubleshooting section.
|
|
- Use `tea` for Gitea operations; do not use GitHub CLI (`gh`) in this repository workflow.
|
|
- Create a Gitea issue before any code or documentation change.
|
|
- Work on a feature branch `feature/issue-{N}-{short-description}` and open a PR.
|
|
- Never commit directly to `main`.
|
|
|
|
2. **Document-first routing**
|
|
- When performing work, consult relevant `docs/` files *before* making changes.
|
|
- Route decisions to the documented policy whenever applicable.
|
|
- If guidance conflicts, prefer the stricter/safety-first rule and note it in the PR.
|
|
|
|
3. **Docs with code**
|
|
- Any code change must be accompanied by relevant documentation updates.
|
|
- If no doc update is needed, state the reason explicitly in the PR.
|
|
|
|
4. **Session-persistent user constraints**
|
|
- If the user requests that a behavior should persist across sessions, record it here
|
|
(or in a dedicated policy doc) and reference it when working.
|
|
- Keep entries short and concrete, with dates.
|
|
|
|
5. **Session start handover gate**
|
|
- Before implementation/verification work, run `python3 scripts/session_handover_check.py --strict`.
|
|
- Keep `workflow/session-handover.md` updated with a same-day entry for the active branch.
|
|
- If the check fails, stop and fix handover artifacts first.
|
|
|
|
6. **Process-change-first execution gate**
|
|
- If process/governance change is required, merge the process ticket to the feature branch first.
|
|
- Do not start code/test edits for implementation tickets until process merge evidence is confirmed.
|
|
- Subagents must be constrained to read-only exploration until the process gate is satisfied.
|
|
|
|
## Change Control
|
|
|
|
- Changes to this file follow the same workflow as code changes.
|
|
- Keep the history chronological and minimize rewording of existing entries.
|
|
|
|
## History
|
|
|
|
### 2026-02-08
|
|
|
|
- Always enforce Gitea workflow: issue -> feature branch -> PR before changes.
|
|
- When work requires guidance, consult the relevant `docs/` policies first.
|
|
- Any code change must be accompanied by relevant documentation updates.
|
|
- Persist user constraints across sessions by recording them in this document.
|
|
|
|
### 2026-02-27
|
|
|
|
- All agents must pre-read `docs/commands.md` and `docs/workflow.md` troubleshooting before running Gitea issue/PR/comment commands.
|
|
- `gh` CLI is prohibited for repository ticket/PR operations; use `tea` (or documented Gitea API fallback only).
|
|
- Session start must pass `python3 scripts/session_handover_check.py --strict`, with branch-matched entry in `workflow/session-handover.md`.
|
|
|
|
### 2026-02-27
|
|
|
|
- Apply process-change-first as an execution gate: process ticket must be merged before implementation ticket coding.
|
|
- Handover entry must record concrete `next_ticket` and `process_gate_checked`; placeholders are not allowed in strict gate.
|
|
- Before process merge confirmation, all subagent tasks must remain read-only (analysis only).
|