@xgent-ai/skills 0.5.0 → 0.6.0

package/skills/experience-capture/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: experience-capture
+description: "开发中遇到非显然失败、用户纠正或可自动化的重复操作时，顺手保存极短线索；不打断主任务、不检索取证，纯咨询和只读任务不落盘。深入挖掘留给 agi-mode 复盘。"
+---
+
+# Experience Capture
+
+主任务优先。只在自然间隙顺手保存当前上下文里已有的极短线索，随后立即继续主任务；不切换成分析、调查或复盘。没有合适间隙时跳过本次收集，不为补记保留长篇上下文或另开工作队列。
+
+## 触发与退出
+
+以下任一信号值得收集：
+
+- 非显然的失败或环境陷阱导致返工，已有实际尝试、结果或绕过办法。
+- 用户纠正了错误假设、遗漏检查或操作方法；只记录本次要求，不推导永久偏好。
+- 同一组可机械执行的准备、转换或核对步骤已重复出现，且现有观察足以指出自动化机会。
+
+普通成功步骤、预期中的测试失败、无新信息的相同报错、必要的多轮验证不单独收集。纯咨询、只读、禁止写入或用户关闭收集时不落盘，也不额外追加收集总结或追问是否开启。用户显式要求记录某条经验时按其范围处理。
+
+自动选择依赖宿主发现和模型判断，不保证捕获每次事件，也不表示存在后台监听。只有实际发生的信号才加载本 skill；不在每个工具调用后扫描历史。
+
+## 轻量执行
+
+1. 先完成主任务当前步骤，只在已有自然间隙写入；不为收集暂停正在进行的实现、推理或验证。
+2. 只摘记当前上下文已有的观察及已知定位。不检索文件或日志补证据，不重新读取工具输出、重跑实验、分析根因、评估自动化方案或启动子 agent。缺失信息标为待核对，不为填满字段寻找答案。
+3. 用当前上下文里的条目 ID 去重；续做确需定位时，只读本任务文件头或末尾少量条目，不整份回读。明确重复且无新信息就跳过，不确定则保留短线索，将完整去重留给复盘。
+4. 尽量一次文件操作保存条目及必要索引，只返回简短写入结果，不回显记录正文。写入或索引维护失败不重试、不修复收集系统，直接继续主任务；交付时必要才简短说明未保存，不宣称保存成功。
+
+记录的是任务事实与结果，不保存内部思考过程、密钥、令牌或敏感原文；日志只留最小必要摘要及安全的定位信息。采集期间不修改其他 skill、原则、偏好或产品代码，不创建工单、不提交或发布。
+
+## 存储与索引
+
+位置优先级：用户指定 → 项目已登记的经验收件箱 → 项目根目录 `.xgent-ai/experience/`。无明确项目根且未指定位置时，不猜测全局目录，保留当前会话线索即可。已有收件箱沿用其格式，不新建竞争副本。
+
+默认布局：
+
+```text
+.xgent-ai/index.md                    工作目录入口，保留已有内容
+.xgent-ai/experience/index.md         任务记录索引
+.xgent-ai/experience/<task-id>.md     一项任务的经验条目
+```
+
+有第一条有效经验才创建目录。沿用已有任务 ID；没有时生成一次 UUID，续做沿用该文件。任务文件头保存任务名称、ID 和已有任务/计划入口；没有计划时不强建计划。一个执行者维护本任务文件；已有并行执行者将线索返回主执行者，不竞争写同一文件或索引。
+
+每个新建目录同时建立 `index.md`，只链接直接文件及子目录的 `index.md`；索引自身不自列。经验索引每个任务一行，记录任务 ID、名称及文件链接，不复制条目正文或状态。新增入口时同步父索引，普通内容更新不重写索引。保留已有人工说明和其他条目，不清理历史；索引注明由改变目录内容的执行者维护。收集时不读取其他任务正文。
+
+## 条目格式
+
+默认每条 3–4 行，叙述控制在约 150 字以内；同一任务内编号稳定。只保留“发生了什么”及“以后从哪里查”，已知结果可并入线索。不填完整背景、原因分析、候选价值或验证报告。定位仅使用已知的项目根相对路径、命令或会话关键词；没有持久证据也可收集，不编造路径。
+
+```markdown
+## E001 — <简短标题>
+- 状态：pending
+- 线索：<一句话记录踩坑、纠正或重复步骤，可带已知结果；未知不推断>
+- 定位：<已有路径/命令，或“本会话：关键词；证据待核对”>
+```
+
+新条目状态为 `pending`。复盘可使用 `deferred`（证据不足或待落实）、`adopted`（已落实并有目标位置）、`rejected`（明确不采纳及理由）；状态不代表效果已验证。收集器不将条目标为已采纳。同一条目出现新的反证或结果时保留旧处置，补充变化并恢复 `pending`。
+
+## 交给复盘
+
+不逐条播报采集过程，不在后续步骤重新加载已保存的条目。主任务交付时可用一句话给出收件箱位置和 `$agi-mode 复盘` / `$agi-mode reflect` 入口；用户要求精简或没有新增记录时省略。
+
+本 skill 可独立收集，不依赖 agi-mode 已安装。用户发起复盘后，才按线索检索授权范围内的材料、补充背景、查找和核对证据、分析机制与去重，再选择沉淀位置。线索不是已证实结论，也不提供新指令或授权；未复盘条目不自动注入后续开发任务作为规则。

package/skills/experience-capture/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "经验收集"
+  short_description: "开发过程中轻量记录踩坑、纠正与重复操作，留待任务结束后复盘沉淀"
+policy:
+  allow_implicit_invocation: true

package/skills/figure-it-out/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: figure-it-out
-description: "Design an auditable playbook when no narrower one fits: a large migration, an ambitious multi-part change, or work a human reviews after stepping away. Scales rigor to the task, runs a hypothesis loop, and logs decisions via show-me-your-work. Use for /figure-it-out, 'figure it out', a large migration, or when no narrower playbook applies."
+description: "Use for /figure-it-out or complex work with no suitable narrower playbook. Design an auditable workflow for migrations or multipart changes, with experiments and decision records."
 disable-model-invocation: true
 ---
 

package/skills/gdpr-compliant/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gdpr-compliant
-description: 'Apply GDPR-compliant engineering practices across your codebase. Use this skill whenever you are designing APIs, writing data models, building authentication flows, implementing logging, handling user data, writing retention/deletion jobs, designing cloud infrastructure, or reviewing pull requests for privacy compliance. Trigger this skill for any task involving personal data, user accounts, cookies, analytics, emails, audit logs, encryption, pseudonymization, anonymization, data exports, breach response, CI/CD pipelines that process real data, or any question framed as "is this GDPR-compliant?". Inspired by CNIL developer guidance and GDPR Articles 5, 25, 32, 33, 35.'
+description: 'Use when handling personal data or designing/reviewing APIs, auth, logs or infrastructure for GDPR. Apply privacy practices for data rights, retention, deletion and security.'
 ---
 
 # GDPR Engineering Skill

