初始化 Makelore 项目协作文档

需求：为客户端修复任务建立独立 worktree 所有权与项目记忆门禁。

实现：引入标准 .project-docs 模板，不修改现有客户端业务代码。

.project-docs/00-brief/project-positioning.md

@@ -0,0 +1,29 @@
+# Project Positioning
+
+## One-line Positioning
+
+This project is {one-line project positioning}.
+
+## Primary Goal
+
+The project exists to {primary project goal}.
+
+## Target Users / Consumers
+
+- {primary user or consumer}
+
+## Non-goals
+
+This project does not aim to {non-goal or boundary}.
+
+## Core Constraints
+
+- {core constraint}
+
+## Quality Bar
+
+A good solution should {quality bar}.
+
+## Last Reviewed
+
+{YYYY-MM-DD}

.project-docs/00-brief/success-criteria.md

@@ -0,0 +1,17 @@
+# Success Criteria
+
+## Project Success
+
+- {observable project-level success condition}
+
+## Task Completion Standard
+
+- {condition that means a task is complete}
+
+## Quality Checks
+
+- {verification command, review expectation, or acceptance check}
+
+## Last Reviewed
+
+{YYYY-MM-DD}

.project-docs/05-agent-entry/concurrent-task-gate.md

@@ -0,0 +1,27 @@
+# Concurrent Task Gate
+
+Complete this gate before the Planning Gate.
+
+## Invariants
+
+- One active task owns one worktree.
+- Concurrent tasks use different branches and worktrees.
+- Never stash, reset, move, delete, or adopt unknown work automatically.
+- Feature tasks write only their own task record and uniquely named supporting records.
+
+## Required Output
+
+- Task ID:
+- Mode: Feature | Integration
+- Branch:
+- Worktree:
+- Base commit:
+- Ownership result: Claimed | Resumed | Isolated | Blocked
+- Other active local tasks:
+
+## Block Conditions
+
+- The worktree belongs to another active task and isolation did not succeed.
+- An unowned worktree contains staged, unstaged, or untracked changes.
+- No reliable committed base was selected for a new worktree.
+- The runtime cannot keep later Git and file operations rooted in the isolated worktree.

.project-docs/05-agent-entry/context-checklist.md

@@ -0,0 +1,15 @@
+# Context Checklist
+
+Before planning, confirm:
+
+- I know the task ID, mode, branch, worktree, base commit, and ownership result.
+- I read the active task record and know its scope.
+- I know what this project is and what it is not.
+- I treat current-state as the last integrated snapshot rather than live concurrent state.
+- I checked active decisions and the architecture overview.
+- I identified task-specific docs that need deeper reading.
+- I inspected other local task records through `task_context.py status --json`.
+- I assessed code overlap separately from semantic or decision conflict.
+- I reported missing peer records as unknown coordination state.
+- I can name unknown, stale, or conflicting information.
+- I know which updates remain task-scoped and which require Integration Gate.

.project-docs/05-agent-entry/integration-gate.md

@@ -0,0 +1,14 @@
+# Integration Gate
+
+Use this gate to promote completed task facts into canonical project memory.
+
+## Requirements
+
+- Run in an exclusively owned integration worktree.
+- Hold the repository integration lock.
+- Verify the task commits being integrated are present.
+- Review task promotion candidates and semantic conflicts.
+- Ask before changing architecture direction, product behavior, or accepted decisions.
+- Record source task or merge commits under `Integrated Through` in `current-state.md`.
+
+Do not resolve meaningful document conflicts with `ours`, `theirs`, or union merge rules.

.project-docs/05-agent-entry/memory-index.md

@@ -0,0 +1,23 @@
+# Memory Index
+
+Use this as the high-density entry point after the Concurrent Task Gate establishes task identity and worktree ownership.
+
+## Startup Set
+
+- Active task: `.project-docs/30-worklog/tasks/{task_id}.md`
+- Project identity: `.project-docs/00-brief/project-positioning.md`
+- Integrated state: `.project-docs/30-worklog/current-state.md`
+- Decision list: `.project-docs/10-decisions/decision-index.md`
+- System shape: `.project-docs/20-architecture/system-overview.md`
+
+## Recall Pointers
+
+- Evidence-heavy bugs, experiments, investigations: `.project-docs/50-evidence/evidence-index.md`
+- Workflow lessons and repeated agent mistakes: `.project-docs/60-reflection/reflection-index.md`
+- Pending promises, loops, timed follow-ups: `.project-docs/80-commitments/commitments.md`
+- Integrated stale items: `.project-docs/90-maintenance/stale-items.md`
+- Task-scoped conflicts: `.project-docs/90-maintenance/conflicts/{task_id}-<slug>.md`
+
+## Loading Rule
+
+Keep this file short. Add shared pointers only during Integration Gate. Feature tasks keep their working context and promotion candidates in their own task record.

