docs: migrate project memory governance

2026-08-30 15:31:12 +08:00
parent 7b5d855b09
commit e7aa58a203
37 changed files with 942 additions and 34 deletions
--- a/.project-docs/00-brief/project-positioning.md
+++ b/.project-docs/00-brief/project-positioning.md
@@ -0,0 +1,36 @@
+# Project Positioning
+
+## One-line Positioning
+
+LianSyn Platform 将业务人员的自然语言指令解析为标准 operation，再由控制面、平台页面和 Chrome ERP 适配器完成确定性校验与受控执行。
+
+## Primary Goal
+
+让已登记的旅游 ERP 业务在统一契约、明确授权、可审计证据和失败关闭边界内被可靠解析与执行。
+
+## Target Users / Consumers
+
+- 使用运营模板提交下单、修改、安排、生命周期和导出指令的业务人员。
+- 维护控制面、平台适配器、Chrome ERP 适配器、Schema、mapping 和业务 Skill 的工程人员。
+- 通过 AgentBus 输入任务并接收业务回执的受控外部 Agent 渠道。
+
+## Non-goals
+
+- AI Agent/Skill 不查询 ERP、不生成内部引用、不直接声明业务成功。
+- 未登记、未唯一定位或未真实验证的写能力不自动扩大执行范围。
+- 项目文档不保存本地秘密、真实客户资料、浏览器 profile 或可重建运行输出。
+
+## Core Constraints
+
+- 活动业务规则以源码、Schema、mapping、业务登记和当前发布清单为准；`archive/` 只供追溯。
+- 真实 ERP 访问或写入、任务 mutation、扩展重载、服务重启、部署和外部发送需要本轮明确授权。
+- `.project-docs/` 是唯一活动项目记忆；任务作用域与 canonical 记忆分别遵守 Feature Gate 和 Integration Gate。
+- 本地 `.env` 可存在但必须被 Git 忽略，不得读取、复制、归档或输出内容。
+
+## Quality Bar
+
+方案应保持确定性、失败关闭、最小权限、单一真相源、可恢复归档和与风险相称的自动化验证。
+
+## Last Reviewed
+
+2026-08-28
--- a/.project-docs/00-brief/success-criteria.md
+++ b/.project-docs/00-brief/success-criteria.md
@@ -0,0 +1,28 @@
+# Success Criteria
+
+## Project Success
+
+- 已登记业务能从手工输入或 AgentBus 输入稳定路由到统一 operation 契约。
+- 写能力只在唯一对象、页面身份、ownership、写前投影、明确服务端响应和 action-specific 完成凭据成立时执行。
+- 当前发布物、源码和机器可读发布清单逐文件、逐哈希一致。
+- 项目记忆能在并行任务下保持任务隔离，并只通过串行 Integration Gate 更新 canonical 状态。
+
+## Task Completion Standard
+
+- 实际范围、约束、结果、验证、后续项和 durable 结论已记录到当前任务文件。
+- 所有相关源码、契约、文档、测试和生成物保持同步；未知或未授权项明确保留为阻断或待办。
+- `maintain-project-docs` 的所有权、漂移和完成门禁通过。
+
+## Quality Checks
+
+- `node --run check:repo`
+- `node --run check`
+- `node --run test:control-plane`
+- `node --run test:legacy`
+- `node --run build`
+- 按已加载的 `maintain-project-docs` Skill 运行 `check_project_docs.py` 与当前任务的 `check_doc_drift.py`。
+- 涉及 Skill、DOCX 或 Chrome 扩展时，追加各自官方校验、渲染或包/源码逐文件比对。
+
+## Last Reviewed
+
+2026-08-28
--- a/.project-docs/05-agent-entry/concurrent-task-gate.md
+++ b/.project-docs/05-agent-entry/concurrent-task-gate.md
@@ -0,0 +1,30 @@
+# 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.
+- Keep the active task record present until ownership is released.
+- Treat `start`, `touch`, `complete`, and `release` as serialized registry transactions; lock timeout or malformed registry state blocks the gate.
+- Feature-task write boundaries in this gate supersede legacy instructions to update shared or canonical project documents.
+
+## 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.
--- a/.project-docs/05-agent-entry/context-checklist.md
+++ b/.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.
--- a/.project-docs/05-agent-entry/integration-gate.md
+++ b/.project-docs/05-agent-entry/integration-gate.md
@@ -0,0 +1,15 @@
+# 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 source task records, task-prefixed supporting records, promotion candidates, and semantic conflicts in read-only mode.
+- Write integration notes only to the integration task's own task record or `{task_id}__<slug>.md` supporting records.
+- 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.
--- a/.project-docs/05-agent-entry/memory-index.md
+++ b/.project-docs/05-agent-entry/memory-index.md
@@ -0,0 +1,30 @@
+# 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`
+
+## Project Authority Pointers
+
+- Business entry and capability status: [`agent设计规范/business-adaptation-registry.md`](../../agent设计规范/business-adaptation-registry.md)
+- Active lifecycle conclusions and immutable evidence links: [`agent设计规范/test-fixtures/lwlt-lifecycle/release-gate.md`](../../agent设计规范/test-fixtures/lwlt-lifecycle/release-gate.md)
+- Current deliverables, versions, filenames, and hashes: [`dist/release-manifest.json`](../../dist/release-manifest.json)
+- Retired Planning with Files snapshots: [`archive/project-history/2026-08-28/README.md`](../../archive/project-history/2026-08-28/README.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.
--- a/.project-docs/05-agent-entry/planning-gate.md
+++ b/.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
--- a/.project-docs/05-agent-entry/read-before-coding.md
+++ b/.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.
--- a/.project-docs/05-agent-entry/read-before-planning.md
+++ b/.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.
--- a/.project-docs/10-decisions/adr-template.md
+++ b/.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}
--- a/.project-docs/10-decisions/decision-index.md
+++ b/.project-docs/10-decisions/decision-index.md
@@ -0,0 +1,28 @@
+# Decision Index
+
+## Active Decisions
+
+| ID | Decision | Status | Date | Applies To | Detail |
+|---|---|---|---|---|---|
+| DOC-001 | `.project-docs/` is the sole active project-memory system; feature tasks own task-scoped records and Integration Gate owns canonical memory. | Active | 2026-08-28 | All repository work | [Governance](../../AGENTS.md) |
+| ARCH-001 | AI parsers provide business semantics only; platform state, ERP resolution, execution evidence, and audit remain outside the business operation. | Active | 2026-08-28 | Parser and execution architecture | [System entry](../../README.md) |
+| ROUTE-001 | The machine registry is the authority for 18 parser routes; the two passenger-list routes are Program-only. | Active | 2026-08-28 | Manual and AgentBus intake | [Machine registry](../../control-plane/src/business-routes.ts) |
+| RELEASE-001 | Current artifacts, filenames, versions, and SHA-256 values are defined only by `dist/release-manifest.json`. | Active | 2026-08-28 | Release and delivery | [Release manifest](../../dist/release-manifest.json) |
+| SAFETY-001 | Real ERP access/write, task mutation, extension reload, service restart, deployment, and external delivery require explicit task-scoped authorization. | Active | 2026-08-28 | Operations and maintenance | [Governance](../../AGENTS.md) |
+
+## Superseded Decisions
+
+| ID | Decision | Superseded By | Date |
+|---|---|---|---|
+| DOC-LEGACY-001 | Root `task_plan.md`, `findings.md`, and `progress.md` were the active project-memory system. | DOC-001 | 2026-08-28 |
+
+## 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
--- a/.project-docs/20-architecture/data-flow.md
+++ b/.project-docs/20-architecture/data-flow.md
@@ -0,0 +1,32 @@
+# Data Flow
+
+## Primary Flows
+
+| Flow | Source | Destination | Notes |
+|---|---|---|---|
+| Business directive | Manual workbench or AgentBus | Route orchestrator | Source changes input/reply adaptation, not parser or confirmation policy |
+| Parsing | Route orchestrator | AI Skill or deterministic Program parser | AI/Shadow/Auto/Program mode is frozen per task |
+| Operation | Parser | Control-plane task and confirmation | Must validate against the same final contract |
+| ERP execution | Confirmed task | Chrome extension and logged-in ERP page | Requires unique object, page identity, ownership, and write preflight |
+| Completion evidence | ERP response/requery | Control-plane receipt and business reply | Evidence is action-specific; uncertain writes fail closed |
+| Passenger workbook | Single `.xls/.xlsx` attachment | Deterministic encrypted canonical TSV | First row ignored, second row fixed header, exact leader-contact rules |
+| Confirmation export | ERP source file | Archived source plus mobile delivery artifact | Visitor XLS becomes real XLSX; other types prefer PDF |
+| Release | Editable source | `dist/release-manifest.json` and versioned artifacts | Manifest owns current hashes and filenames |
+
+## State Ownership
+
+- PostgreSQL owns durable control-plane task, session, confirmation, channel, audit, and outcome state.
+- Production attachment bytes use the configured OSS provider; normalized sensitive fields remain encrypted.
+- Chrome extension local state is bounded execution/reconciliation support, not canonical business history.
+- `.project-docs/30-worklog/tasks/` owns task-local project memory; canonical project state is an integrated projection.
+
+## External Interfaces
+
+- Operator workbench at the control-plane service.
+- AgentBus WebSocket channels and attachment delivery.
+- Logged-in ERP browser pages under the Chrome extension host permissions.
+- PostgreSQL, OSS, deployment gateway, and authenticated artifact download.
+
+## Last Updated
+
+2026-08-28
--- a/.project-docs/20-architecture/module-map.md
+++ b/.project-docs/20-architecture/module-map.md
@@ -0,0 +1,34 @@
+# Module Map
+
+## Source Layout
+
+| Path | Responsibility | Owner Notes |
+|---|---|---|
+| `agent设计规范/` | Business prompt, Skills, templates, registry, business pages, fixtures | Update business entry and Skill before downstream contracts when user fields change |
+| `schemas/` | Current parse, execution, and ERP schemas | Historical schemas belong in `archive/` |
+| `mappings/` | Current ERP fields, lifecycle, and extension-version mapping | Must stay synchronized with execution code |
+| `control-plane/` | TypeScript control plane, migrations, parser and tests | Never hand-edit `.build/` output |
+| `LianSyn-platform/` | Operator UI and external Agent parsing adapter | No task output or release packages |
+| `chrome-extension/` | Current ERP extension source | Version bump and release synchronization required for code changes |
+| `tools/` | Reusable builders, tests, diagnostics, and controlled write helpers | Tool outputs do not stay here |
+| `infra/` | Deployment, backup, restore, and gateway configuration | No local secrets or database backups |
+| `.project-docs/` | Durable task and canonical project memory | Governed by worktree ownership and Integration Gate |
+| `dist/` | Current versioned delivery artifacts | Defined by `release-manifest.json` |
+| `archive/` | Immutable dated history and evidence | Read-only authority boundary |
+
+## Dependency Direction
+
+- Business input/AgentBus → route orchestration → AI or Program parser → unified operation → control plane → Chrome extension → ERP.
+- Business source documentation → Schema/mapping/implementation/tests → versioned artifacts; generated artifacts never become editable sources.
+- Task-scoped `.project-docs` records propose durable changes; canonical documents consume them only through Integration Gate.
+
+## Risky Or Sensitive Areas
+
+- ERP write boundaries and reconciliation after uncertain responses.
+- Attachment encryption, OSS network validation, and passenger workbook normalization.
+- Cross-file release version and hash synchronization.
+- Concurrent worktree ownership and canonical document integration.
+
+## Last Updated
+
+2026-08-28
--- a/.project-docs/20-architecture/system-overview.md
+++ b/.project-docs/20-architecture/system-overview.md
@@ -0,0 +1,37 @@
+# System Overview
+
+## Current Architecture
+
+Manual or AgentBus input is routed through task-scoped AI/Shadow/Auto/Program orchestration into one validated operation contract. The control plane owns task/session/confirmation/audit state, and the Chrome extension resolves the unique ERP object, enforces page and write gates, performs native actions, and returns action-specific evidence.
+
+## Main Components
+
+| Component | Responsibility | Notes |
+|---|---|---|
+| `agent设计规范/` | Agent Prompt, five parsing Skills, business templates, business registry, and stable fixtures | Editable source for business semantics; not runtime evidence |
+| `schemas/` and `mappings/` | Parse-state, execution-state, ERP form, field, and lifecycle contracts | Current contracts only |
+| `control-plane/` | Task/session persistence, parser orchestration, confirmation, audit, AgentBus, attachments, and receipts | TypeScript source; build output goes to `.build/` |
+| `LianSyn-platform/` | Operator workbench and external parser adapter | Source and UI, not local task output |
+| `chrome-extension/ltjt-order-assistant/` | Logged-in ERP resolution, preflight, native execution, response handling, and requery | Any code change requires synchronized versioned release updates |
+| `dist/` | Versioned current deliverables and machine-readable release manifest | Not a compilation directory |
+| `.project-docs/` | Task-isolated project memory and integrated canonical context | No runtime dependency |
+| `archive/` | Date-scoped immutable history and evidence | Never defines current behavior |
+
+## Important Boundaries
+
+- AI/Program parsing and ERP resolution/execution share the final operation contract but do not share authority.
+- Platform envelope fields such as task ID, session, parser decision, confirmation, transport, and audit never enter the business operation.
+- Unknown, ambiguous, unverified, or post-write-uncertain states fail closed; automatic retries must not create duplicate writes.
+- Canonical project memory is updated only under Integration Gate; feature tasks write only their task-scoped records.
+
+## Related Decisions
+
+- DOC-001
+- ARCH-001
+- ROUTE-001
+- RELEASE-001
+- SAFETY-001
+
+## Last Updated
+
+2026-08-28
--- a/.project-docs/30-worklog/current-state.md
+++ b/.project-docs/30-worklog/current-state.md
@@ -0,0 +1,45 @@
+# 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
+
+- Commit `7b5d855b093af39bf834fab4f41f41b37be1170d` as the inspected repository baseline.
+- Integration task `20260828-migrate-project-docs-6f1a9c2d` for the project-documentation migration.
+
+## Current Focus
+
+Operate the current `0.5.157` release baseline safely, keep Program/AI routing and ERP execution boundaries synchronized, and close the remaining authorization-dependent validation gaps.
+
+## Recently Completed
+
+- 2026-08-28: Initialized `.project-docs/`, migrated durable project memory, and retired the root Planning with Files system into date-scoped history.
+- 2026-08-28: Released Chrome extension `0.5.157`, Program parser `v1.0.6`, input contract/DOCX `0.5.123`, and five business Skills `0.5.125`.
+- 2026-08-28: Added narrow shared-mother-plan whole-visitor export using `shared_plan + visitor-list + tid-only` while preserving child/independent `did+tid` behavior.
+- 2026-08-28: Restarted the standard 8786 control plane under authorization and observed AgentBus 4/4 channels ready across repeated samples.
+
+## In Progress
+
+- No separate repository feature task is recorded at this integration snapshot.
+
+## Next Recommended Steps
+
+1. With explicit authorization, run a live read-only ERP verification of the shared-mother-plan `tid-only` whole-visitor export path.
+2. With explicit authorization, perform ERP write verification for independent-order SGL/TWN and adult/child/leader headcount mappings.
+3. Design a controlled public-DNS or host-allowlist fallback for AgentBus OSS attachments without weakening private-network SSRF blocking.
+
+## Open Questions / Blockers
+
+- Shared-mother-plan whole-visitor export has historical read evidence and static coverage but lacks a fresh authorized runtime ERP read verification.
+- Independent-order SGL/TWN and four headcount categories lack authorized current-version ERP write evidence.
+- Some AgentBus OSS attachment URLs can be rejected when local DNS resolves them to private or reserved addresses.
+
+## Risky Areas
+
+- Any ERP write, uncertain post-write state, automatic retry, or scope widening.
+- Passenger workbook normalization, encrypted attachment persistence, leader-contact projection, and native ERP row capacity.
+- Release synchronization across extension source, minimum platform version, mapping, ZIP, Skills, DOCX, and `dist/release-manifest.json`.
+
+## Last Updated
+
+2026-08-28
--- a/.project-docs/30-worklog/session-notes/.gitkeep
+++ b/.project-docs/30-worklog/session-notes/.gitkeep
@@ -0,0 +1 @@
+
--- a/.project-docs/30-worklog/task-history.md
+++ b/.project-docs/30-worklog/task-history.md
@@ -0,0 +1,9 @@
+# Task History
+
+This is integrated history. Feature tasks write only their task-scoped records; Integration Gate updates this file when a concise milestone remains useful.
+
+| Date | Milestone | Result | Detail |
+|---|---|---|---|
+| 2026-08-28 | Project documentation migration | `.project-docs/` became the sole active project-memory system; legacy root planning files were preserved in date-scoped history. | [Integration task](tasks/20260828-migrate-project-docs-6f1a9c2d.md) |
+| 2026-08-28 | AgentBus reconnect | Authorized control-plane restart completed; database, migration 014, and 4/4 channels were repeatedly ready. | [Archived legacy progress](../../archive/project-history/2026-08-28/legacy-planning-with-files-progress-final.md) |
+| 2026-08-28 | Shared mother-plan whole-visitor export | Released strict `shared_plan + visitor-list + tid-only` routing and execution boundaries in extension `0.5.157`. | [Release gate](../../agent设计规范/test-fixtures/lwlt-lifecycle/release-gate.md) |
--- a/.project-docs/30-worklog/task-template.md
+++ b/.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.
--- a/.project-docs/30-worklog/tasks/20260828-migrate-project-docs-6f1a9c2d.md
+++ b/.project-docs/30-worklog/tasks/20260828-migrate-project-docs-6f1a9c2d.md
@@ -0,0 +1,69 @@
+# Task: Migrate project docs governance
+
+## Identity
+
+- Task ID: 20260828-migrate-project-docs-6f1a9c2d
+- Mode: Integration
+- Branch: main
+- Worktree: /Users/inmanx/Documents/lwltAPI
+- Base commit: 7b5d855b093af39bf834fab4f41f41b37be1170d
+- Owner: codex
+- Status: Ready for Integration
+
+## Scope
+
+- Initialize and adopt `.project-docs/` as the repository's durable project-memory system.
+- Migrate known current state, architecture, domain boundaries, evidence pointers, commitments, and maintenance rules from the legacy root planning files and active project documentation.
+- Archive and retire root `task_plan.md`, `findings.md`, and `progress.md` so the repository has one active documentation system.
+- Update `AGENTS.md`, `README.md`, and repository hygiene tests to enforce the new entry and ownership workflow.
+
+## Intent And Constraints
+
+- Preserve all legacy content in date-scoped history before removing root files.
+- Do not fabricate unknown project facts; keep unknowns and authorization-dependent validation explicit.
+- Do not change business behavior, source contracts, release artifacts, ERP state, services, deployment, or external systems.
+- Keep this migration exclusively owned under the integration lock; no sub-agents or concurrent task scopes are involved.
+- Use the bundled `maintain-project-docs` scripts for initialization, ownership, validation, drift checking, and task completion.
+
+## Plan
+
+1. Scan active references and inspect governance/test files that depend on the legacy root planning files.
+2. Freeze exact legacy files into `archive/project-history/2026-08-28/` and update its index.
+3. Populate the canonical `.project-docs` brief, current state, decisions, architecture, domain, evidence, reflection, commitments, and maintenance records from verified local sources.
+4. Update project entry documents and repository hygiene checks, then remove the legacy root files.
+5. Run document checks, drift checks, the repository's five required gates, size/hash/link/diff checks, and complete the task context.
+
+## Outcome
+
+- Initialized the complete `.project-docs/` concurrency and canonical-memory tree with the bundled non-overwriting initializer.
+- Claimed the known dirty `main` worktree in exclusive Integration mode and acquired the repository integration lock.
+- Populated project positioning, success criteria, integrated state/history, decisions, architecture, domain rules, glossary, evidence, reflection, commitments, stale-state guidance, and project authority pointers from verified local sources.
+- Updated `AGENTS.md`, `README.md`, and repository hygiene tests so future repository tasks use `maintain-project-docs` and the Concurrent Task Gate.
+- Preserved the final legacy `task_plan.md`, `findings.md`, and `progress.md` byte-for-byte in `archive/project-history/2026-08-28/`, indexed their hashes, and removed the root copies to prevent dual project-memory systems.
+- No business code, contracts, release artifacts, ERP state, service process, deployment, or external system was changed.
+
+## Verification
+
+- 2026-08-30 completion recheck: the user explicitly authorized finishing, committing, and releasing the known governance migration changes.
+- `check_project_docs.py`: passed.
+- `task_context.py doctor`: registry consistent.
+- `check_doc_drift.py --task-id 20260828-migrate-project-docs-6f1a9c2d`: passed after resolving the initializer placeholder issue recorded below.
+- Repository governance: 9/9 passed, including root boundaries, `.project-docs` authority, Markdown links, archive indexes, release hashes, and package/source equality.
+- TypeScript check: passed.
+- Control-plane tests: 127/127 passed.
+- Legacy/platform/tools tests: 248/248 passed.
+- Build: passed.
+- Two macOS-generated `.DS_Store` files were moved out of the repository before the final verification; they contained no project source or task state.
+- Final legacy archive SHA-256 and byte comparisons: all three passed.
+
+## Gate Notes
+
+- The first drift check correctly blocked six initializer-created `.gitkeep` files inside task-owned supporting directories because they had no task ID owner. The empty placeholders were removed; task records create their parent directory automatically, and future optional supporting directories are created only when a valid task-prefixed record is needed. No project information was deleted.
+
+## Follow-ups
+
+- Authorization-dependent ERP and AgentBus follow-ups were integrated into `.project-docs/80-commitments/commitments.md`; this documentation migration creates no additional operational follow-up.
+
+## Promotion Candidates
+
+- None. This task ran in Integration mode and applied the user-approved project-memory migration directly to canonical documentation.
--- a/.project-docs/40-domain/business-rules.md
+++ b/.project-docs/40-domain/business-rules.md
@@ -0,0 +1,22 @@
+# Business Rules
+
+## Durable Rules
+
+- `agent设计规范/business-adaptation-registry.md` is the cross-session business entry; each business maps user input, Skill/action, ERP flow, contracts, implementation, fixtures, and verification status.
+- Manual and AgentBus tasks share the same 18 machine routes, task-scoped parser mode snapshot, and organization automation rules.
+- The two passenger-list import routes are Program-only and wait for exactly one `.xls` or `.xlsx` attachment before deterministic normalization.
+- Passenger overwrite requires confirmation when target ERP rows are occupied; after `full_replace + confirmed=true`, every attachment-specified sequence is written even when values are unchanged.
+- A single strict `领队` row supplies leader contact; ambiguous, incomplete, duplicate, or structurally inconsistent leader data fails closed.
+- Shared-mother-plan `整团游客信息` export is only `shared_plan + visitor-list + tid-only`; independent and concrete shared-child visitor lists remain `did+tid`.
+- Real writes require unique resolution, exact page identity, ownership, write projection, explicit server response, and action-specific completion evidence.
+- Current business capability and verification status come from active source/contracts and the lifecycle release gate, never from archive wording.
+
+## Open Questions
+
+- Fresh authorized runtime read verification remains for the shared-mother-plan whole-visitor export branch.
+- Authorized current-version ERP write verification remains for SGL/TWN and four independent-order headcount categories.
+- AgentBus OSS DNS fallback must preserve private/reserved-network SSRF blocking.
+
+## Last Reviewed
+
+2026-08-28
--- a/.project-docs/40-domain/glossary.md
+++ b/.project-docs/40-domain/glossary.md
@@ -0,0 +1,13 @@
+# Glossary
+
+| Term | Meaning | Notes |
+|---|---|---|
+| operation | Unified validated business instruction exchanged between parser, control plane, and executor | Platform/task envelope metadata is excluded |
+| parse state | Business-semantic operation before ERP resolution | Must not claim execution success |
+| execution state | ERP-enriched operation after unique resolution and strict gates | Contains exact internal refs needed by the executor |
+| shared plan / 母团 | Parent shared-tour plan | Whole-visitor export uses `tid` only |
+| shared child / 子单 | Concrete customer order under a shared plan | Visitor list uses `did+tid` |
+| Program-only | Route must use the deterministic parser and may not fall back to AI | Applies to both passenger-list routes |
+| fresh requery | Read-only ERP verification performed after an action | Required except where an action-specific explicit-success credential is accepted |
+| no ERP write | Evidence-backed result that the write boundary was not crossed | Must not be inferred from an unknown post-submit failure |
+| Promotion Candidate | Task-scoped proposal for durable canonical memory | Accepted only through Integration Gate |
--- a/.project-docs/50-evidence/evidence-index.md
+++ b/.project-docs/50-evidence/evidence-index.md
@@ -0,0 +1,16 @@
+# Evidence Index
+
+Use this index for searchable, traceable evidence records.
+
+| Date | Topic | Status | Source | Detail |
+|---|---|---|---|---|
+| 2026-08-28 | Legacy project memory migration | Verified byte-for-byte | [Archive index](../../archive/project-history/2026-08-28/README.md) | Final root planning files were hashed, copied, and compared before retirement. |
+| 2026-08-28 | Current release capability and real-validation boundary | Current integrated evidence | [Lifecycle release gate](../../agent设计规范/test-fixtures/lwlt-lifecycle/release-gate.md) | Defines active conclusions and links immutable evidence. |
+| 2026-08-28 | Release artifact hashes and sources | Machine-verified | [Release manifest](../../dist/release-manifest.json) | Seven current artifacts and their source/hash metadata. |
+| 2026-08-28 | AgentBus reconnect and runtime switch | Verified at observation time; time-sensitive | [Archived legacy progress](../../archive/project-history/2026-08-28/legacy-planning-with-files-progress-final.md) | Repeated 4/4-ready samples after authorized restart; live status must be rechecked when needed. |
+
+## 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/`.
--- a/.project-docs/50-evidence/topic-template.md
+++ b/.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
+
+-
--- a/.project-docs/60-reflection/reflection-index.md
+++ b/.project-docs/60-reflection/reflection-index.md
@@ -0,0 +1,13 @@
+# Reflection Index
+
+Use this index for second-order workflow lessons.
+
+| Date | Reflection | Trigger | Action | Detail |
+|---|---|---|---|---|
+| 2026-08-28 | Shared rolling planning files created repeated size pressure and forced semantic compression. | Root `task_plan.md` repeatedly approached or exceeded its fixed limit. | Replaced the legacy system with task-scoped records plus serialized canonical integration in `.project-docs/`. | [Migration task](../30-worklog/tasks/20260828-migrate-project-docs-6f1a9c2d.md) |
+
+## 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`.
--- a/.project-docs/60-reflection/reflection-template.md
+++ b/.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?
--- a/.project-docs/60-reflection/skill-candidates.md
+++ b/.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.
--- a/.project-docs/80-commitments/commitments.md
+++ b/.project-docs/80-commitments/commitments.md
@@ -0,0 +1,13 @@
+# Commitments
+
+Track future-facing memory: promised follow-ups, unfinished loops, timed checks, and restart points.
+
+| Date | Commitment | Trigger / Due | Owner | Status | Next Action |
+|---|---|---|---|---|---|
+| 2026-08-28 | Verify shared-mother-plan `tid-only` whole-visitor export against the current runtime ERP path. | Explicit user authorization for ERP read access | Future authorized task | Pending authorization | Run read-only source and artifact checks without external delivery. |
+| 2026-08-28 | Verify independent-order SGL/TWN and adult/child/leader headcount mappings with real ERP writes. | Explicit user authorization for controlled ERP writes | Future authorized task | Pending authorization | Use reversible values and action-specific requery evidence. |
+| 2026-08-28 | Resolve AgentBus OSS attachment rejection caused by private/reserved local DNS answers. | User schedules the networking task | Future feature task | Pending | Design controlled public-DNS or host-allowlist fallback; keep private-network blocking. |
+
+## Use
+
+Record only commitments that should affect future sessions. Routine next steps can stay in `30-worklog/current-state.md`.
--- a/.project-docs/90-maintenance/doc-update-policy.md
+++ b/.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 `{task_id}__<slug>.md` files in the task-writable directories. The slug is non-empty and `.md` is the exact extension. 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`. Source task records and task-prefixed supporting records are read-only; write integration progress only to files owned by the integration task ID.
+
+## 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.
--- a/.project-docs/90-maintenance/stale-items.md
+++ b/.project-docs/90-maintenance/stale-items.md
@@ -0,0 +1,18 @@
+# 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 |
+|---|---|---|---|---|
+| 2026-08-28 | Archived legacy progress and plan snapshots | Process IDs, live/ready state, AgentBus channel readiness, and browser handshake are observations from one time window, not durable current state. | `20260828-migrate-project-docs-6f1a9c2d` | Re-run live read-only checks before relying on runtime state. |
+
+## Missing Context
+
+- Fresh authorized ERP read evidence for the shared-mother-plan `tid-only` visitor export branch.
+- Current-version authorized ERP write evidence for independent SGL/TWN and four headcount mappings.
+
+## 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.
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,29 +1,41 @@
 # LTJT 项目文件治理规则

-本文件约束所有后续维护会话。用户指令优先；在没有新的明确指令时，必须遵守以下位置、同步和归档规则。
+本文件约束所有后续维护会话。用户指令优先；在没有新的明确指令时，必须遵守以下位置、所有权、同步和归档规则。

 ## 开始工作前

-1. 依次读取根目录 `README.md`、`task_plan.md`、`findings.md`、`progress.md`。
-2. 运行 `git status --short`，保留所有既有未提交改动；禁止 `git reset --hard`、`git clean` 或批量回退。
-3. 通过 `agent设计规范/business-adaptation-registry.md` 定位业务，再读取对应业务页、Skill、Schema、mapping 和实现代码。
-4. `archive/` 只供追溯，不能反向覆盖当前业务规则；若历史文件与活动源码冲突，以活动源码及当前契约为准。
+1. 运行 `git status --short`，保留所有既有未提交改动；禁止 `git reset --hard`、`git clean` 或批量回退。
+2. 加载 `maintain-project-docs` Skill，先运行其 Concurrent Task Gate。任何代码或项目文档编辑前，`task_context.py start` 必须成功，且 `status --json` 中的 task ID、mode、绝对 worktree、branch 与当前任务完全一致。
+3. 所有权门禁通过后，按 `.project-docs/05-agent-entry/read-before-planning.md` 的顺序加载当前任务和 canonical 项目记忆；Feature 与 Integration 写入边界以该 Skill 和 `.project-docs/90-maintenance/doc-update-policy.md` 为准。
+4. 通过 `agent设计规范/business-adaptation-registry.md` 定位业务，再读取对应业务页、Skill、Schema、mapping 和实现代码。
+5. `archive/` 只供追溯，不能反向覆盖当前业务规则；若历史文件与活动源码冲突，以活动源码及当前契约为准。
+
+## 并发与子智能体
+
+- 原则上不创建子智能体；确有必要时必须先取得用户明确同意。
+- 一个活动任务只拥有一个 worktree；不得在已被其他任务占用或归属不明的 dirty worktree 中继续。
+- 不得用 Markdown 或口头约定模拟任务所有权；只能使用 `maintain-project-docs` 自带的 `task_context.py`。
+- 未知改动不得自动 stash、reset、移动、删除或认领；采用 `--adopt-existing` 必须有用户对已知改动的明确接管授权。

 ## 根目录边界

-允许的长期文件只有：
+允许的长期文件和目录只有：

 - 项目入口与约束：`README.md`、`AGENTS.md`；
- Planning with Files：`task_plan.md`、`findings.md`、`progress.md`；
+- 项目记忆：`.project-docs/`；
 - 构建与部署配置：`package.json`、锁文件、TypeScript、Docker、Compose、Git/Docker ignore 和环境示例；
+- 下表登记的活动源码、发布、报告、隔离与历史目录；
 - 本地秘密配置 `.env` 可以存在，但必须被 Git 忽略，不得读取、复制、归档或输出其内容。

+旧根目录 `task_plan.md`、`findings.md`、`progress.md` 已退役并冻结在 `archive/project-history/2026-08-28/`；不得恢复为活动入口或与 `.project-docs/` 并行维护。
+
 禁止在根目录新增临时说明、交接副本、测试输出、ZIP、DOCX、截图、日志、浏览器状态或一次性脚本。新增内容必须进入下表规定的位置。

 ## 唯一目录职责

 | 位置 | 唯一职责 | 禁止内容 |
 |---|---|---|
+| `.project-docs/` | 任务作用域记录、canonical 项目记忆、证据索引、反思、承诺和文档维护状态 | 运行日志、秘密、业务附件、绕过所有权门禁的共享进度 |
 | `agent设计规范/` | Agent Prompt、五个 Skill、业务模板、业务入口与稳定测试夹具的可编辑源 | 发布包、运行日志、历史版本副本 |
 | `schemas/` | 当前解析态、执行态和 ERP 表单 Schema | 历史 Schema、运行结果 |
 | `mappings/` | 当前 ERP 字段与生命周期 mapping | 探针输出、旧版本副本 |
@@ -39,13 +51,14 @@
 | `quarantine/` | 无法安全解析的外部输入隔离边界 | 当前源码或已信任 fixture |
 | `archive/` | 日期化、只读、可恢复的历史实现、证据、规划和发布物 | 当前入口或需要运行时读取的文件 |

-## Planning with Files
+## Maintain Project Docs

- `task_plan.md` 始终保留当前任务目标、阶段、决策和错误，建议不超过 16 KiB。
- `findings.md` 只保留仍影响当前设计和执行的事实，建议不超过 32 KiB。
- `progress.md` 只保留当前任务和最近有效里程碑，建议不超过 32 KiB。
- 超过边界时，先把原文件完整冻结到 `archive/project-history/<日期>/`，再语义压缩根文件并链接归档；禁止直接丢弃历史。
- 任务完成后不删除三文件。将计划状态收敛为完成，并保留足够信息让下一会话继续。
+- `.project-docs/30-worklog/tasks/<task_id>.md` 是任务局部范围、约束、结果、验证、后续项和 Promotion Candidates 的唯一记录。
+- Feature 模式只写当前 task ID 所属记录和允许的 task-prefixed supporting records；不得更新 `current-state.md`、共享索引、accepted ADR、canonical 架构、业务规则或共享聚合。
+- Integration 模式必须独占 worktree 和集成锁，才能把已接受事实写入 canonical 项目记忆；冲突的产品行为、架构方向或真相源必须由用户决定。
+- `current-state.md` 是上次集成快照，不代表其他并行任务的实时状态；其他任务只通过其 task record 做只读范围评估。
+- 仓库变更任务完成前必须更新任务记录、运行 `check_doc_drift.py --task-id <task_id>`，再用 `task_context.py complete` 标记 `ready_for_integration`。
+- 历史 Planning with Files 只供追溯；不得从归档复制回活动项目记忆。

 ## 单一源与同步矩阵

@@ -59,14 +72,21 @@

 ## 历史与生成物处理

- 旧版本、旧交接、旧发布说明和完成的计划按日期移动到相应 `archive/` 分类，并更新该日期 README。
+- 旧版本、旧交接、旧发布说明和退役文档按日期移动到相应 `archive/` 分类，并更新该日期 README。
 - 可重建编译产物、完全相同的别名包、`.DS_Store`、日志和临时输出不进入历史上下文；确认无唯一信息后清理。
 - 不把桌面作为当前源或发布源。桌面只允许用户主动需要的临时交付副本，项目内 `dist/` 才是当前交付位置。
 - 移动前必须做引用扫描；移动后必须修复活动链接。归档内部允许保留原始历史措辞，但归档 README 必须声明其非当前规则。

 ## 验证

-文件或目录调整后至少运行：
+项目文档或仓库文件调整后，先按已加载的 `maintain-project-docs` Skill 运行：
+
+```text
+scripts/check_project_docs.py
+scripts/check_doc_drift.py --task-id <task_id>
+```
+
+再至少运行：

 ```bash
 node --run check:repo