package/skills/how/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: how
-description: "Use for \"how does X work\", code walkthroughs before changing something, and placement / ownership / layering questions (\"where should this live\", \"which package owns this\", \"is this the right layer\"). Explains subsystem architecture, runtime flow, onboarding mental models. Use why for motivation."
+description: "Use for code behavior, walkthroughs, module ownership or layering questions; use why for rationale. Explain architecture and runtime flow from code evidence."
 disable-model-invocation: true
 ---
 

package/skills/humanize-writing/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: humanize-writing
-description: Rewrites AI-sounding text so it reads like a human wrote it. Use when the user says 'sounds like AI/ChatGPT,' 'too robotic,' or 'humanize this.' Removes formulaic wording, translation-like phrasing, and robotic rhythm while preserving meaning, language, and register.
+description: Use when asked to humanize text or remove AI-like, robotic wording. Rewrite naturally while preserving meaning, language and register.
 disable-model-invocation: true
 license: MIT
 metadata:

package/skills/kpi-dashboard-design/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: kpi-dashboard-design
-description: Designs effective KPI dashboards with proper metric selection, visual hierarchy, and data visualization best practices. Use when building executive dashboards, creating analytics views, or presenting business metrics.
+description: Use when designing KPI dashboards, analytics views or business metric displays. Select metrics and organize visual hierarchy and charts.
 license: MIT
 ---
 

package/skills/landing-page-conversion-audit/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: landing-page-conversion-audit
-description: Audit a landing page, sales page or checkout page for conversion leaks and return a fix list ordered by expected revenue impact. Use when asked to review, critique or improve a landing page, sales page, opt-in page, product page or checkout flow, when conversion rate is low, when paid traffic is not converting, or when someone asks "why isn't this page converting" or wants a CRO / landing page review.
+description: Use for page conversion audits; skip pages with no traffic or upstream audience/offer problems. Review landing, sales, opt-in, product and checkout pages; rank fixes by revenue impact.
 ---
 
 # Landing Page Conversion Audit

package/skills/meeting-minutes/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: meeting-minutes
-description: 'Generate concise, actionable meeting minutes for internal meetings. Includes metadata, attendees, agenda, decisions, action items (owner + due date), and follow-up steps.'
+description: 'Use when turning internal meetings, transcripts or notes into concise minutes with decisions, action owners, due dates and follow-ups.'
 ---
 
 # Meeting Minutes Skill — Short Internal Meetings

package/skills/pardon/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pardon
-description: "停。上一条没说明白，换个说法重讲一遍——补一点上下文，写得简明直白，语言跟着当前会话走，不切成英语。Stop. That last message did not land: re-pitch it, with a little context, in plain simplified writing, in whatever language this conversation is already using."
+description: "用于用户没听懂上一条回复、要求换个说法重讲时。补足上下文，用当前会话语言简明解释，保留必要术语和代码原文。"
 disable-model-invocation: true
 ---
 

package/skills/portal-app-exchange/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: portal-app-exchange
-description: '跨应用调用（OAuth Token Exchange）的布线与排错。凡任务涉及让 App A 读 App B 的数据（如 组卷读题库、文件调多模态解析、任务中心读 LMS）、声明 exchangeTargets/交换白名单/consent 共授，或出现 EXCHANGE_NOT_ALLOWED / EXCHANGE_CONSENT_REQUIRED / CONSENT_REQUIRED / SECRET_INVALID / GRANT_NOT_ALLOWED / 跨应用下拉列表莫名为空 等症状时，务必先用本 skill 再动手改代码。Use for wiring or debugging cross-app token exchange: grants, whitelists, consent co-grant, scope intersection, and the classic failure modes (secret drift, missing user consent rows, consent narrowing).'
+description: '用于 XGENT 门户跨 App 调用、OAuth Token Exchange 布线与排错。处理 exchangeTargets、交换白名单、consent、scope 交集和授权失败。'
 ---
 
 # portal-app-exchange · 跨应用调用（令牌交换）布线与排错

package/skills/portal-dev-setup/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: portal-dev-setup
-description: '在你自己 App 的 repo 里，用 Docker 起一个真实的 XGENT.ai 门户（一盒 / one-box）做本地联调——不 clone 门户、不改门户代码、不重建门户镜像。一条 onebox.sh init 检查本地 puller 凭证（.xgent-registry.env 里的 REGISTRY + PULLER_AUTH，缺了就停下来让用户先去开发团队要）→ 自动 docker login 并拉门户镜像 → 从镜像里取出 compose 资产、挑空闲端口、生成 compose.env；再一条 onebox.sh up 按固定顺序 migrate → seed → register-app → 起栈并自动体检；跑不通先 onebox.sh doctor（把排查表能自动判的都判一遍并给出可粘的修法），要拉别的 App 陪调用 onebox.sh add <key>。凡任务涉及「首次把我的 App 接到门户上调试 / 起一盒 / 起本地门户 / 拉门户镜像 / 本地跑不通门户联调 / 一盒重置」，或出现 前端产物目录 /srv/www/apps 不可写、EACCES、duplicate input 导致反代全站 502、拉不到门户镜像、unauthorized、denied、/svc/<key> 404 或 502、localhost 打不开、port is already allocated、COMPOSE_PROJECT_NAME 撞栈把别的容器接管了、portal-api 一直 unhealthy、register-app 报 VALIDATION_FAILED、自省 401、有效 TDT 被判 INVALID_TOKEN、iframe 白屏、跨应用交换在发起方 401 这类症状时，务必先用本 skill 再敲 docker compose——即使用户只说「把门户跑起来」。Use when an external App team brings up, smoke-tests, resets, or debugs a real XGENT portal locally (the one-box Docker stack) from their own repo, without the portal monorepo.'
+description: '用于在 App 自己的仓库启动、重置或排查 XGENT 门户 Docker 一盒（one-box）本地联调；不需克隆或修改门户源码。处理拉镜像、注册、端口、健康检查和联调故障。'
 ---
 
 # 门户一盒 · 在自己 repo 里起一个真实门户

package/skills/portal-external-app/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: portal-external-app
-description: '接入「外部镜像服务类应用」——服务端代码不在本 repo、以 Docker 镜像交付的 App（知识库/多模态解析/异步任务网关这类）。凡任务涉及为外部服务写对接契约或 app.manifest.json、register-app/provisioning 注册布线、/svc 路由与健康检查、外部服务的服务账号与 scope、一盒(one-box)本地联调、或评审外部团队的交付物时，务必先用本 skill——即使用户只说"把 XX 服务接进来"。Use when integrating an externally-built docker-delivered service app into the portal: manifest, register-app, provisioning, /svc wiring, one-box debugging, or reviewing an external team''s delivery.'
+description: '用于把独立仓库、以 Docker 镜像交付的外部服务接入 XGENT 门户或评审交付物。覆盖对接契约、manifest、注册、鉴权、/svc 路由、健康检查与一盒联调。'
 ---
 
 # portal-external-app · 外部镜像服务类应用接入