.project-docs/05-agent-entry/planning-gate.md

@@ -0,0 +1,66 @@
+# Planning Gate
+
+A coding agent must complete this gate after the Concurrent Task Gate and before writing an implementation plan.
+
+## Peer Scope Check
+
+Run `task_context.py status --json`. For each other owner, read only the peer task record at `Path(owner.worktree) / owner.task_record`. Use its `Scope`, `Intent And Constraints`, and `Promotion Candidates` sections to assess overlap.
+
+Do not inspect or modify arbitrary uncommitted files in another task's worktree. Report a missing or unreadable peer record as unknown coordination state; do not silently treat it as no overlap. Code-path overlap alone is a warning. Block when semantic decisions conflict or unresolved overlap could change the plan.
+
+## Required Output
+
+```md
+## Project Context Loaded
+
+Task context:
+- Task ID:
+- Mode:
+- Branch:
+- Worktree:
+- Base commit:
+- Other active local tasks:
+- Overlap or semantic-conflict assessment:
+
+Read:
+- {file path}
+
+Relevant understanding:
+- Project goal:
+- Current integrated focus:
+- Active task scope:
+- Active constraints:
+- Decisions affecting this task:
+- Evidence, reflections, or commitments affecting this task:
+- Files or modules likely involved:
+- Unknowns, stale docs, or conflicts:
+
+Gate result:
+- Passed or Blocked
+```
+
+## Pass Criteria
+
+The gate passes only when:
+
+- task identity and worktree ownership are resolved
+- the active task record exists and matches the owner task ID
+- required documents were read
+- task-relevant decisions were checked
+- relevant evidence, reflection, and commitment indexes were checked when applicable
+- other active local task scopes were assessed
+- stale, unknown, or conflicting context was called out
+- the plan respects project positioning and constraints
+
+## Block Criteria
+
+Block planning when:
+
+- worktree ownership is unresolved
+- an unowned worktree is dirty and has not been explicitly adopted by a human
+- required worktree isolation failed or later operations cannot remain rooted there
+- required documents are missing or a concurrency upgrade is incomplete
+- current integrated state conflicts with the user request
+- an existing decision appears to be violated
+- semantic decisions conflict across active tasks
+- the task changes project positioning or architecture without human confirmation

.project-docs/05-agent-entry/read-before-coding.md

@@ -0,0 +1,7 @@
+# Read Before Coding
+
+Before editing code, verify that the implementation plan passed both the Concurrent Task Gate and Planning Gate. Confirm the task ID, branch, worktree, owner, and active task record still match.
+
+If the plan is stale, ownership changed, or new peer scope affects the plan, return to `read-before-planning.md`. Keep every later file and Git operation rooted in the owned worktree.
+
+Read the source files directly related to the target modules. Record feature progress, discovered constraints, verification, and promotion candidates in `.project-docs/30-worklog/tasks/{task_id}.md`; leave canonical project memory to Integration Gate.

.project-docs/05-agent-entry/read-before-planning.md

@@ -0,0 +1,24 @@
+# Read Before Planning
+
+Before writing any coding plan, follow this order:
+
+1. Run the Concurrent Task Gate.
+2. Read memory-index.md.
+3. Read the active task record at `.project-docs/30-worklog/tasks/{task_id}.md`.
+4. Read project-positioning.md.
+5. Read current-state.md as the integrated snapshot.
+6. Read decision-index.md and system-overview.md.
+7. Inspect other locally active task scopes.
+
+Then read additional files when relevant:
+
+- Architecture or refactor task: `.project-docs/20-architecture/module-map.md` and `.project-docs/20-architecture/data-flow.md`
+- Product or behavior task: `.project-docs/40-domain/business-rules.md` and `.project-docs/00-brief/success-criteria.md`
+- Ambiguous terms: `.project-docs/40-domain/glossary.md`
+- Decision-sensitive task: referenced accepted ADRs in `.project-docs/10-decisions/`
+- Evidence-heavy bug, investigation, or experiment: `.project-docs/50-evidence/evidence-index.md`
+- Repeated workflow issue, skipped gate, or skill/script candidate: `.project-docs/60-reflection/reflection-index.md`
+- Follow-up, loop, timed check, or restart-point task: `.project-docs/80-commitments/commitments.md`
+- Suspicious integrated context: `.project-docs/90-maintenance/stale-items.md`
+
+Treat shared files as the last integrated snapshot, not as live state from concurrent feature tasks. Do not write a plan until both the Concurrent Task Gate and Planning Gate pass.

.project-docs/10-decisions/adr-template.md