--- a/README.md
+++ b/README.md
@@ -5,11 +5,12 @@
 ## 新会话入口

 1. 先读 [项目文件治理规则](AGENTS.md)。
-2. 再读当前 [任务计划](task_plan.md)、[关键发现](findings.md) 和 [进度](progress.md)。
-3. 通过 [业务适配登记表](agent设计规范/business-adaptation-registry.md) 定位业务入口、Skill、Schema、mapping 和实现。
-4. 发布边界看 [生命周期发布门槛](agent设计规范/test-fixtures/lwlt-lifecycle/release-gate.md)，当前制品看 [发布清单](dist/release-manifest.json)。
+2. 加载 `maintain-project-docs` Skill，通过 Concurrent Task Gate 取得当前 worktree 所有权。
+3. 按 [项目记忆入口](.project-docs/05-agent-entry/read-before-planning.md) 加载当前任务、集成状态、决策和架构。
+4. 通过 [业务适配登记表](agent设计规范/business-adaptation-registry.md) 定位业务入口、Skill、Schema、mapping 和实现。
+5. 发布边界看 [生命周期发布门槛](agent设计规范/test-fixtures/lwlt-lifecycle/release-gate.md)，当前制品看 [发布清单](dist/release-manifest.json)。

-`archive/` 是只读历史，不定义当前规则；桌面不是当前源码或发布源。
+`.project-docs/` 是唯一活动项目记忆；旧 Planning with Files 已日期化归档。`archive/` 是只读历史，不定义当前规则；桌面不是当前源码或发布源。

 ## 当前发布基线