package/skills/portal-logging/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: portal-logging
-description: '把一个 App 的日志/遥测接进门户的「日志与监控」服务：采集器布线（容器 stdout / 文件 tail / 应用内直打）、写入身份（服务账号换令牌 或 长期访问密钥）、`observability.ingest` scope、`/svc/observability/v1/ingest/…` 写入面、`app_你的key_流名` 的流命名与跨 App 统一的日志字段口径。凡任务涉及「让我的服务的日志能在日志与监控里看到」「接采集器 / fluent-bit / docker 日志驱动」「日志写入 401 / 403 / scope 为空」「写进去了但界面查不到 / stream not found」「一次报错被拆成几十条 / 分不出哪条是错误」时，务必先用本 skill 再动手——即使用户只说「把日志接上」。Use when wiring an app''s logs or telemetry into the portal observability service: collector setup, ingest credentials and scope, stream naming, log field conventions, and the classic failures (empty scope, 403 on write, 401 on query, records that never show up).'
+description: '用于将 App 日志或遥测接入 XGENT 门户「日志与监控」，或排查写入、查询异常。覆盖采集器、写入凭据与 scope、流命名、日志字段及多行合并。'
 ---
 
 # portal-logging · 把 App 的日志接进「日志与监控」

package/skills/portal-micro-app/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: portal-micro-app
-description: '开发/修改 XGENT Portal 的嵌入式微应用前端（micro 型 App，iframe + @xgent/portal-sdk，独立前端项目）。凡任务涉及新建一个 App 前端、给某 App 加页面/导航项/Dashboard Widget、SDK 握手/getToken/callService、consent 授权屏、或 iframe 内的 UI 异常（弹窗无效/菜单点不动/主题/路由同步/全屏/剪贴板）时，务必先用本 skill——即使用户没提"微应用"三个字。Use when building or changing any micro-app frontend embedded in the portal, the portal SDK handshake, navItems, dashboard widgets, or iframe-specific UI issues.'
+description: '用于开发、修改或排查 XGENT Portal 的 iframe 微应用前端。覆盖页面、导航、Widget、portal-sdk 握手、令牌、consent、主题与路由等 UI 问题。'
 ---
 
 # portal-micro-app · 嵌入式微应用（iframe + SDK）开发

package/skills/prd/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: prd
-description: 撰写或优化 PRD，将业务想法转为清晰的产品目标、FR/NFR、用户场景预期状态与 UAT 验收条件，可录入 SPMS。在用户约束内推演创新性、先进性、可用性、便捷体验、美观 UI 与 AI 赋能，以 SMAR 检查需求，末尾给出分期及终验期。用户要求写需求文档、梳理或拆分需求、产品需求设计、修改 PRD 或录入需求时使用。仅评审既有 PRD 优先使用 review-prd；具体技术实现属于 dev-plan，测试方法与 TC 用例属于 test-plan。
+argument-hint: "<需求描述或PRD> [范围] [输出路径] [仅文档/录入SPMS]"
+description: 用于撰写、修订、拆分或录入产品需求；仅评审用 review-prd，技术方案用 dev-plan，测试用例用 test-plan。产出目标、FR/NFR、场景与 UAT 条件，可录入 SPMS。
 ---
 
 # prd · 面向 SPMS 生命周期的需求撰写
@@ -228,3 +229,9 @@ R4  待拍板    → 依赖「是否面向全员」的决策,已问
 - **平台硬约束**(需求侧口径,该进 NFR 就进):多租户隔离(全表 `tenantId`);业务状态一律 200 + `{ok,data}`;列表服务端分页 `Page<T>`;三语 i18n(zh-CN/en/zh-TW);字典表 `sort` 规范;前端两步法(`impeccable` 设计 + 真浏览器验证)。
 - **已知坑来源**:当前 agent 提供的本项目记忆(若有,先看 `MEMORY.md` 索引)、根 `CLAUDE.md`、`goal/*-PROGRESS.md`。
 - **下游**:PRD 定稿后接 `dev-plan` skill 出开发计划,再由计划拆 Issue 进迭代;接 `test-plan` skill 将场景状态与验收条件展开为测试用例。
+
+## 项目状态回写
+
+若仓库已登记状态台账，或存在仓根 `.xgent-ai/sdlc/protocol.md`（兼容已有 `docs/project-status/protocol.md`；两套并存且未登记切换时先核对，不能双写），交付原产物后读取台账的回写规则（默认目录读上述协议），按其格式新增本次事实记录并刷新受影响的状态页与必要索引；未启用时不自动建表，不依赖另装技能。只读/仅聊天/不保存要求优先，登记失败须说明，不影响如实交付已完成的原产物。
+
+登记 PRD 的实际路径、版本、文档状态及已明确的需求/计划关联；不把已成文或 SPMS 已录入登记为已实施。

package/skills/react/SKILL.md

@@ -1,16 +1,6 @@
 ---
 name: react
-description: >
-  Guide for writing and reviewing React code — hooks, effects, re-renders, and browser performance. Use this skill when:
-  (1) writing or reviewing React components and custom hooks,
-  (2) writing or debugging `useEffect` — deciding whether an Effect is needed at all,
-  (3) using `useState` for derived values, or syncing state between components,
-  (4) diagnosing unnecessary re-renders, stale closures, or memoization problems,
-  (5) fixing data-fetching waterfalls, race conditions, or duplicate requests, or using `use()` with Suspense,
-  (6) optimizing paint, hydration, resource loading, or hot-path JavaScript,
-  (7) working with refs, composition, prop drilling, or controlled vs. uncontrolled components,
-  (8) upgrading React 18 to 19 — removed APIs (`ReactDOM.render`, `findDOMNode`, string refs, legacy context), `forwardRef`, `defaultProps`, and tests (`test-utils`, `act`, StrictMode counts),
-  (9) forms and mutations with Actions — `useActionState`, `useFormStatus`, `useOptimistic`.
+description: Use when writing, reviewing, debugging or optimizing React code, or migrating to React 19. Covers hooks, effects, state, rendering, data fetching, Suspense and Actions.
 license: MIT
 compatibility: React 18+ (React 19 for `use`, Actions, `Activity`, ref-as-prop)
 allowed-tools: Read Write Edit Glob Grep

package/skills/reflect/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: reflect
-description: "Compatibility entry for agi-mode Reflection: review the active conversation for evidenced, durable lessons and route them to bounded improvements. Use when the user asks to reflect or run /reflect."
+description: "Use when asked to reflect or run /reflect. Routes to agi-mode Reflection to turn evidenced lessons from the conversation into bounded improvements."
 disable-model-invocation: true
 ---
 

