chore: add c4 spec

2026-06-06 19:22:58 +08:00
commit ca9f1242f8
11 changed files with 2490 additions and 0 deletions
@@ -0,0 +1,30 @@
+# ADR 0002: Project Lock Is Owned By AgentRun
+
+## Status
+
+Accepted.
+
+## Context
+
+The older model effectively made a long-lived teacher/project session hold the project lock. That breaks down once project groups become long-lived collaboration spaces and Claude is invoked on demand.
+
+We need to prevent concurrent Claude executions from modifying the same project, while still allowing teachers to keep discussing the project in the group.
+
+## Decision
+
+Use a project-scoped lock whose owner is the current `AgentRun`.
+
+```text
+scope = project_id
+owner = run_id
+lifetime = one Claude processing task
+```
+
+The lock is acquired after `@Claude` creates an `AgentRun`, and released when the run completes, fails, times out or is canceled.
+
+## Consequences
+
+- Group membership, teacher identity and Claude provider session do not directly own the lock.
+- The same long-lived `AgentSession` can be reused by many runs.
+- `cancel current processing` releases the lock by `run_id`.
+- Admin `force release` remains an exceptional operation for stuck runs or lost processes.