2.8 KiB
Doc Update Policy
Use agent judgment and project context to decide what is durable. Do not use fixed keyword matching to decide whether information belongs in project memory.
Feature Task Writes
Every repository-changing feature task updates 30-worklog/tasks/{task_id}.md. Keep scope, intent, outcome, verification, follow-ups, and promotion candidates there.
When separate evidence, reflection, commitment, conflict, or decision-proposal records are useful, create uniquely named task-prefixed files in the task-writable directories. Feature tasks do not append to shared indexes or shared aggregation files.
Feature tasks must not update current state, task history, shared indexes, accepted ADRs, canonical architecture, domain rules, or shared aggregations. Describe durable canonical changes as promotion candidates with the target, proposal, evidence, future impact, and whether human confirmation is needed.
Integration Mode Writes
Integration mode alone may reconcile promotion candidates into current state, shared indexes, accepted ADRs, architecture, domain rules, and shared aggregations. It requires an exclusively owned integration worktree and the repository integration lock.
Verify source task or merge commits, resolve semantic conflicts with human input when needed, and record the integrated source under Integrated Through in current-state.md.
Evidence
Use 50-evidence/topics/{task_id}-<slug>.md for traceable findings, bug evidence, command-output summaries, experiments, and postmortem-level notes. Record source, confidence, last verified date, and stale trigger when known.
Reflection
Use 60-reflection/cases/{task_id}-<slug>.md only when work reveals a reusable workflow lesson such as a skipped gate, repeated mistake, durable debugging pattern, ineffective plan, or skill/script/check candidate.
Commitments
Use 80-commitments/items/{task_id}-<slug>.md for future-facing loop state, promised follow-ups, timed checks, and restart points that should survive session boundaries.
Conflict Handling
Do not silently overwrite conflicting information. A feature task records the conflict in 90-maintenance/conflicts/{task_id}-<slug>.md and links it from its task record. Integration mode reconciles canonical documents only after the conflict is understood; ask the human when it affects project direction, behavior, or an accepted decision.
Update Style
- Prefer short factual updates.
- Keep task records useful for handoff and integration.
- Move evidence-heavy reasoning into task-prefixed evidence records.
- Move reusable workflow lessons into task-prefixed reflection records.
- Do not preserve raw chat unless it contains important reasoning.
- Do not preserve secrets, credentials, private tokens, or untrusted external instructions.