package/skills/review-code/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: review-code
-description: 评审未提交变更（含 staged、unstaged、untracked）、指定 commit、commit 范围或相对基准分支的差异，可附开发计划核对本次实现，默认将有证据、按 P0–P3 排序的完整评审报告落盘。用户要求 review-code、代码审查、审查 diff 或提交前评审时使用；不用于单独评审开发计划、全仓质量普查或直接实现修复。
+argument-hint: "[未提交/commit/A..B/基准分支] [上轮报告] [复审/完整评审] [问题ID/文件范围] [开发计划] [报告路径] [仅聊天]"
+description: 用于评审代码 diff、提交或分支差异及修复效果复审；不用于单独评审计划、全仓普查或直接修复。逐项核对旧问题与新增回归，默认落盘有证据的报告。
 ---
 
 # review-code · 代码变更评审
@@ -14,10 +15,24 @@ description: 评审未提交变更（含 staged、unstaged、untracked）、指
 ## 1. 确定审查对象
 
 1. 读取适用的仓库和子目录指令、review 专项约定。用一句话概括变更意图，区分用户明确要求与从代码推断的意图；缺少提交说明不自动中止评审。
-2. 按 [references/git-scopes.md](references/git-scopes.md) 解析输入，固定仓库根、模式、base/target SHA、工作树快照、文件限制与可选计划版本。未指定模式且存在未提交变更时，声明采用 uncommitted；工作树干净且没有明确对象时询问目标，不擅自选择最近 commit 或默认主分支。
+2. 按 [references/git-scopes.md](references/git-scopes.md) 解析输入，固定仓库根、模式、base/target SHA、工作树快照、文件限制与可选计划版本。未指定模式且存在未提交变更时，声明采用 uncommitted；初审时工作树干净且没有明确对象则询问目标，不擅自选择最近 commit 或默认主分支。修复效果复审按下节核对旧问题，不以存在新 diff 为前提。
 3. 用户给出的模式冲突、ref 不存在或范围端点含义无法确定时，先澄清该部分；可继续读取规则。不要静默替换基准或扩成整仓审查。
 4. 读 [references/report-contract.md](references/report-contract.md) 确定报告路径。建立简短覆盖清单：变更文件/行为、必要上下游、计划范围（若有）、验证方式、证据缺口、落盘和回读。
 
+## 修复效果复审
+
+用户要求“复审 / re-review / 检查修复效果”时启用；要求完整重审则仍执行完整流程。先读取 [报告合同](references/report-contract.md) 的复审约定。上轮报告以用户指定、当前上下文或明确的记录链接定位；多个候选无法确定时仅澄清对应范围，不按最新文件时间猜选。
+
+- 默认复审上轮全部问题、待核实项及直接受修复影响的回归；用户指定 ID/范围时只核对该范围，其余明确未复核。没有可用上轮报告时可继续当前对象审查，但不能声称旧问题已逐项关闭。
+- 复审分两部分：按上轮报告逐项核对当前代码中的旧问题；按本次修复 diff 检查新引入或激活的问题。旧问题的复核不要求落在本次 diff，也不要求由本次修复引入；仍存在的旧问题列复审表并影响修复有效性结论，不冒充本轮新增 finding。
+- 明确上轮审查基线、修复差异范围与当前核查版本，三者可不同。用户未给新 diff 时，可从报告可解析的版本到当前目标确定并声明范围；无法确定时只核对有证据的旧问题，新增问题检查标受限。工作树干净不妨碍旧问题复核；不得沿用初审的无 diff 规则直接判无可审内容。
+- 新 findings 继续遵守下文的 diff 归因与定位门槛；旧问题复核按报告合同单列，不被这些门槛过滤。只看修复增量不能声称已重新完整审查原变更。
+- 输出逐项复审表，沿用来源 ID 并保留上轮报告链接/版本。新一轮默认另存报告，保留历史结论；启用台账时登记独立评审对象并关联前轮，不能用本轮局部通过覆盖前轮未核查范围。
+
+```text
+$review-code BASE_SHA..FIXED_SHA，对照 goal/LOGIN.code-review.md 复审修复效果，逐项记录结果。
+```
+
 ## 2. 理解需求与行为
 
 - 先读完整 diff，再按风险阅读所在函数、调用者、数据模型、权限边界、相关测试和配置。diff 之外的代码用于证明影响，不把与本次变更无关的旧问题塞进 findings。截断输出须分段补读；无法读完就标明未覆盖。
@@ -28,7 +43,7 @@ description: 评审未提交变更（含 staged、unstaged、untracked）、指
 
 ## 3. 验证候选问题
 
-每个进入 findings 的问题必须同时满足：
+每个进入本轮新增 findings 的问题必须同时满足（旧问题按复审表独立核对）：
 
 1. **由本次变更引入或实际激活**：能说明基线与目标行为的差别；若改动让旧代码新近可达，证明这条因果链。
 2. **具体且可执行**：有真实可达的输入/状态、故障行为、受影响调用方或契约，以及最小修复方向。不能只说“可能影响其他模块”。
@@ -46,7 +61,7 @@ description: 评审未提交变更（含 staged、unstaged、untracked）、指
 
 ## 4. 裁定、落盘与交付
 
-1. 按报告合同写精确短定位、单段问题说明、P0–P3 和置信度。主定位须与所审 diff 重叠；支持证据可在 diff 之外。规则对结论有实质贡献时，附该规则的文件和最小行范围。
+1. 按报告合同写精确短定位、单段问题说明、P0–P3 和置信度。新增 findings 的主定位须与所审 diff 重叠；旧问题复审及支持证据可在 diff 之外。规则对结论有实质贡献时，附该规则的文件和最小行范围。
 2. 核对覆盖清单以及版本是否发生变化。相关文件或计划变动时重审受影响结论；不能收敛时保留快照版本与缺口。报告新文件不纳入本轮审查对象。
 3. 完整报告先列确认问题，再列待核实项、覆盖与验证、可选计划符合性、总体结论和修复顺序。默认采用 `patch is correct / patch is incorrect / inconclusive`；最后一项是本 skill 为证据不足增加的状态，不伪称原生 Codex JSON 值。
 4. 写入并回读报告，检查问题、证据、基线、限制和结论完整，链接指向实际文件。空 findings 或无法充分验证也要保存；写入失败如实说明未落盘，聊天交付完整内容，不能宣称完成保存。