@@ -48,6 +49,7 @@ AI Agent/Skill 与确定性解析器都只负责业务语义、字段抽取和

 | 目录 | 用途 |
 |---|---|
+| `.project-docs/` | worktree 所有权门禁、任务作用域记录和经 Integration Gate 更新的 canonical 项目记忆 |
 | `agent设计规范/` | Agent Prompt、五个 Skill、业务模板、业务入口和稳定夹具 |
 | `schemas/`、`mappings/` | 当前解析/执行契约与 ERP 映射 |
 | `chrome-extension/` | 已登录 ERP 页面内的浏览器适配器源码 |
--- a/archive/project-history/2026-08-28/README.md
+++ b/archive/project-history/2026-08-28/README.md
@@ -1,8 +1,12 @@
 # 2026-08-28 项目历史

-本目录保存超过活动文件大小边界后冻结的完整规划快照，只供追溯，不定义当前规则。
+本目录保存达到或接近活动文件大小边界时冻结的完整规划快照，只供追溯，不定义当前规则。

 - [名单覆盖行修复完成后的完整计划](task_plan-pre-compression-roster-name-overwrite.md)：压缩根 `task_plan.md` 前的原始全文。
 - [名单确认覆盖强制覆写实施中的完整计划](task_plan-pre-compression-confirmed-overwrite.md)：`0.5.155` 发布门禁前再次压缩根 `task_plan.md` 的原始全文；SHA-256 `fdbf8ec09055be34daac5a13b52890020c3f7c833f0d03a4f3a612ae44fc88d3`。
 - [整团游客信息接入前的完整 findings](findings-pre-compression-shared-plan-visitor-export.md)：压缩根 `findings.md` 前的原始全文；SHA-256 `17e5c316e5f9e18f4b56374d2e1dba75c03e346396e3f63bdf78cdd4df3fcf84`。
 - [整团游客信息接入前的完整 progress](progress-pre-compression-shared-plan-visitor-export.md)：压缩根 `progress.md` 前的原始全文；SHA-256 `6e6c01b01a7fd294855edc1dcdf797c6ec0513f8b5e131f204660420341bd768`。
