docs: AGENTS.md — require issue tracking for discovered/fixed problems

Author: ework-agent

AGENTS.md

@@ -566,6 +566,13 @@ Every PR MUST have a corresponding devlog entry in `devlog/{YYYY-MM-DD_short-tit
 
 See `devlog/README.md` for templates and naming conventions.
 
+### 5.1.3 Problem Discovery & Fix Reporting (MANDATORY)
+
+Problems discovered or fixed while working MUST leave a trace in the issue tracker — never fixed silently and moved on.
+
+1. **Discovered a problem** (bug, defect, wrong behavior, spec violation) — whether while working on this project or any sibling project — file an issue in the project the problem belongs to: repro/steps, impact, root cause (if known), suggested fix.
+2. **Fixed a problem** — after the fix, submit an issue to the owning project recording the problem and how it was fixed. For problems in this project: https://github.com/ranxianglei/opencode-acp/issues . If the fix ships as a PR, the PR MUST reference its issue (`Fixes #N`); a bare PR without an issue is not acceptable — file the issue first, then link it. An existing PR for the fix counts, but it should carry an accompanying issue.
+
 ### 5.2 After Making Changes
 
 1. `npm run build` must pass

devlog/2026-09-06_agents-md-problem-reporting/REQ.md

@@ -0,0 +1,45 @@
+# REQ - AGENTS.md problem discovery & fix reporting clause
+
+- Task ID: `2026-09-06_agents-md-problem-reporting`
+- Home Repo: `opencode-acp`
+- Created: 2026-09-06
+- Status: InProgress
+- Priority: P2
+- Owner: ranxianglei (agent)
+- References: https://github.com/ranxianglei/billion-context/issues/584
+
+## 1. Background & Problem Statement
+
+- **Context**: Agents frequently discover problems while working, and fixes sometimes land without any issue tracking — the problem, its impact, and the fix rationale exist only in a chat thread or nowhere.
+- **Current behavior (symptom)**: AGENTS.md §5 covers workflow, git safety, and PR merge prohibition, but says nothing about problems discovered or fixed *along the way*; such fixes can be silent.
+- **Expected behavior**: A MANDATORY clause requires that every discovered problem is filed as an issue in the owning project, and every fix is followed by an issue recording the problem + fix (or a PR referencing its issue; issue first, then link). The clause references this project's GitHub address.
+- **Impact**: Traceability of all agent-driven fixes across the billion-context family.
+
+## 2. Reproduction (if applicable)
+
+N/A — documentation/policy change.
+
+## 3. Constraints & Non-Goals
+
+- **Constraints**:
+  - Backward compatibility: none (docs only).
+  - Performance requirements: n/a.
+  - Resource limits: n/a.
+- **Non-Goals** (explicitly out of scope): no code changes; no CI enforcement (policy lives in AGENTS.md); sibling repos get equivalent clauses via their own PRs (billion-context, billion-context-pi).
+
+## 4. Acceptance Criteria (must be testable)
+
+- **Correctness**:
+  - [x] AGENTS.md §5 contains a new subsection "5.1.3 Problem Discovery & Fix Reporting (MANDATORY)" covering both cases: discovered-but-unfixed → file issue; fixed → issue after fix, or PR referencing its issue (`Fixes #N`).
+  - [x] Clause references https://github.com/ranxianglei/opencode-acp/issues .
+  - [x] `./scripts/ci/check-pr.sh` passes on this branch (branch name + devlog presence).
+- **Performance / Stability**: n/a.
+- **Regression**:
+  - [x] No code changes — no test suite impact.
+
+## 5. Proposed Approach (optional)
+
+- **Affected modules & entry files**:
+  - `AGENTS.md` — new subsection §5.1.3 under §5 Contributing, between §5.1.2 (Devlog Requirement) and §5.2 (After Making Changes).
+- **Risks**: None (documentation).
+- **Rollback strategy**: Revert the single docs commit.

devlog/2026-09-06_agents-md-problem-reporting/WORKLOG.md

@@ -0,0 +1,51 @@
+# WORKLOG - AGENTS.md problem discovery & fix reporting clause
+
+- Task ID: `2026-09-06_agents-md-problem-reporting`
+- Home Repo: `opencode-acp`
+- Status: Done
+- Updated: 2026-09-06 22:25
+
+## 1. Summary
+
+- **What was done**: Added a MANDATORY subsection "5.1.3 Problem Discovery & Fix Reporting" to AGENTS.md §5 requiring issue tracking for every discovered problem and for every fix (issue first, PR references it via `Fixes #N`).
+- **Why** (sibling of issue ranxianglei/billion-context#584): fixes discovered/made by agents were not required to leave a trace in the project's issue tracker; the clause makes that mandatory and points at this project's GitHub address.
+- **Behavior / compatibility changes**: No (documentation only).
+- **Risk level**: Low.
+
+## 2. Change Log
+
+### Commits
+
+| Commit | Description |
+|--------|-------------|
+| head of this branch | docs: AGENTS.md — require issue tracking for discovered/fixed problems |
+
+### Key Files
+
+- `AGENTS.md` — new subsection §5.1.3 under §5 Contributing, between §5.1.2 (Devlog Requirement) and §5.2 (After Making Changes).
+- `devlog/2026-09-06_agents-md-problem-reporting/REQ.md`, `WORKLOG.md` — this entry (required by pr-checks CI).
+
+## 3. Design & Implementation Notes
+
+- Clause covers both directions requested in the source issue: (a) problem discovered (in this project or a sibling) → file an issue in the owning project; (b) problem fixed → after the fix, submit an issue recording problem + fix, or ship the PR referencing its issue (`Fixes #N`) — a bare PR without an issue is not acceptable; an existing PR counts but should carry an accompanying issue.
+- References https://github.com/ranxianglei/opencode-acp/issues per "agents.md 引用对应的项目地址".
+
+## 4. Testing & Verification
+
+### Build & Test Commands
+
+```sh
+./scripts/ci/check-pr.sh 2026-09-06_agents-md-problem-reporting origin/master
+```
+
+Docs-only change — build/test suite not required.
+
+### Results
+
+- **PASS/FAIL**: PASS (check-pr.sh: branch name + devlog presence verified).
+
+## 5. Risk Assessment & Rollback
+
+- **Risk points**: none.
+- **Rollback method**: revert the single docs commit.
+- **Compatibility notes**: No.