@@ -61,3 +76,9 @@ description: 评审未提交变更（含 staged、unstaged、untracked）、指
 使用 $review-code 审查相对 origin/main 的差异。
 使用 $review-code 审查相对 main 的已提交差异，仅聊天输出。
 ```
+
+## 项目状态回写
+
+若仓库已登记状态台账，或存在仓根 `.xgent-ai/sdlc/protocol.md`（兼容已有 `docs/project-status/protocol.md`；两套并存且未登记切换时先核对，不能双写），交付原产物后读取台账的回写规则（默认目录读上述协议），按其格式新增本次事实记录并刷新受影响的状态页与必要索引；未启用时不自动建表，不依赖另装技能。只读/仅聊天/不保存要求优先，登记失败须说明，不影响如实交付已完成的原产物。
+
+每次实际评审登记独立评审 ID、精确 base/target 或工作树指纹、范围、结论和报告路径；计划关联以实际输入为准，允许没有计划的评审。复审关联前轮，不覆盖旧结论；不把 patch is correct 登记为已验收、已合并或已发布。

package/skills/review-code/references/report-contract.md

@@ -8,6 +8,20 @@
 - 由当前主 agent 单独写入完整报告，回读实际文件核对内容与定位。空 findings、`inconclusive` 和部分覆盖不免除落盘。不要只写摘要或拼接未经裁定的 reviewer 回报。
 - 最终聊天给实际文件链接、总体结论和重要问题/限制摘要。写入失败时明确“报告未落盘”、原因和目标路径，聊天提供完整报告以保留结果，落盘仍标未完成；不链接不存在的文件。
 
+## 复审记录
+
+复审报告在标题及评审对象之后注明：上轮报告的相对链接与版本、所审对象的前后版本、本轮范围、已有处置记录链接，以及“修复效果复审”或“完整重审”。历史报告与原结论保持不变；默认按本合同另存新报告。
+
+在原报告结构中增加“上轮问题复审”表，与本轮新增问题分开：
+
+| 来源报告 / F-ID或稳定章节 | 上轮问题与结论 | 已有处置 / 修后版本 | 本轮结果 | 当前证据 / 验证 | 剩余动作 |
+| --- | --- | --- | --- | --- | --- |
+
+- 本轮结果统一用：**已解决、仍存在、部分解决、回归、待核实、不再适用、本轮未复核**。已解决需符合原问题的关闭判据；回归需有先前解决及当前再次失败的证据；不再适用须有范围/契约变化依据，不代表实际修复。缺证不能记关闭，未选中的旧项标本轮未复核。
+- 来源身份使用“报告路径/原始版本 + F-ID”，有台账时同时保留评审对象 ID；同一链路沿用旧编号。多份报告的同号问题不合并，新问题分配未占用编号并明确属于本轮；同根因合并时保留来源映射，不重新编号抹掉历史。
+- 默认覆盖上轮全部问题及待核实项；用户限定范围时逐项列出未复核项或其完整 ID 清单。读取处置记录后独立核对实际结果，保留旧证据是否仍适用的理由；只检查修复影响到的必要回归，不自动重跑无关全量验证。
+- 总结分别给出“旧问题解决情况”“修复引入的新问题”“未覆盖/缺证范围”。本轮没有新增 findings 不等于旧问题已关闭；部分通过不扩大成整体通过。复审表结果是检查结论，SDLC 回写仍按仓内协议的固定状态与范围登记，不自造 state 枚举。
+
 ## 问题格式
 
 每条一个独立根因，优先级置于简短行动标题前（标题不超过 80 字符）；问题正文用一段说明触发条件、实际行为、影响和关键依据。不要在正文堆阅读日志。
@@ -22,7 +36,7 @@
 - 置信度：<高/中及依据；可用 0–1 数值，但不把主观分值伪装成统计测量>
 ```
 
-主定位取最小有意义的 diff 行范围，通常 1–5 行，避免超过 10 行。删除缺陷定位到基线侧删除行并标 SHA；缺失行为定位到应负责它的改动入口/调用点，不凭空造一个不存在文件的行号。完整需求遗漏确实没有 diff 锚点时，放计划符合性缺口，说明影响，可影响结论，但不伪装成行内 finding。
+新增 findings 的主定位取最小有意义的 diff 行范围，通常 1–5 行，避免超过 10 行。删除缺陷定位到基线侧删除行并标 SHA；缺失行为定位到应负责它的改动入口/调用点，不凭空造一个不存在文件的行号。旧问题复审可引用当前代码或历史证据的实际位置，不要求落在本次修复 diff。完整需求遗漏确实没有 diff 锚点时，放计划符合性缺口，说明影响，可影响结论，但不伪装成行内 finding。
 
 本地当前文件用可点击路径；历史版本另标 `SHA:path:line`，需要可点击证据时链接实际存在的版本快照文件。支持证据可在 diff 外。基于仓库规则的结论须引用实际读过且适用的规则最小行范围；不能只写“违反最佳实践”。
 
@@ -54,3 +68,5 @@
 - `inconclusive`：尚无足够证据裁定，或没有实际可审变更，例如基线不明确、关键调用方无法读取、冲突未解或关键验收无法核实。说明缺口，不把它写成代码已证实有错。
 
 空 findings 不自动等于正确；未运行全量测试也不自动等于不可裁定，依据关键行为的实际证据判断。报告落盘成功与代码是否正确是两个不同结论。
+
+修复效果复审另给 `已解决 / 未完全解决 / 无法判定` 的修复结论：全部选定旧问题有关闭或有依据的不再适用结论、且相关回归无阻塞，才能判已解决并分别统计实际解决与不再适用。尚有确定未解决项或阻塞回归则未完全解决；关键项仅缺证则无法判定。patch 结论只覆盖声明的 diff，不能用修复增量的 patch is correct 掩盖旧问题仍存在。没有新 diff 时可省略 patch 结论，仍交付旧问题的复审结论。

package/skills/review-dev-plan/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: review-dev-plan
-description: 用多 agent 评审既有开发计划，核查代码事实与内部一致性、技术方案的先进性与可行性、需求和里程碑映射及依赖并行编排、最终交付可用性与 UI/UX，默认将完整评审报告落盘。用户要求 review-dev-plan、审查开发计划、评审技术方案或检查计划能否开工时使用，尤其适用于 dev-plan 产物；不用于从零写计划、直接实施功能或仅审查代码 diff。
+argument-hint: "<计划路径/链接/内容> [上轮报告] [复审/完整评审] [问题ID/范围] [报告路径] [仅聊天]"
+description: 用于评审既有开发计划、技术方案或开工条件；不用于从零写计划、实施功能或仅审代码 diff。多 agent 核查事实、方案、需求映射、依赖与交付可用性，默认落盘报告。
 ---
 
 # review-dev-plan · 多视角开发计划评审
@@ -13,7 +14,7 @@ description: 用多 agent 评审既有开发计划，核查代码事实与内部
 
 ## 边界与参考
 