+- [AgentBus 重连后的完整计划](task_plan-pre-compression-agentbus-reconnect.md)：根 `task_plan.md` 达到 15,640 字节、距 16 KiB 上限仅余 744 字节时主动轮转的原始全文；SHA-256 `e8e288166f3bf4ad848fb37b985651320e9a9d3213b091fdcd2d13153d7d86ee`。
+- [退役时的最终 task plan](legacy-planning-with-files-task-plan-final.md)：切换到 `.project-docs/` 前根 `task_plan.md` 的最终全文；SHA-256 `22a4dd9d9ecf4883135c798fabde0f90656cab07bff5cf417d29d9edf1bddce0`。
+- [退役时的最终 findings](legacy-planning-with-files-findings-final.md)：切换到 `.project-docs/` 前根 `findings.md` 的最终全文；SHA-256 `e4c0515b2147f27bcd4db88ecf0d4658f05dc850ee29f07cdad62b5100011e6e`。
+- [退役时的最终 progress](legacy-planning-with-files-progress-final.md)：切换到 `.project-docs/` 前根 `progress.md` 的最终全文；SHA-256 `78ea11b52ac094b0dde0188a8c6018e6aae966717e6a2f7b6e288ac6acd83d86`。
--- a/archive/project-history/2026-08-28/legacy-planning-with-files-findings-final.md
+++ b/archive/project-history/2026-08-28/legacy-planning-with-files-findings-final.md
--- a/archive/project-history/2026-08-28/legacy-planning-with-files-progress-final.md
+++ b/archive/project-history/2026-08-28/legacy-planning-with-files-progress-final.md
@@ -1,5 +1,12 @@
 # 项目进度