@@ -0,0 +1,33 @@
+# ADR-{number}: {decision title}
+
+## Status
+
+Proposed
+
+## Date
+
+{YYYY-MM-DD}
+
+## Context
+
+{context that made the decision necessary}
+
+## Decision
+
+{decision made}
+
+## Rationale
+
+{why this option was chosen}
+
+## Consequences
+
+- {positive or negative consequence}
+
+## Supersedes
+
+- {older ADR or decision, if any}
+
+## Related
+
+- {related doc or source file}

.project-docs/10-decisions/decision-index.md

@@ -0,0 +1,22 @@
+# Decision Index
+
+## Active Decisions
+
+| ID | Decision | Status | Date | Applies To | Detail |
+|---|---|---|---|---|---|
+
+## Superseded Decisions
+
+| ID | Decision | Superseded By | Date |
+|---|---|---|---|
+
+## Decision Criteria
+
+Create or update an ADR when a choice affects:
+
+- project positioning
+- architecture boundaries
+- public behavior
+- data model
+- long-term maintenance
+- user-facing workflow

.project-docs/20-architecture/data-flow.md

@@ -0,0 +1,18 @@
+# Data Flow
+
+## Primary Flows
+
+| Flow | Source | Destination | Notes |
+|---|---|---|---|
+
+## State Ownership
+
+- {state owner or persistence rule}
+
+## External Interfaces
+
+- {API, file, service, or user-facing boundary}
+
+## Last Updated
+
+{YYYY-MM-DD}

.project-docs/20-architecture/module-map.md

@@ -0,0 +1,18 @@
+# Module Map
+
+## Source Layout
+
+| Path | Responsibility | Owner Notes |
+|---|---|---|
+
+## Dependency Direction
+
+- {dependency direction rule}
+
+## Risky Or Sensitive Areas
+
+- {module or path that needs extra care}
+
+## Last Updated
+
+{YYYY-MM-DD}

.project-docs/20-architecture/system-overview.md

@@ -0,0 +1,22 @@
+# System Overview
+
+## Current Architecture
+
+{short description of the current system shape}
+
+## Main Components
+
+| Component | Responsibility | Notes |
+|---|---|---|
+
+## Important Boundaries
+
+- {boundary that future work should respect}
+
+## Related Decisions
+
+- {ADR reference}
+
+## Last Updated
+
+{YYYY-MM-DD}

.project-docs/30-worklog/current-state.md

@@ -0,0 +1,36 @@
+# Current State
+
+This file is the integrated default-branch snapshot. Feature tasks record progress in `30-worklog/tasks/{task_id}.md` and propose canonical changes for the Integration Gate. Feature tasks must not rewrite this file; it changes only in integration mode.
+
+## Integrated Through
+
+- {source task or merge commit}
+
+## Current Focus
+
+The project is currently focused on {current focus}.
+
+## Recently Completed
+
+- {YYYY-MM-DD}: {completed work summary}
+
+## In Progress
+
+- {in-progress item}
+
+## Next Recommended Steps
+
+1. {next recommended step}
+2. {next recommended step}
+
+## Open Questions / Blockers
+
+- {open question or blocker}
+
+## Risky Areas
+
+- {risky area}
+
+## Last Updated
+
+{YYYY-MM-DD}

.project-docs/30-worklog/session-notes/.gitkeep

@@ -0,0 +1 @@
+

.project-docs/30-worklog/task-history.md

@@ -0,0 +1,10 @@
+# Task History
+
+## Completed Tasks
+
+| Date | Task | Outcome | Docs Updated |
+|---|---|---|---|
+
+## Notes
+
+This is legacy integrated history. Feature tasks must not append here. Record new work in `30-worklog/tasks/{task_id}.md`; an integration workflow may render or summarize accepted history later.

.project-docs/30-worklog/task-template.md

@@ -0,0 +1,35 @@
+# Task: {title}
+
+## Identity
+
+- Task ID: {task_id}
+- Mode: {mode}
+- Branch: {branch}
+- Worktree: {worktree}
+- Base commit: {base_commit}
+- Owner: {owner}
+- Status: Planning
+
+## Scope
+
+- {scope}
+
+## Intent And Constraints
+
+- {intent_or_constraint}
+
+## Outcome
+
+- Not completed.
+
+## Verification
+
+- Not run.
+
+## Follow-ups
+
+- None recorded.
+
+## Promotion Candidates
+
+- None recorded.

.project-docs/40-domain/business-rules.md

@@ -0,0 +1,13 @@
+# Business Rules
+
+## Durable Rules
+
+- {business or product rule}
+
+## Open Questions
+
+- {rule that needs human confirmation}
+
+## Last Reviewed
+
+{YYYY-MM-DD}