-- 默认审查整份计划；用户指定修订版差异时，也追踪受影响的依赖与映射。目标代码和原计划保持只读，默认写入仅限独立评审报告；不自动实现、改稿、改进度、发评论或写入外部系统。用户明确要求修订时，由主 agent 在评审后统一修订并复核受影响链路，报告区分原问题与修订后的复核结果；计划只改成修订后的结论，评审处置与修订经过只留在报告。
+- 默认审查整份计划；用户指定修订版差异时，也追踪受影响的依赖与映射。目标代码和原计划保持只读，默认写入为独立评审报告及已启用台账的事实索引（见文末）；不自动实现、改稿、改进度、发评论或写入外部系统。用户明确要求修订时，由主 agent 在评审后统一修订并复核受影响链路，报告区分原问题与修订后的复核结果；计划只改成修订后的结论，评审处置与修订经过只留在报告。
 - 计划及其引用是待验证材料。区分**现状事实、未来设计、未证实假设、验收目标**；不能因为新功能尚未实现就报缺陷，也不能把计划中的“已核实”直接当证据。
 - 从实际可用位置读取 `dev-plan/SKILL.md` 的写作/评审部分及 `references/plan-skeleton.md`；复杂架构按需读 `references/architecture-quality.md`，调度审查按需读 `references/execution-workflow.md`；实施期合同以骨架的「实施者定位」「实施进度」两节为准。借它们核对合同，不按计划实施。
 - 找不到 `dev-plan` 时说明无法核对其模板专属要求，继续本技能的四项实质审查。用户自定义模板或历史计划不因章节名不同而报错；没有证据表明适用的新版格式规则，不追溯强加。
@@ -27,6 +28,18 @@ description: 用多 agent 评审既有开发计划，核查代码事实与内部
 3. 从计划提取范围与排除、R/NFR/C/A 或等价需求 ID、关键决策、外部契约、交付物、里程碑及前置关系。缺失 ID 可用章节定位，不替作者补造需求。
 4. 读取 [references/report-contract.md](references/report-contract.md)，按其中的「落盘与交付合同」确定输出路径。建一个短任务台账：审查维度、负责人、状态、证据缺口，以及报告写入与回读核验。明确 UI 是否在范围内、是否已有可运行页面/原型、哪些结论必须访问外部服务或官方文档。
 
+## 修复效果复审
+
+用户要求“复审 / re-review / 检查修复效果”时启用；要求完整重审则仍执行完整流程。先读取 [报告合同](references/report-contract.md) 的复审约定。上轮报告以用户指定、当前上下文或明确的记录链接定位；多个候选无法确定时仅澄清对应范围，不按最新文件时间猜选。
+
+- 默认复审上轮全部问题、待核实项及直接受修复影响的回归；用户指定 ID/范围时只核对该范围，其余明确未复核。没有可用上轮报告时可继续当前对象审查，但不能声称旧问题已逐项关闭。
+- 当前原文可由上轮报告的“评审对象”引用定位，按报告目录解析相对路径并核实身份；原文参数可在唯一明确时省略。读取已有处置节或 applied 文档，逐项验证原问题和修订影响的关联内容，不把“已 applied”直接当复审通过。
+- 输出逐项复审表，沿用来源 ID 并保留上轮报告链接/版本。新一轮默认另存报告，保留历史结论；启用台账时登记独立评审对象并关联前轮，不能用本轮局部通过覆盖前轮未核查范围。
+
+```text
+$review-dev-plan goal/LOGIN.md，对照 goal/LOGIN.review.md 复审修复效果，逐项记录结果。
+```
+
 ## 2. 编排四个独立审查视角
 
 先读 [references/review-lenses.md](references/review-lenses.md) 的对应节，再分派下表。**有多 agent 工具时实际启动 subagents**，不是在同一段回答里扮演四个角色。主 agent 保留综合裁定职责。
@@ -78,6 +91,7 @@ description: 用多 agent 评审既有开发计划，核查代码事实与内部
 
 报告至少包含：
 
+- 报告头的「评审对象」：原开发计划的可点击引用、类型、所审版本与范围；本地路径相对实际报告目录，回读时核验，使 `apply-doc-review` 可仅接收报告参数。
 - 按严重度排序、编号的问题，每条定位到计划行或稳定章节，并附行为级代码/规则/外部证据。
 - 四个维度的审查覆盖及未核实项；UI 分清文档推演、原型走查和实际浏览器验证。
 - 需求到交付的映射缺口，以及建议的依赖顺序、可并行任务、共享资源负责人和最终集成验收。没有安全并行空间时给出具体原因。
@@ -86,3 +100,9 @@ description: 用多 agent 评审既有开发计划，核查代码事实与内部
 **没有确认问题时允许空 findings；有未核实的关键前提时不能据此判 Ready。计划评审通过也不表示功能已实现或上线可用。**
 
 交付前确认：报告已写入并回读、内容符合上述合同、文件链接指向实际产物。最终回复给出报告链接、建议状态及关键问题/待核实项摘要；用户明确要求仅聊天时，直接在聊天中交付完整报告。写入失败时按落盘合同说明未完成项，不把聊天摘要算作完成。
+
+## 项目状态回写
+
+若仓库已登记状态台账，或存在仓根 `.xgent-ai/sdlc/protocol.md`（兼容已有 `docs/project-status/protocol.md`；两套并存且未登记切换时先核对，不能双写），交付原产物后读取台账的回写规则（默认目录读上述协议），按其格式新增本次事实记录并刷新受影响的状态页与必要索引；未启用时不自动建表，不依赖另装技能。只读/仅聊天/不保存要求优先，登记失败须说明，不影响如实交付已完成的原产物。
+
+每次实际评审登记独立评审 ID、计划版本、覆盖范围、建议状态与报告路径；复审关联前轮。评审建议与计划自报状态分别保留，当前就绪按台账协议核对证据，不直接改原计划；建议 Ready 不表示已实施。

package/skills/review-dev-plan/references/report-contract.md

@@ -9,6 +9,36 @@
 - 最终聊天回复只给实际报告链接、建议状态和关键问题/待核实项摘要，避免重复整份报告；明确仅聊天时才在聊天中交付完整报告。
 - 无可用文件写入工具或写入失败时，明确说明“报告未落盘”、原因与目标路径，在聊天中提供完整报告以保留结果，并将落盘标为未完成；不能声称已保存或给出不存在的产物链接。
 