+## 2026-08-28 — Planning with Files 主动轮转（已完成）
+
+- `task_plan.md` 处理前为 15,640 字节，占 16 KiB 上限的 95.5%；`findings.md` 与 `progress.md` 均远低于各自 32 KiB 上限，因此本轮只轮转活动计划。
+- 原计划已完整冻结到 [AgentBus 重连后计划快照](archive/project-history/2026-08-28/task_plan-pre-compression-agentbus-reconnect.md)，SHA-256 `e8e288166f3bf4ad848fb37b985651320e9a9d3213b091fdcd2d13153d7d86ee`，并与压缩前活动文件逐字节一致。
+- 活动计划已语义压缩为当前治理任务、最近有效里程碑、相邻待处理项和持续边界；业务源码、契约、Skill、发布物与运行态均未改变。
+- 归档索引已更新；规定门禁通过：仓库治理 9/9、TypeScript、控制面 127/127、legacy 248/248、build，且大小、快照哈希与 `git diff --check` 均通过。
+
 ## 2026-08-28 — AgentBus 断线后重启（已完成）

 - 用户明确授权重启控制面；预检确认在途 task 与 `accepted/running` attempt 均为 0。旧进程组 `62152` 退出后，运行会话管理器自动从标准入口拉起新进程组 `66218`、服务 PID `66228`，8786 只有一个监听。