.project-docs/40-domain/glossary.md

@@ -0,0 +1,4 @@
+# Glossary
+
+| Term | Meaning | Notes |
+|---|---|---|

.project-docs/50-evidence/evidence-index.md

@@ -0,0 +1,12 @@
+# Evidence Index
+
+Use this index for searchable, traceable evidence records.
+
+| Date | Topic | Status | Source | Detail |
+|---|---|---|---|---|
+
+## When To Add Evidence
+
+Add a topic file when a task depends on logs, commits, test output, external docs, bug reproduction, experiments, or postmortem-level reasoning.
+
+Keep task progress in `30-worklog/`; keep reusable workflow lessons in `60-reflection/`.

.project-docs/50-evidence/topic-template.md

@@ -0,0 +1,35 @@
+# Evidence Topic: {short title}
+
+## Metadata
+
+- Date:
+- Status: Active | Resolved | Superseded | Stale
+- Scope:
+- Confidence: Fact | Inference | Hypothesis
+- Source:
+- Last verified:
+- Stale trigger:
+
+## Question
+
+What needed evidence?
+
+## Evidence
+
+- Commit:
+- Files:
+- Commands:
+- Logs:
+- External source:
+
+## Finding
+
+What does the evidence support?
+
+## Impact
+
+What future planning or implementation should this affect?
+
+## Open Items
+
+- 

.project-docs/50-evidence/topics/.gitkeep

@@ -0,0 +1 @@
+

.project-docs/60-reflection/cases/.gitkeep

@@ -0,0 +1 @@
+

.project-docs/60-reflection/reflection-index.md

@@ -0,0 +1,12 @@
+# Reflection Index
+
+Use this index for second-order workflow lessons.
+
+| Date | Reflection | Trigger | Action | Detail |
+|---|---|---|---|---|
+
+## When To Reflect
+
+Create a reflection only when work reveals a reusable lesson: skipped gates, repeated mistakes, durable debugging patterns, ineffective plans, human corrections, or candidates for new scripts or skills.
+
+Routine task completion belongs in `30-worklog/task-history.md`.

.project-docs/60-reflection/reflection-template.md

@@ -0,0 +1,54 @@
+# Reflection: {short title}
+
+## Trigger
+
+What happened?
+
+## Expected Behavior
+
+What should the agent or workflow have done?
+
+## Actual Behavior
+
+What happened instead?
+
+## Root Cause
+
+Classify the cause:
+
+- Missing trigger
+- Weak gate
+- Stale docs
+- Unclear ownership
+- Missing script
+- Human decision not promoted
+- Agent ignored context
+- Other:
+
+## Evidence
+
+- Commit:
+- Files:
+- Session/thread:
+- Command output:
+- Docs involved:
+
+## Lesson
+
+What should future agents learn?
+
+## Action
+
+Choose one:
+
+- Update docs
+- Update gate
+- Create script
+- Create/update skill
+- Add check/eval
+- Ask human to decide
+- No action
+
+## Promotion
+
+Should this become a rule, ADR, architecture note, task-history entry, skill change, or script?

.project-docs/60-reflection/skill-candidates.md

@@ -0,0 +1,10 @@
+# Skill Candidates
+
+Track repeated workflow lessons that may deserve a reusable skill, script, or stronger gate.
+
+| Date | Candidate | Evidence | Proposed Action | Status |
+|---|---|---|---|---|
+
+## Promotion Rule
+
+If the same reflection pattern appears repeatedly or prevents a serious mistake, propose a skill update, new skill, script, or deterministic check.

.project-docs/80-commitments/commitments.md

@@ -0,0 +1,10 @@
+# Commitments
+
+Track future-facing memory: promised follow-ups, unfinished loops, timed checks, and restart points.
+
+| Date | Commitment | Trigger / Due | Owner | Status | Next Action |
+|---|---|---|---|---|---|
+
+## Use
+
+Record only commitments that should affect future sessions. Routine next steps can stay in `30-worklog/current-state.md`.

.project-docs/90-maintenance/doc-update-policy.md

@@ -0,0 +1,42 @@
+# 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.

.project-docs/90-maintenance/stale-items.md

@@ -0,0 +1,16 @@
+# Stale Items
+
+This is the integrated registry of stale or conflicting canonical memory. Update it only in Integration Gate.
+
+## Possibly Stale Or Conflicting
+
+| Date | Document | Issue | Source Task | Needed Confirmation |
+|---|---|---|---|---|
+
+## Missing Context
+
+- {missing information that affects future planning}
+
+## Feature Task Routing
+
+A feature task records new uncertainty in its own task record. When a separate conflict record is needed, write `90-maintenance/conflicts/{task_id}-<slug>.md`; do not append concurrent feature work here.