+## 原文档引用（报告头）
+
+报告标题后、findings 前必须写「评审对象」，供 `apply-doc-review` 仅凭报告定位原文；即使没有 findings 也保留。每个实际评审目标一行，背景资料和关联 PRD 不混作修订目标。
+
+```markdown
+## 评审对象
+
+| 类型 | 原文档 | 所审版本 | 评审范围 |
+| --- | --- | --- | --- |
+| 开发计划 | [<原文档标题>](<相对报告所在目录的原文路径或稳定 URL>) | <内容 hash / 可取回版本；不可得则 unknown> | <全文或指定章节/里程碑 ID> |
+```
+
+- 本地链接按**实际报告所在目录**计算，不能按当前工作目录、仓根或默认报告位置计算；含空格路径使用合法 Markdown 链接语法。不写机器绝对路径，原文位置与文件名不变。另存到指定目录或带日期的报告时重新核对链接。
+- 远程原文用稳定 URL 并注明可用版本；输入只有聊天文本且没有持久原文时，原文档栏写「聊天输入，无原文路径」，不伪造链接，说明 apply 时需可定位的目标。
+- 回读报告时沿引用打开原文，核对类型、身份、版本与范围；原文已变化时说明所审基线及适用性。后续处置保留此处的历史所审版本，修后版本写入处置节。
+
+## 复审记录
+
+复审报告在标题及评审对象之后注明：上轮报告的相对链接与版本、所审对象的前后版本、本轮范围、已有处置记录链接，以及“修复效果复审”或“完整重审”。历史报告与原结论保持不变；默认按本合同另存新报告。
+
+在原报告结构中增加“上轮问题复审”表，与本轮新增问题分开：
+
+| 来源报告 / F-ID或稳定章节 | 上轮问题与结论 | 已有处置 / 修后版本 | 本轮结果 | 当前证据 / 验证 | 剩余动作 |
+| --- | --- | --- | --- | --- | --- |
+
+- 本轮结果统一用：**已解决、仍存在、部分解决、回归、待核实、不再适用、本轮未复核**。已解决需符合原问题的关闭判据；回归需有先前解决及当前再次失败的证据；不再适用须有范围/契约变化依据，不代表实际修复。缺证不能记关闭，未选中的旧项标本轮未复核。
+- 来源身份使用“报告路径/原始版本 + F-ID”，有台账时同时保留评审对象 ID；同一链路沿用旧编号。多份报告的同号问题不合并，新问题分配未占用编号并明确属于本轮；同根因合并时保留来源映射，不重新编号抹掉历史。
+- 默认覆盖上轮全部问题及待核实项；用户限定范围时逐项列出未复核项或其完整 ID 清单。读取处置记录后独立核对实际结果，保留旧证据是否仍适用的理由；只检查修复影响到的必要回归，不自动重跑无关全量验证。
+- 总结分别给出“旧问题解决情况”“修复引入的新问题”“未覆盖/缺证范围”。本轮没有新增 findings 不等于旧问题已关闭；部分通过不扩大成整体通过。复审表结果是检查结论，SDLC 回写仍按仓内协议的固定状态与范围登记，不自造 state 枚举。
+
 ## 什么进入 findings
 
 确认的问题须同时具备：计划中的可定位主张或缺口、已核实的依据、具体触发/受影响场景、对本期目标的实际后果、可执行的最小修订。建议作者换个人偏好的技术、堆更多章节、覆盖无关老问题，都不算。

package/skills/review-prd/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: review-prd
-description: 评审既有 PRD 或产品需求文档，核实代码现状与依赖，审查创新性、先进性、可用性、便捷体验、美观 UI、AI 赋能、SMAR、UAT 预期状态及分期终验，默认将完整评审报告落盘。用户要求 review-prd、review PRD、需求评审或检查需求是否合理且可验收时使用；不用于从零写 PRD、评审技术开发计划或仅审查代码 diff。
+argument-hint: "<PRD路径/链接/内容> [上轮报告] [复审/完整评审] [问题ID/范围] [报告路径] [仅聊天]"
+description: 用于评审既有 PRD 的合理性、产品质量与可验收性；不用于从零写 PRD、评审技术计划或代码 diff。核实代码现状、需求、体验、UAT 与分期，默认落盘报告。
 ---
 
 # review-prd · 基于代码事实的产品需求评审
@@ -13,7 +14,7 @@ description: 评审既有 PRD 或产品需求文档，核实代码现状与依
 
 ## 边界与参考
 
-- 默认审查整份 PRD；指定差异或局部范围时，同时追踪受影响的场景、需求、验收和分期。原 PRD 与代码保持只读，默认写入仅限独立评审报告；不自动实现、改稿、写 SPMS 或发送评论。用户明确要求修订时，先形成可追踪的问题，再统一修订并复核；报告保留处置记录，PRD 正文只保留修订后的产品结论。
+- 默认审查整份 PRD；指定差异或局部范围时，同时追踪受影响的场景、需求、验收和分期。原 PRD 与代码保持只读，默认写入为独立评审报告及已启用台账的事实索引（见文末）；不自动实现、改稿、写 SPMS 或发送评论。用户明确要求修订时，先形成可追踪的问题，再统一修订并复核；报告保留处置记录，PRD 正文只保留修订后的产品结论。
 - 区分**现状事实、目标能力、用户/平台约束、未证实假设、验收门槛与观察/PoC 基线**。新能力尚未实现不是 PRD 缺陷；代码当前行为也不是禁止产品演进的理由。报告指出增量与前置，不擅自把当前实现固化为需求。
 - PRD 回答 what / why / 怎样算完成。用户旅程、信息层级、视觉要求、AI 产品行为属于产品设计；内部架构、表结构、端点拆分、模型/算法选型与技术里程碑属于开发计划。UAT 定义角色、场景、预期状态与清晰判据；测试脚本、造数、故障注入、工具及 TC 创建属于测试计划。已给定技术约束、外部产品契约与作为产品能力的评测台可以保留，不能机械按技术词判越界。
 - 在可用时读取 `prd/references/product-quality.md` 校准产品质量规则；采用该模板的文档再按需读 `prd/references/prd-skeleton.md`。找不到 `prd` 时继续按本技能的实质标准评审，不要求安装依赖。用户自定义模板或历史 PRD 不因章节名、编号、缺少 TC 或未录入 SPMS 被判不合格。
@@ -27,6 +28,18 @@ description: 评审既有 PRD 或产品需求文档，核实代码现状与依
 4. 将会改变产品选择的现状主张和前置条件列入核实清单：声称已支持、未支持、可复用、无需改动、兼容、已验证及性能数字等。标清它们是事实还是未来目标。
 5. 读取 [references/report-contract.md](references/report-contract.md)，确定报告路径；记录四个审查维度及代码核实、报告写入、回读核验的状态。事实能查就先查，只向用户询问无法从证据推出的产品决定；缺少某项输入时继续不依赖它的审查。
 