--- a/archive/project-history/2026-08-28/legacy-planning-with-files-task-plan-final.md
+++ b/archive/project-history/2026-08-28/legacy-planning-with-files-task-plan-final.md
@@ -0,0 +1,50 @@
+# 项目文件治理计划
+
+## 当前任务：收敛 Planning with Files 大小（已完成）
+
+- **目标：** 在根 `task_plan.md` 达到治理上限前完成可恢复轮转，使活动计划重新只保留当前目标、有效决策、待处理项和安全边界。
+- **触发原因：** 处理前 `task_plan.md` 为 15,640 字节，占 16 KiB 上限的 95.5%，尚未超限但只剩 744 字节；`findings.md` 与 `progress.md` 均远低于各自 32 KiB 上限。
+- **安全边界：** 只调整 Planning with Files 与对应历史索引；不修改业务源码、Schema、mapping、Skill 或发布物，不访问 ERP，不变更任务或服务运行态，不部署或外发。
+
+### 阶段
+
+- [x] 恢复 README、三份 Planning with Files、工作区状态和业务登记，确认这是跨业务文件治理。
+- [x] 在修改活动计划前，将原文完整冻结到日期化历史目录并完成 SHA-256、逐字节一致性校验。
+- [x] 语义压缩活动 `task_plan.md`，保留当前任务、最近有效里程碑、相邻待处理项和持续边界。
+- [x] 更新归档索引与 `progress.md`，运行规定的五道门禁及 diff/大小检查。
+
+### 已确定的治理决策
+
+- 本轮只压缩接近上限的 `task_plan.md`；处理前 `findings.md` 为 4,885 字节、`progress.md` 为 5,487 字节，无需无意义轮转。
+- 压缩前原文已冻结到 [AgentBus 重连后完整计划](archive/project-history/2026-08-28/task_plan-pre-compression-agentbus-reconnect.md)，SHA-256 为 `e8e288166f3bf4ad848fb37b985651320e9a9d3213b091fdcd2d13153d7d86ee`，与原活动文件逐字节一致。
+- 归档只供追溯，不反向定义当前规则；活动事实继续以源码、契约、业务登记、`findings.md`、`progress.md` 和发布清单为准。
+
+## 最近有效里程碑
+
+- 当前发布基线为 Chrome 扩展 `0.5.157`、Program parser `v1.0.6`、输入契约/DOCX `0.5.123`、五个业务 Skill `0.5.125`；版本、文件名和哈希只以 [发布清单](dist/release-manifest.json) 为准。
+- `confirmation_export` 已接入散拼母团“整团游客信息”：固定 `shared_plan + visitor-list`，只允许 `orders_Visitor.asp?tid=<tid>`；独立团/散拼具体子单“游客名单”继续使用 `did+tid`，范围不得混用。
+- `passenger_list_import` 固定 Program-only；未确认的占用游客位要求覆盖确认，确认后附件指定序号全部覆写，同值也写；ERP 原生游客位不足时在保存前返回名单人数与可录入上限。
+- 名单唯一严格“领队”行投影为父表单联系人；父表单 ERP 明确成功即完成名单任务，不执行写后逐行名单回查，其他生命周期 action 仍要求 action-specific 完成凭据。
+- 8786 控制面和本地 Chrome 扩展已切换到上述基线；最近一次授权重启后，数据库、Schema、迁移 014 和 AgentBus 4/4 渠道连续采样正常。
+
+## 相邻待处理项
+
+- 散拼母团整团游客 `tid-only` 新分支仍需另行授权后做运行态 ERP 只读复测。
+- 独立团 SGL/TWN 与成人、占床儿童、不占床儿童、领队人数映射仍需另行授权 ERP 实写复测。
+- AgentBus OSS 附件曾因本机 DNS 返回私网/保留地址而被 SSRF 门禁拒绝；后续应采用受控公有 DNS 或主机白名单回退，不能全局放宽私网阻断。
+
+## 错误记录
+
+- 本轮尚无文件处理或校验错误。
+
+## 完成结论
+
+- 活动 `task_plan.md` 已从 15,640 字节压缩到远低于 16 KiB 的安全区间；完整原文、哈希和归档索引均已保留。
+- 规定门禁通过：仓库治理 9/9、TypeScript、控制面 127/127、legacy 248/248、build；`git diff --check` 通过。
+- 本轮仅修改三份治理记录：活动计划、项目进度和同日归档索引，并新增一个完整计划快照；没有业务、发布物或运行态变更。
+
+## 历史与持续边界
+
+- 本轮压缩前完整计划见 [2026-08-28 快照](archive/project-history/2026-08-28/task_plan-pre-compression-agentbus-reconnect.md)；更早快照见同目录 README 和 `archive/project-history/`。
+- 详细业务发现与运行结果分别见 [findings.md](findings.md) 和 [progress.md](progress.md)，避免在计划中重复堆叠已完成过程。
+- 真实 ERP 访问或写入、任务 mutation、扩展重载、服务重启、部署和外部发送仍需用户另行明确授权。
--- a/archive/project-history/2026-08-28/task_plan-pre-compression-agentbus-reconnect.md
+++ b/archive/project-history/2026-08-28/task_plan-pre-compression-agentbus-reconnect.md
--- a/tools/repository-hygiene.test.mjs
+++ b/tools/repository-hygiene.test.mjs
@@ -2,7 +2,7 @@ import assert from 'node:assert/strict';
 import { execFileSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
 import { existsSync } from 'node:fs';
-import { readdir, readFile, stat } from 'node:fs/promises';
+import { readdir, readFile } from 'node:fs/promises';
 import path from 'node:path';
 import test from 'node:test';
 import { fileURLToPath } from 'node:url';
@@ -18,6 +18,7 @@ const ROOT_ALLOWLIST = new Set([
  '.env.production.example',
  '.git',
  '.gitignore',
+  '.project-docs',
  'AGENTS.md',
  'Dockerfile',
  'LianSyn-platform',
@@ -28,19 +29,16 @@ const ROOT_ALLOWLIST = new Set([
  'control-plane',
  'dist',
  'docker-compose.yml',
-  'findings.md',
  'infra',
  'mappings',
  'node_modules',
  'package-lock.json',
  'package.json',
  'pnpm-lock.yaml',
-  'progress.md',
  'quarantine',
  'reports',
  'samples',
  'schemas',
-  'task_plan.md',
  'tools',
  'tsconfig.json',
 ]);
@@ -102,21 +100,38 @@ test('root contains only governed long-lived entries', async () => {
  const names = (await readdir(ROOT)).sort();
  const unexpected = names.filter((name) => !ROOT_ALLOWLIST.has(name));
  assert.deepEqual(unexpected, []);
-  for (const required of ['README.md', 'AGENTS.md', 'task_plan.md', 'findings.md', 'progress.md']) {
+  for (const required of ['README.md', 'AGENTS.md', '.project-docs']) {
    assert.ok(names.includes(required), `缺少根目录治理文件 ${required}`);
  }
 });

-test('Planning with Files stays current and bounded', async () => {
-  const limits = new Map([
-    ['task_plan.md', 16 * 1024],
-    ['findings.md', 32 * 1024],
-    ['progress.md', 32 * 1024],
-  ]);
-  for (const [name, limit] of limits) {
-    const size = (await stat(path.join(ROOT, name))).size;
-    assert.ok(size <= limit, `${name} 为 ${size} 字节，超过 ${limit} 字节；请先冻结再语义压缩`);
+test('maintain-project-docs is the sole active project memory', async () => {
+  const projectDocs = path.join(ROOT, '.project-docs');
+  const required = [
+    '00-brief/project-positioning.md',
+    '05-agent-entry/concurrent-task-gate.md',
+    '05-agent-entry/read-before-planning.md',
+    '10-decisions/decision-index.md',
+    '20-architecture/system-overview.md',
+    '30-worklog/current-state.md',
+    '30-worklog/task-template.md',
+    '90-maintenance/doc-update-policy.md',
+  ];
+  for (const relativePath of required) {
+    assert.ok(existsSync(path.join(projectDocs, relativePath)), `缺少项目记忆文件 .project-docs/${relativePath}`);
  }
+  for (const legacy of ['task_plan.md', 'findings.md', 'progress.md']) {
+    assert.ok(!existsSync(path.join(ROOT, legacy)), `旧 Planning with Files 文件不得恢复到根目录：${legacy}`);
+  }
+
+  const positioning = await readFile(path.join(projectDocs, '00-brief/project-positioning.md'), 'utf8');
+  const currentState = await readFile(path.join(projectDocs, '30-worklog/current-state.md'), 'utf8');
+  const taskRecords = (await readdir(path.join(projectDocs, '30-worklog/tasks')))
+    .filter((name) => name.endsWith('.md'));
+  assert.doesNotMatch(positioning, /\{(?:one-line project positioning|primary project goal|primary user or consumer)\}/u);
+  assert.match(currentState, /^## Integrated Through$/mu);
+  assert.match(currentState, /Commit `[a-f0-9]{40}`/u);
+  assert.ok(taskRecords.some((name) => /^\d{8}-[a-z0-9-]+-[a-f0-9]{4,16}\.md$/u.test(name)), '缺少规范 task ID 的项目任务记录');
 });

 test('temporary residue and report outputs do not pollute the repository', async () => {