+## 修复效果复审
+
+用户要求“复审 / re-review / 检查修复效果”时启用；要求完整重审则仍执行完整流程。先读取 [报告合同](references/report-contract.md) 的复审约定。上轮报告以用户指定、当前上下文或明确的记录链接定位；多个候选无法确定时仅澄清对应范围，不按最新文件时间猜选。
+
+- 默认复审上轮全部问题、待核实项及直接受修复影响的回归；用户指定 ID/范围时只核对该范围，其余明确未复核。没有可用上轮报告时可继续当前对象审查，但不能声称旧问题已逐项关闭。
+- 当前原文可由上轮报告的“评审对象”引用定位，按报告目录解析相对路径并核实身份；原文参数可在唯一明确时省略。读取已有处置节或 applied 文档，逐项验证原问题和修订影响的关联内容，不把“已 applied”直接当复审通过。
+- 输出逐项复审表，沿用来源 ID 并保留上轮报告链接/版本。新一轮默认另存报告，保留历史结论；启用台账时登记独立评审对象并关联前轮，不能用本轮局部通过覆盖前轮未核查范围。
+
+```text
+$review-prd docs/PRD-login.md，对照 docs/PRD-login.review.md 复审修复效果，逐项记录结果。
+```
+
 ## 2. 编排四个审查视角
 
 先读 [references/review-lenses.md](references/review-lenses.md) 的对应节，再分派。各视角都以用户约束为边界，不为凑问题扩大产品范围。
@@ -76,9 +89,16 @@ PRD 与基线：{PRD 绝对路径及版本；代码仓根、commit/dirty、日
 
 报告至少包含：
 
+- 报告头的「评审对象」：原 PRD 的可点击引用、类型、所审版本与范围；本地路径相对实际报告目录，回读时核验，使 `apply-doc-review` 可仅接收报告参数。
 - 按严重度排序且可定位的问题，附用户场景、实际后果、行为级证据、最小产品修订与复核条件。
 - 代码现状核实矩阵、关键依赖和待核实项；区分静态代码、现有测试、实际运行与浏览器证据，不把尚待开发的目标报成当前缺陷。
 - 四维覆盖及六个产品设计维度的实质结论、SMAR/UAT 与分期终验的断链；不因缺少固定章节或 TC 判错。
 - 建议结论 **通过 / 需修订 / 需补证**，写清阻塞范围与解除条件；有价值的非阻塞机会与修订优先顺序。
 
 **评审通过仅表示在已核实范围内可作为开发/测试计划的输入，不表示功能已实现、性能已实测、UI 已验证或可直接上线。** 最终聊天回复给实际报告链接、结论和关键问题/待核实项摘要。写入失败时说明「报告未落盘」并按合同保留完整内容，不能链接不存在的产物。
+
+## 项目状态回写
+
+若仓库已登记状态台账，或存在仓根 `.xgent-ai/sdlc/protocol.md`（兼容已有 `docs/project-status/protocol.md`；两套并存且未登记切换时先核对，不能双写），交付原产物后读取台账的回写规则（默认目录读上述协议），按其格式新增本次事实记录并刷新受影响的状态页与必要索引；未启用时不自动建表，不依赖另装技能。只读/仅聊天/不保存要求优先，登记失败须说明，不影响如实交付已完成的原产物。
+
+每次实际评审登记独立评审 ID、PRD 版本、覆盖范围、原结论与报告路径；复审关联前轮，保留历史，不因通过改写 PRD 实施状态。台账更新属于已有跟进协议的产物索引，不修改原 PRD。

package/skills/review-prd/references/report-contract.md

@@ -8,6 +8,36 @@
 - 主 agent 单写完整报告并回读实际文件，核对 findings、待核实项、代码矩阵、覆盖、映射/分期、结论和修订顺序齐全；检查引用定位与文件链接。空 findings、缺源码或「需补证」不免除落盘。
 - 最终聊天给实际报告链接、结论与关键摘要；仅聊天模式在聊天交付完整报告。写入工具不可用或失败时明确「报告未落盘」、原因与目标路径，在聊天保留完整结果，将保存标为未完成；不能链接不存在的文件。
 
+## 原文档引用（报告头）
+
+报告标题后、findings 前必须写「评审对象」，供 `apply-doc-review` 仅凭报告定位原文；即使没有 findings 也保留。每个实际评审目标一行，背景资料和关联计划不混作修订目标。
+
+```markdown
+## 评审对象
+
+| 类型 | 原文档 | 所审版本 | 评审范围 |
+| --- | --- | --- | --- |
+| PRD | [<原文档标题>](<相对报告所在目录的原文路径或稳定 URL>) | <内容 hash / 可取回版本；不可得则 unknown> | <全文或指定章节/需求 ID> |
+```
+
+- 本地链接按**实际报告所在目录**计算，不能按当前工作目录、仓根或默认报告位置计算；含空格路径使用合法 Markdown 链接语法。不写机器绝对路径，原文位置与文件名不变。另存到指定目录或带日期的报告时重新核对链接。
+- 远程原文用稳定 URL 并注明可用版本；输入只有聊天文本且没有持久原文时，原文档栏写「聊天输入，无原文路径」，不伪造链接，说明 apply 时需可定位的目标。
+- 回读报告时沿引用打开原文，核对类型、身份、版本与范围；原文已变化时说明所审基线及适用性。后续处置保留此处的历史所审版本，修后版本写入处置节。
+
+## 复审记录
+
+复审报告在标题及评审对象之后注明：上轮报告的相对链接与版本、所审对象的前后版本、本轮范围、已有处置记录链接，以及“修复效果复审”或“完整重审”。历史报告与原结论保持不变；默认按本合同另存新报告。
+
+在原报告结构中增加“上轮问题复审”表，与本轮新增问题分开：
+
+| 来源报告 / F-ID或稳定章节 | 上轮问题与结论 | 已有处置 / 修后版本 | 本轮结果 | 当前证据 / 验证 | 剩余动作 |
+| --- | --- | --- | --- | --- | --- |
+
+- 本轮结果统一用：**已解决、仍存在、部分解决、回归、待核实、不再适用、本轮未复核**。已解决需符合原问题的关闭判据；回归需有先前解决及当前再次失败的证据；不再适用须有范围/契约变化依据，不代表实际修复。缺证不能记关闭，未选中的旧项标本轮未复核。
+- 来源身份使用“报告路径/原始版本 + F-ID”，有台账时同时保留评审对象 ID；同一链路沿用旧编号。多份报告的同号问题不合并，新问题分配未占用编号并明确属于本轮；同根因合并时保留来源映射，不重新编号抹掉历史。
+- 默认覆盖上轮全部问题及待核实项；用户限定范围时逐项列出未复核项或其完整 ID 清单。读取处置记录后独立核对实际结果，保留旧证据是否仍适用的理由；只检查修复影响到的必要回归，不自动重跑无关全量验证。
+- 总结分别给出“旧问题解决情况”“修复引入的新问题”“未覆盖/缺证范围”。本轮没有新增 findings 不等于旧问题已关闭；部分通过不扩大成整体通过。复审表结果是检查结论，SDLC 回写仍按仓内协议的固定状态与范围登记，不自造 state 枚举。
+
 ## 什么进入 findings
 
 确认的问题同时具备：PRD 可定位的主张/缺口、已核实依据、具体用户场景/触发、对已确认目标的实际后果、可执行的最小产品修订。每条一个独立根因，重复症状合并但保留关键定位。纯格式、偏好或无关旧代码问题不进入 findings。