@xgent-ai/skills 0.3.0 → 0.5.0

package/skills/react/references/react19-migration.md

@@ -0,0 +1,407 @@
+---
+name: react-19-migration
+description: Upgrade React 18 source and test files to React 19 — removed APIs, ref as a prop, defaultProps, test-utils, and StrictMode changes.
+license: MIT
+last_reviewed: 2026-09-26
+---
+
+# React 19 migration — removed APIs, source rewrites, and tests
+
+## Contents
+
+- [Ground rule](#ground-rule--an-upgrade-pr-changes-api-surface-only)
+- Source files: [root API](#pattern-1--root-api-render--hydrate--unmountcomponentatnode) · [findDOMNode](#pattern-2--finddomnode--a-ref-on-the-dom-element) · [forwardRef](#pattern-3--forwardref--ref-as-a-prop) · [defaultProps](#pattern-4--defaultprops-on-function-components--default-parameters) · [legacy context](#pattern-5--legacy-context--createcontext) · [string refs](#pattern-6--string-refs--createref-or-callback-refs) · [propTypes](#pattern-7--proptypes-are-silently-ignored) · [JSX transform](#pattern-8--new-jsx-transform-and-unused-react-imports) · [TypeScript](#pattern-9--typescript-only-changes)
+- Test files: [act](#test-1--import-act-from-react) · [test-utils](#test-2--replace-the-rest-of-react-domtest-utils) · [react-test-renderer](#test-3--react-test-renderer-is-deprecated) · [StrictMode counts](#test-4--strictmode-call-counts-what-actually-changed) · [act warnings](#test-5--not-wrapped-in-act-warnings)
+- [Scan checklist](#scan-checklist) · [Decision table](#decision-table--react-19-fix-by-symptom)
+
+## When to apply
+
+- Upgrading `react` / `react-dom` from 18 to 19
+- Errors after the upgrade: `ReactDOM.render is not a function`, `findDOMNode is not a function`, a missing `act` export, the "outdated JSX transform" warning
+- Code uses `forwardRef`, `defaultProps` on function components, `contextTypes`, string refs, or `react-dom/test-utils`
+- Tests fail or change call counts after the upgrade
+
+Most mechanical rewrites have official codemods. Run them first, then fix what's left by hand:
+
+```bash
+npx codemod@latest react/19/migration-recipe       # render/hydrate, string refs, act import, useFormState, propTypes
+npx types-react-codemod@latest preset-19 ./src     # TypeScript type changes
+```
+
+## Ground rule — an upgrade PR changes API surface only
+
+Keep the upgrade diff limited to removed or changed APIs. `createRoot`, `useTransition`, `startTransition`, `useDeferredValue`, `Suspense`, and `lazy` work the same in React 19 — leave that logic untouched. Adopt new APIs ([`use`](data-fetching.md#pattern-5--use-suspense-boundaries-for-non-critical-data), [Actions](actions.md)) in follow-up PRs once the upgrade is green; mixing the two makes regressions impossible to bisect.
+
+```bash
+# Files the upgrade touched that also contain concurrent logic — review each diff:
+git diff --name-only main... | xargs grep -lE "useTransition|useDeferredValue|startTransition|<Suspense" 2>/dev/null
+```
+
+## Source files
+
+### Pattern 1 — Root API: `render` / `hydrate` / `unmountComponentAtNode`
+
+All three are removed from `react-dom`.
+
+**Incorrect (React 18 legacy root):**
+
+```tsx
+import ReactDOM from 'react-dom'
+
+ReactDOM.render(<App />, container)
+ReactDOM.hydrate(<App />, container)
+ReactDOM.unmountComponentAtNode(container)
+```
+
+**Correct:**
+
+```tsx
+import { createRoot, hydrateRoot } from 'react-dom/client'
+
+const root = createRoot(container)
+root.render(<App />)
+
+const ssrRoot = hydrateRoot(container, <App />)
+
+root.unmount()  // needs the root object, not the container
+```
+
+`unmount()` needs the root that `createRoot` returned. If the old code only kept the container, store the root where it's created (a module variable, or a `Map` keyed by container for widgets that mount many roots).
+
+### Pattern 2 — `findDOMNode` → a ref on the DOM element
+
+**Incorrect:**
+
+```tsx
+class Tooltip extends React.Component {
+  componentDidMount() {
+    const width = findDOMNode(this).offsetWidth
+  }
+  render() {
+    return <div>{this.props.children}</div>
+  }
+}
+```
+
+**Correct:**
+
+```tsx
+class Tooltip extends React.Component {
+  nodeRef = React.createRef<HTMLDivElement>()
+
+  componentDidMount() {
+    const width = this.nodeRef.current!.offsetWidth
+  }
+  render() {
+    return <div ref={this.nodeRef}>{this.props.children}</div>
+  }
+}
+```
+
+Put the ref on the DOM element the code measures. A ref on a class component points to the instance, not its DOM, so `componentRef.current` is not a drop-in replacement for `findDOMNode(componentRef.current)`.
+
+### Pattern 3 — `forwardRef` → `ref` as a prop
+
+Function components receive `ref` as a regular prop. `forwardRef` still works in React 19, so converting is optional in the upgrade PR — do it when you touch the file.
+
+**Before:**
+
+```tsx
+const Input = forwardRef<HTMLInputElement, InputProps>((props, ref) => (
+  <input ref={ref} {...props} />
+))
+```
+
+**After:**
+
+```tsx
+function Input({ ref, ...props }: InputProps & { ref?: React.Ref<HTMLInputElement> }) {
+  return <input ref={ref} {...props} />
+}
+```
+
+`useImperativeHandle` is unchanged — only the wrapper goes away (see [Ref rule 3](component-patterns.md#ref-rule-3--use-useimperativehandle-to-limit-exposed-dom-surface)).
+
+Code that inspects children must read `element.props.ref`. `element.ref` is deprecated and warns: "Accessing element.ref is no longer supported. ref is now a regular prop."
+
+### Pattern 4 — `defaultProps` on function components → default parameters
+
+React 19 ignores `defaultProps` on function components. **Class components still support `static defaultProps`** — leave them alone.
+
+**Incorrect (silently ignored in React 19):**
+
+```tsx
+function Button({ label, variant }: Props) {
+  return <button className={variant}>{label}</button>
+}
+Button.defaultProps = { label: 'Click', variant: 'primary' }
+```
+
+**Correct:**
+
+```tsx
+function Button({ label = 'Click', variant = 'primary' }: Props) {
+  return <button className={variant}>{label}</button>
+}
+```
+
+Both mechanisms apply only when the prop is `undefined`; an explicit `null` is passed through either way, so the semantics match.
+
+Watch non-primitive defaults. `defaultProps = { items: [] }` created the array once; `{ items = [] }` creates a new array on every render and breaks `memo` and effect dependencies. Hoist it (see [Pattern 9](rerender-optimization.md#pattern-9--extract-stable-default-values-for-memoized-components)):
+
+```tsx
+const NO_ITEMS: Item[] = []
+
+function List({ items = NO_ITEMS }: Props) { /* ... */ }
+```
+
+### Pattern 5 — Legacy context → `createContext`
+
+`contextTypes`, `childContextTypes`, and `getChildContext` are removed.
+
+**Incorrect:**
+
+```tsx
+class App extends React.Component {
+  static childContextTypes = { theme: PropTypes.string }
+  getChildContext() { return { theme: 'dark' } }
+  render() { return <Toolbar /> }
+}
+
+class Button extends React.Component {
+  static contextTypes = { theme: PropTypes.string }
+  render() { return <button className={this.context.theme} /> }
+}
+```
+
+**Correct:**
+
+```tsx
+const ThemeContext = createContext('light')
+
+function App() {
+  return (
+    <ThemeContext value="dark">   {/* React 19; older versions use <ThemeContext.Provider> */}
+      <Toolbar />
+    </ThemeContext>
+  )
+}
+
+class Button extends React.Component {
+  static contextType = ThemeContext   // class consumers: modern contextType is fine
+  render() { return <button className={this.context} /> }
+}
+```
+
+Migrate the provider and every consumer in the same change. The old and new APIs don't see each other, so a half-migrated tree reads `undefined`. Search for all consumers first (`grep -rn "contextTypes" src/`) — they're often in other files.
+
+### Pattern 6 — String refs → `createRef` or callback refs
+
+**Incorrect:**
+
+```tsx
+class Search extends React.Component {
+  render() {
+    return (
+      <>
+        <input ref="input" />
+        <button onClick={() => this.refs.input.focus()}>Focus</button>
+      </>
+    )
+  }
+}
+```
+
+**Correct:**
+
+```tsx
+class Search extends React.Component {
+  input = React.createRef<HTMLInputElement>()
+  // or a callback ref: input: HTMLInputElement | null = null; <input ref={el => { this.input = el }} />
+
+  render() {
+    return (
+      <>
+        <input ref={this.input} />
+        <button onClick={() => this.input.current?.focus()}>Focus</button>
+      </>
+    )
+  }
+}
+```
+
+### Pattern 7 — `propTypes` are silently ignored
+
+React 19 removed the `propTypes` checks; declarations stay valid but nothing validates at runtime. React recommends migrating to TypeScript (`npx codemod@latest react/prop-types-typescript`). That is a separate change — don't delete `propTypes` in the upgrade PR. If they stay, say so in the code so readers don't assume runtime validation:
+
+```tsx
+// NOTE: React 19 no longer runs propTypes validation at runtime.
+// PropTypes kept for documentation and IDE tooling only.
+Button.propTypes = { label: PropTypes.string }
+```
+
+### Pattern 8 — New JSX transform and unused `React` imports
+
+React 19 requires the new JSX transform; without it you get "Your app (or one of its dependencies) is using an outdated JSX transform." With the new transform, `import React from 'react'` is only needed where the file references `React.*`.
+
+```tsx
+// Before
+import React, { useState } from 'react'
+
+// After (no React.* usage in the file)
+import { useState } from 'react'
+```
+
+```bash
+# Files importing React as a default that never reference React.*:
+grep -rlE "^import React[ ,]" src/ | xargs grep -L "React\."
+```
+
+### Pattern 9 — TypeScript-only changes
+
+These fail type checking, not at runtime. JavaScript projects need no change.
+
+| Change | Fix |
+|---|---|
+| `useRef()` requires an argument | `useRef<HTMLDivElement>(null)` or `useRef<number>(undefined)` |
+| Ref callbacks may not return a value (the return is now treated as a cleanup) | `ref={el => { instance = el }}`, not `ref={el => (instance = el)}` |
+| `ReactElement` props default to `unknown`, not `any` | Type the props, or run `types-react-codemod react-element-default-any-props` |
+
+`preset-19` in `types-react-codemod` handles most of these.
+
+## Test files
+
+Fix in this order — each step unblocks the next:
+
+1. `act` import
+2. `Simulate` → `fireEvent`
+3. The rest of `react-dom/test-utils`
+4. StrictMode call counts — measure, don't guess
+5. Remaining "not wrapped in act" warnings
+6. The custom render helper — check once per codebase, not per test
+
+### Test 1 — Import `act` from `react`
+
+**Incorrect (removed in React 19):**
+
+```tsx
+import { act } from 'react-dom/test-utils'
+```
+
+**Correct:**
+
+```tsx
+import { act } from 'react'
+```
+
+Codemod: `npx codemod@latest react/19/replace-act-import`. When `act` shares an import with other test-utils helpers, split it off and replace the rest (next section).
+
+### Test 2 — Replace the rest of `react-dom/test-utils`
+
+Every other `test-utils` export errors when called in React 19. Use React Testing Library:
+
+| `react-dom/test-utils` | Replacement |
+|---|---|
+| `act` | `import { act } from 'react'` |
+| `Simulate.click(el)`, `.change(el, init)`, `.submit`, `.keyDown` | `fireEvent.click(el)`, `fireEvent.change(el, init)`, … from `@testing-library/react` (same arguments) |
+| `renderIntoDocument` | `render` |
+| `findRenderedDOMComponentWithTag` / `...WithClass` | `getByRole`, `getByTestId`, or `container.querySelector` |
+| `scryRenderedDOMComponentsWithTag` | `getAllByRole` |
+| `isElement`, `isCompositeComponent`, `isDOMComponent` | Delete — RTL tests don't inspect component types |
+
+```tsx
+// Before
+import { act, Simulate } from 'react-dom/test-utils'
+Simulate.change(input, { target: { value: 'hello' } })
+
+// After
+import { fireEvent } from '@testing-library/react'
+fireEvent.change(input, { target: { value: 'hello' } })
+```
+
+### Test 3 — `react-test-renderer` is deprecated
+
+In React 19 it logs a deprecation warning and renders concurrently, so snapshots and synchronous assertions may shift. Move those tests to React Testing Library instead of re-recording snapshots.
+
+### Test 4 — StrictMode call counts: what actually changed
+
+StrictMode **still** runs one extra setup → cleanup → setup cycle for every Effect in development (see [Cleanup rule 3](effect-patterns.md#cleanup-rule-3--development-double-fire-is-intentional-fix-cleanup-not-the-guard)). Effect spy counts do not change because of the upgrade — if one did, find out why rather than editing the number.
+
+What changed in React 19 StrictMode:
+
+| Spy on | React 18 StrictMode | React 19 StrictMode |
+|---|---|---|
+| Component body (render) | 2 per render | 2 per render — unchanged |
+| `useEffect` setup | setup, cleanup, setup | Unchanged |
+| `useMemo` / `useCallback` factory on mount | Ran in both renders | Second render reuses the first result — count drops |
+| Ref callback on initial mount | Once | Invoked, cleaned up, invoked again — count rises |
+
+These counts only apply when the test renders inside StrictMode — an explicit `<StrictMode>` wrapper, a custom render helper, or RTL's `reactStrictMode` option. Check the helper once.
+
+Read the real numbers before editing any assertion:
+
+```bash
+npm test -- --watchAll=false --testPathPattern="<file>" 2>&1 | grep -E "Expected|Received"
+```
+
+Then match the difference to a row above. An unexplained change is a bug, not a new baseline.
+
+### Test 5 — "not wrapped in act(...)" warnings
+
+React recommends async `act`; the sync form "doesn't work in all cases" and will be removed:
+
+```tsx
+await act(async () => {
+  fireEvent.click(button)
+})
+```
+
+RTL's `findBy*` queries and `waitFor` already wrap `act`. Prefer them over manual `act` for anything that resolves asynchronously. Outside RTL, set `globalThis.IS_REACT_ACT_ENVIRONMENT = true` in the test setup.
+
+## Scan checklist
+
+```bash
+grep -rnE "ReactDOM\.(render|hydrate)\(|unmountComponentAtNode|findDOMNode" src/   # Pattern 1–2
+grep -rn "forwardRef" src/                                                           # Pattern 3 (optional)
+grep -rnE "\.defaultProps\s*=" src/                                                  # Pattern 4 — function components only
+grep -rnE "contextTypes|childContextTypes|getChildContext" src/                      # Pattern 5
+grep -rnE "ref=\"|this\.refs\." src/                                                  # Pattern 6
+grep -rnE "\.propTypes\s*=|static propTypes" src/                                    # Pattern 7
+grep -rn "useRef()" src/                                                             # Pattern 9 (TypeScript)
+grep -rnE "react-dom/test-utils|react-test-renderer" src/                            # Test 1–3
+```
+
+## Decision table — React 19 fix by symptom
+
+| Symptom | Fix |
+|---|---|
+| `ReactDOM.render` / `hydrate` is not a function | `createRoot(container).render()` / `hydrateRoot(container, ui)` |
+| `unmountComponentAtNode` is not a function | Keep the root object; call `root.unmount()` |
+| `findDOMNode` is not a function | Ref on the DOM element |
+| Function component defaults stopped applying | ES6 default parameters; hoist non-primitive defaults |
+| `this.context` is `undefined` in a class | Legacy context → `createContext` + `static contextType` |
+| `this.refs.x` is `undefined` | `createRef()` or a callback ref |
+| PropTypes warnings stopped appearing | Expected — migrate to TypeScript in a separate PR |
+| "outdated JSX transform" warning | Enable the automatic JSX runtime in the compiler config |
+| `act` import fails | `import { act } from 'react'` |
+| `Simulate` / other test-utils throw | React Testing Library equivalents |
+| StrictMode spy count changed | Match it to the table in Test 4; effect counts should not change |
+
+## When NOT to apply
+
+- **Class component `defaultProps`:** still supported — rewriting them as constructor logic loses the "only when `undefined`" semantics.
+- **Converting every `forwardRef` in the upgrade PR:** it still works; convert when you touch the file.
+- **Deleting `propTypes`:** they're harmless; replacing them with types is its own change.
+- **Adopting `use`, Actions, or `useOptimistic` during the upgrade:** stabilize first (see the ground rule).
+
+## Common failure modes
+
+| Mistake | Consequence |
+|---|---|
+| Changing effect-count assertions from 2 to 1 "because React 19 stopped double-invoking" | Wrong premise — tests go green while cleanup bugs go unnoticed |
+| Removing `static defaultProps` from class components | Needless rewrite; hand-rolled defaults often mishandle `false` and `0` |
+| `{ items = [] }` replacing `defaultProps` in a memoized component | New array every render; `memo` and effect deps break |
+| Migrating the legacy context provider but not all consumers | Consumers read `undefined` |
+| `componentRef.current` as a `findDOMNode` replacement on a class ref | Gets the instance, not the DOM node |
+| Mixing new-API adoption into the upgrade PR | Regressions can't be bisected |
+| Sync `act` around async updates | Flaky "not wrapped in act" warnings and missed updates |

package/skills/reflect/SKILL.md

@@ -0,0 +1,13 @@
+---
+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."
+disable-model-invocation: true
+---
+
+# Reflect
+
+The maintained workflow and reviewer templates now live in **agi-mode**. Read and execute [Reflection](../agi-mode/playbooks/reflection.md).
+
+Use only the current conversation and authorized materials. Preserve whether the user requested findings or also authorized skill edits; a reflection request alone does not authorize external tickets or global changes.
+
+Resolve the sibling path or the registered installation of `agi-mode`. This compatibility entry requires that skill; if unavailable, report the missing dependency and do not claim the review workflow ran.

package/skills/review-code/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: review-code
+description: 评审未提交变更（含 staged、unstaged、untracked）、指定 commit、commit 范围或相对基准分支的差异，可附开发计划核对本次实现，默认将有证据、按 P0–P3 排序的完整评审报告落盘。用户要求 review-code、代码审查、审查 diff 或提交前评审时使用；不用于单独评审开发计划、全仓质量普查或直接实现修复。
+---
+
+# review-code · 代码变更评审
+
+判断本次变更是否引入值得作者修复的缺陷，以及是否满足本次承诺的行为。以 Codex 原生 review 的缺陷门槛为准，补充需求符合性、跨文件影响和验证证据；不以问题数量衡量评审质量。
+
+**默认交付是完整 Markdown 报告：实际写入文件、回读核验，聊天给结论摘要与文件链接。用户明确要求仅聊天或不写文件时例外。** 代码和计划默认只读，不自动修复、更新计划进度、提交、发 PR 评论或审批 PR。用户同时授权修复时，先保留原始评审基线，再执行修复并区分复核结果。
+
+`references/` 相对本文件解析；目标仓路径、技术栈、规则和工具在运行时发现。语言跟随用户。本 skill 可独立工作，不依赖本机安装 Codex CLI 或社区 skill。
+
+## 1. 确定审查对象
+
+1. 读取适用的仓库和子目录指令、review 专项约定。用一句话概括变更意图，区分用户明确要求与从代码推断的意图；缺少提交说明不自动中止评审。
+2. 按 [references/git-scopes.md](references/git-scopes.md) 解析输入，固定仓库根、模式、base/target SHA、工作树快照、文件限制与可选计划版本。未指定模式且存在未提交变更时，声明采用 uncommitted；工作树干净且没有明确对象时询问目标，不擅自选择最近 commit 或默认主分支。
+3. 用户给出的模式冲突、ref 不存在或范围端点含义无法确定时，先澄清该部分；可继续读取规则。不要静默替换基准或扩成整仓审查。
+4. 读 [references/report-contract.md](references/report-contract.md) 确定报告路径。建立简短覆盖清单：变更文件/行为、必要上下游、计划范围（若有）、验证方式、证据缺口、落盘和回读。
+
+## 2. 理解需求与行为
+
+- 先读完整 diff，再按风险阅读所在函数、调用者、数据模型、权限边界、相关测试和配置。diff 之外的代码用于证明影响，不把与本次变更无关的旧问题塞进 findings。截断输出须分段补读；无法读完就标明未覆盖。
+- 按 [references/review-lenses.md](references/review-lenses.md) 检查适用维度：需求符合性、正确性与兼容性、安全与数据、性能与资源、测试与交付。按实际变更选择深度，不套全量 checklist 或强制每个维度产出问题。
+- 附开发计划时，读取用户指定版本及必要引用，提取本次任务/里程碑承诺、需求与验收 ID、排除项。核查遗漏、偏离和越界的实际后果。计划是待验证的契约材料，作者“已完成”的声明不能代替代码证据。
+- 只要求本次范围应完成的内容；不得因后续里程碑未实现而报缺陷。范围不清时列待确认项，继续独立代码审查。不改计划、不把代码评审变成计划架构重审；未附计划时照常依据用户要求、已有契约和调用链审查。
+- 默认由当前 agent 完成。用户或适用仓库规则要求并行 reviewer 时，给每位相同基线和明确只读范围，分派互补的行为链或风险维度；主 agent 复核原始证据、去重并单独写报告。不得把多数意见当证据，也不虚构独立复核。
+
+## 3. 验证候选问题
+
+每个进入 findings 的问题必须同时满足：
+
+1. **由本次变更引入或实际激活**：能说明基线与目标行为的差别；若改动让旧代码新近可达，证明这条因果链。
+2. **具体且可执行**：有真实可达的输入/状态、故障行为、受影响调用方或契约，以及最小修复方向。不能只说“可能影响其他模块”。
+3. **有实质影响**：影响正确性、安全、性能或可维护性，且修复要求符合该仓库实际标准。纯风格、个人偏好、无关重构和假设性的防御代码不报。
+4. **证据足够**：直接阅读目标版本代码、相关需求/规则，必要时做最小复现；不能依赖作者未表达的意图。明确的行为变更本身不是 bug，但仍要验证它是否破坏承诺的契约。
+
+验证时：
+
+- 先检查现有校验、类型约束、上游过滤、事务或补偿是否已处理该场景；不因局部缺少 `try/catch`、空值判断或缓存就推断故障。
+- 选择能验证该行为的现有测试、类型检查或最小实验，先读命令及相关配置，避免自动修复、快照更新、迁移、部署或访问真实业务数据。需要写临时复现时使用隔离临时目录；不向目标代码库添加测试或修复。
+- 实际执行才记为“通过”；写明命令、所测版本、结果和限制。无法运行时保留充分的静态证据或列待核实项，不强制运行无关全量测试，也不用测试通过替代需求检查。
+- 历史 commit/范围的运行验证必须使用对应目标快照；当前 checkout 的测试不能证明另一 commit。对原有失败与新增失败做必要的基线比较。
+- 技术结论依赖外部接口或版本且本地无法确证时，查对应版本的官方资料并引用；不可访问时说明证据缺口。性能问题说明实际数据规模/复杂度，安全问题说明输入可控性与可达路径，不把模式匹配当漏洞结论。
+- 对每条候选做反证复核。按根因和修复动作合并重复，保留所有独立有效问题；不设数量指标，不只留最严重几条。证据不足移入待核实项，不能降为 P3 混入 findings。
+
+## 4. 裁定、落盘与交付
+
+1. 按报告合同写精确短定位、单段问题说明、P0–P3 和置信度。主定位须与所审 diff 重叠；支持证据可在 diff 之外。规则对结论有实质贡献时，附该规则的文件和最小行范围。
+2. 核对覆盖清单以及版本是否发生变化。相关文件或计划变动时重审受影响结论；不能收敛时保留快照版本与缺口。报告新文件不纳入本轮审查对象。
+3. 完整报告先列确认问题，再列待核实项、覆盖与验证、可选计划符合性、总体结论和修复顺序。默认采用 `patch is correct / patch is incorrect / inconclusive`；最后一项是本 skill 为证据不足增加的状态，不伪称原生 Codex JSON 值。
+4. 写入并回读报告，检查问题、证据、基线、限制和结论完整，链接指向实际文件。空 findings 或无法充分验证也要保存；写入失败如实说明未落盘，聊天交付完整内容，不能宣称完成保存。
+
+调用示例（自然语言参数，不要求专用解析器）：
+
+```text
+使用 $review-code 审查当前未提交变更。
+使用 $review-code 审查未提交的 src/auth.ts 和 tests/auth.test.ts。
+使用 $review-code 审查 commit abc1234，参考 docs/plan/login.md 的 M2。
+使用 $review-code 审查 a1b2c3d..d4e5f6a，报告写到 docs/reviews/login.code-review.md。
+使用 $review-code 审查相对 origin/main 的差异。
+使用 $review-code 审查相对 main 的已提交差异，仅聊天输出。
+```

package/skills/review-code/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "代码变更评审"
+  short_description: "审查未提交、commit、范围或分支差异，可附开发计划，默认落盘完整报告"
+  default_prompt: "使用 $review-code 审查指定代码变更，核查可选开发计划，按 P0–P3 输出有证据的问题，将完整报告落盘并回读核验，回复结论摘要与报告链接。"

package/skills/review-code/references/git-scopes.md

@@ -0,0 +1,38 @@
+# 输入范围与 Git 取证
+
+开始时读取 `git rev-parse --show-toplevel`、`git status --short` 和 HEAD；如无 HEAD，单独处理首次提交前的工作树。命令从仓库根执行。下面尖括号是占位符，不可照抄；验证 ref 并解析成 SHA 后再使用。用户路径放在 `--` 后，正确引用空格和特殊字符；脚本收集文件名用 `-z`，不按空格拆分。
+
+## 四类输入
+
+| 输入 | 基线 → 目标 | 取证方式与边界 |
+| --- | --- | --- |
+| uncommitted，或未提交的指定文件 | HEAD → 当前工作树，另核对 index | `git diff --no-ext-diff --no-textconv HEAD --` 看 tracked 净差异；`git diff --cached` 和 `git diff` 区分 staged/unstaged；`git ls-files --others --exclude-standard -z` 枚举并读取 untracked |
+| 单 commit C | C 的第一父提交 → C | 先 `git rev-list --parents -n 1 <C>`；普通提交用 `git diff <C^1> <C> --`。根提交用 `git show --root --format= --no-ext-diff --no-textconv <C> --`；merge commit 默认第一父提交并注明，用户指定其他父提交时从其要求 |
+| commit 范围 A..B | A 的树 → B 的树 | `git diff <A> <B> --` 审查累计净效果，不叠加逐 commit 的中间问题；不混入当前工作树。A 是基线，不包含 A 自身引入的改动 |
+| 相对基准分支 BASE | merge-base(HEAD, BASE) → 当前工作树 | 固定 BASE 和 HEAD 的 SHA，用 `git merge-base --all <HEAD> <BASE>` 确认唯一共同祖先，再 `git diff <merge-base> --`。沿用原生 review 的 tracked 工作树语义，包含 staged/unstaged；不得误写成只审 committed |
+
+所有实际 diff/show 命令均加 `--no-ext-diff --no-textconv`，避免仓库自定义 diff 驱动执行。先用 `--name-status -M` 盘点增删改与重命名，再读取 patch 和必要全文。
+
+### 未提交与分支模式
+
+- staged 和 unstaged 可能相互抵消，即 `git diff HEAD` 为空而 index 非空。仍检查两层；仅存在于 index 的缺陷标注为“只提交 staged 内容时触发”，不能说当前工作树也有该缺陷。若用户只要求 staged，则基线为 HEAD、目标为 index，用 `git show :<path>` 读取完整目标文件。
+- 未初始化 HEAD 时，以空树为基线，读取 staged 新文件、工作树及 untracked；不要因 `git diff HEAD` 失败判定无变更。可用 `git diff --cached` 配合文件清单和全文。
+- 分支模式默认审查 tracked 工作树差异。先声明这一范围；untracked 不在该 diff 中，但应枚举，新增调用依赖它们时作为上下文读取。用户要求把新文件也纳入审查时，明确增加 untracked 范围并记录清单；未纳入的必要新文件形成覆盖限制，不能宣称完整实现已审。
+- 用户明确要求“只审已提交分支变更”时，用 `git diff <merge-base> <HEAD> --`。本地 dirty 内容仅记录，不作为目标代码。用户要求分支 tip 之间直接比较时用两端树差异，明确它不同于共同祖先比较。
+- untracked 按新增文件完整审查；忽略文件不自动纳入，除非用户明确点名。二进制、生成文件或子模块无法深入检查时，记录实际检查的指针/来源与缺口，不静默视为无风险。
+
+### 范围、父提交和 ref 异常
+
+- `A...B` 明确解释为 `merge-base(A, B) → B`，不等同 `A..B`。用户说“从 A 到 B，包含 A”时，以 `A^1 → B` 为范围；A 为根提交则以空树为基线。自然语言未说明是否包含起点且无法推断时询问。
+- 单 commit 为 merge 时，第一父提交差异是默认审查对象；不要依赖可能隐藏普通变更的 combined diff。冲突解决逻辑按需与其他父提交对照，记录实际审查父提交。
+- ref 验证可用 `git rev-parse --verify --end-of-options '<ref>^{commit}'`。不存在、浅克隆历史不足、无共同祖先或存在多个 merge-base 时，不擅自退回 HEAD~1 或任选基线；说明缺口并澄清/按已有授权补齐历史。
+- unmerged index 要明确记录；可以审查确定部分，但 unresolved conflict 不等于完整可运行快照，不给出无保留正确结论。
+- 用户限定文件时只对限定文件的变更出 findings，读取相关文件证明影响；另发现范围外线索可列覆盖建议，不静默扩大任务。
+
+## 固定版本与行号
+
+- 记录原始输入和解析后的完整 SHA、实际比较方式、dirty 状态、纳入文件清单；工作树/index/untracked 使用内容 hash 或等价可复查快照，不能只靠 `git status` 判断内容未变。包括影响结论的上下游文件与附带计划。
+- 历史版本的代码、调用方、测试与契约从目标树读取，如 `git show <target>:<path>`、`git grep <pattern> <target> --`；基线证据从 base 读取。执行环境的当前指令仍须遵守，涉及历史仓库约定时标明所用版本。
+- 不为读历史代码而 checkout、reset 或 stash 用户工作树。需要运行目标版本时用隔离临时检出或快照；确保命令在该版本执行，并记录快照路径和 SHA。
+- 默认使用目标侧的短行范围；删除行/删除文件可用基线侧，必须标记 old/base 及 SHA。重命名附旧路径；index 定位明确标 staged。引用历史版本时附 `SHA:path:line`，不要把当前文件链接冒充历史行内容。
+- 结束前比较固定基线与相关内容指纹。外部修改需重审受影响部分；写报告、临时验证产物不得污染本轮输入，也不能因此把用户的新改动一起排除。

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

@@ -0,0 +1,56 @@
+# 问题与报告合同
+
+## 落盘与交付
+
+- 默认保存完整 Markdown 报告；只有用户明确要求仅聊天/不写文件时跳过，不询问是否保存。
+- 路径优先级：用户指定路径 → 附带的本地计划同目录 `<计划名去扩展名>.code-review.md` → 仓库既有报告目录 → 当前工作区 `docs/reviews/<主题>.code-review.md`。无本地计划时，主题可用 `uncommitted`、`commit-<短SHA>`、`range-<短A>-<短B>` 或 `against-<基准分支短名>`；将分支中的 `/` 等路径字符转换为 `-`，不把 ref 直接作为目录。
+- 写前检查文件已存在与否。仅在用户明确授权更新/覆盖该报告时覆盖；否则另存 `<主题>.code-review.<YYYY-MM-DD>.md`、`<主题>.code-review.<YYYY-MM-DD>-2.md` 等未占用名称。指定路径冲突也遵守此规则，最终说明实际路径。不得把报告写到代码或原计划文件，即使名字碰巧一致。
+- 由当前主 agent 单独写入完整报告，回读实际文件核对内容与定位。空 findings、`inconclusive` 和部分覆盖不免除落盘。不要只写摘要或拼接未经裁定的 reviewer 回报。
+- 最终聊天给实际文件链接、总体结论和重要问题/限制摘要。写入失败时明确“报告未落盘”、原因和目标路径，聊天提供完整报告以保留结果，落盘仍标未完成；不链接不存在的文件。
+
+## 问题格式
+
+每条一个独立根因，优先级置于简短行动标题前（标题不超过 80 字符）；问题正文用一段说明触发条件、实际行为、影响和关键依据。不要在正文堆阅读日志。
+
+```markdown
+### F-01 · [P1] <简短、可执行的修复标题>
+
+- 定位：<目标路径:短行范围，target/index/base 侧及版本；须与 diff 重叠>
+- 问题：<在具体输入或状态下，改动如何导致故障，影响哪个调用方/契约，为什么是本次引入。单段。>
+- 证据：<上下游代码、需求/计划/仓库规则的精确定位，或复现命令与实际结果>
+- 修复与验证：<最小修复方向；验证该行为的断言/回归场景，不自动实施>
+- 置信度：<高/中及依据；可用 0–1 数值，但不把主观分值伪装成统计测量>
+```
+
+主定位取最小有意义的 diff 行范围，通常 1–5 行，避免超过 10 行。删除缺陷定位到基线侧删除行并标 SHA；缺失行为定位到应负责它的改动入口/调用点，不凭空造一个不存在文件的行号。完整需求遗漏确实没有 diff 锚点时，放计划符合性缺口，说明影响，可影响结论，但不伪装成行内 finding。
+
+本地当前文件用可点击路径；历史版本另标 `SHA:path:line`，需要可点击证据时链接实际存在的版本快照文件。支持证据可在 diff 外。基于仓库规则的结论须引用实际读过且适用的规则最小行范围；不能只写“违反最佳实践”。
+
+不强制给代码片段。确有助益时最多三行；`suggestion` 块仅含可直接替换的最小代码，保留原缩进，不在块内解释。自然语言足以说明修复时不生成 patch。
+
+## 严重度与置信度
+
+| 等级 | 含义 |
+| --- | --- |
+| P0 | 必须立即停止其他工作处理的普遍性严重故障，阻断发布/运行/主要使用，无须额外输入假设；极少使用 |
+| P1 | 紧急，应在下一修复周期处理的高影响缺陷；写明受影响条件与范围 |
+| P2 | 应修复的一般缺陷，有明确局部功能、兼容性、性能或维护后果 |
+| P3 | 有证据、值得修复但优先级低的小问题；纯风格和个人偏好不报 |
+
+严重度描述后果，置信度描述证据。只有猜测的风险属于待核实项，不以 P3 收纳。不要把所有安全字样都升为 P0，也不把未运行测试自动降格成已证实失败。
+
+## 完整报告顺序
+
+1. **确认问题**：按 P0 → P3 排序，F-01 等稳定编号。没有时写“未发现可确认的问题”，不凑数；复审沿用编号并区分已解决、仍存在、新增。
+2. **待核实/待决策项**：缺少什么证据、影响哪个结论、如何补证；无法访问的文件/环境、需求歧义、尚未运行的关键验证放这里。
+3. **覆盖与验证**：一句话意图；仓库根与日期；原输入、解析 SHA、比较方式、工作树/index 指纹或快照、文件限制、纳入/排除项；已审行为链与未覆盖部分；实际命令、目标版本、结果、失败原因。区分静态、测试、浏览器与外部资料证据；注明实际 reviewer 分工（若有）。
+4. **计划符合性（有计划才写）**：计划路径和版本、本次任务/里程碑；仅列相关需求的映射和缺口，包含未核实及后续范围。不要复制整份计划或更新其进度。
+5. **总体结论与修复顺序**：结论、1–3 句理由与覆盖限制；优先解除契约/数据/安全根因，再修局部行为，最后验证相关回归。明确解除阻塞的可观察条件，不把评审结论当作 merge/deploy 授权。
+
+### 正确性结论
+
+- `patch is incorrect`：有已证实影响正确性或形成实质阻塞的缺陷/本期需求缺口，引用对应编号或计划缺口。其余覆盖不足仍须说明。
+- `patch is correct`：在明确审查范围内未发现上述缺陷，证据足以支撑判断；非阻塞的小问题不自动否定正确性。表述为评审判断，不保证不存在未知 bug。
+- `inconclusive`：尚无足够证据裁定，或没有实际可审变更，例如基线不明确、关键调用方无法读取、冲突未解或关键验收无法核实。说明缺口，不把它写成代码已证实有错。
+
+空 findings 不自动等于正确；未运行全量测试也不自动等于不可裁定，依据关键行为的实际证据判断。报告落盘成功与代码是否正确是两个不同结论。

package/skills/review-code/references/review-lenses.md

@@ -0,0 +1,33 @@
+# 审查视角与取舍
+
+这些是调查线索，不是自动判错规则。每项仍须通过主流程的引入性、影响和证据门槛。
+
+| 视角 | 需要追踪的行为与证据 |
+| --- | --- |
+| 需求符合性 | 用户请求/计划中的本期验收 → 入口 → 实现 → 可观察结果；遗漏、误解和越界是否产生实际契约或范围后果。需求歧义列待决策，不用“常见做法”替作者决定 |
+| 正确性与兼容性 | 调用链和状态转换、边界与错误路径、重试/幂等/并发、事务与资源释放；API/类型/序列化/配置默认值变动对现有消费者的具体影响 |
+| 安全与数据 | 不可信输入是否可达危险操作、身份与对象级授权/租户隔离、敏感数据流、注入、路径与请求边界；数据迁移、约束、失败回滚和读写兼容性。报告敏感证据时隐藏实际密钥 |
+| 性能与资源 | 真实规模下的查询次数、无界读取/队列/循环、阻塞、缓存一致性、订阅或连接泄漏；复杂度与实测分开，不强制缓存/批处理，不虚构毫秒或容量 |
+| 测试与交付 | 测试断言是否能捕获改变的行为，mock 是否掩盖协议/权限/事务，回归用例能否在基线失败而目标通过；构建、入口接线、配置、依赖和部署产物是否一致 |
+
+## 可选开发计划
+
+只核对所审变更承担的任务与验收。最小映射为 `需求/章节 → 本次任务 → 实现证据 → 验证状态`，状态区分已核实、存在缺陷、未核实、后续范围。不要求计划必须采用某个模板或有正式 ID。
+
+计划符合性发现问题后仍继续安全与正确性审查，不用“先修计划偏差”跳过其他风险。用户明确改变需求时以当前用户要求为准，列出与旧计划的差异；不自动改计划，也不把服从新要求视为缺陷。没有被本次变更触及/承诺的旧功能缺失不属于新增问题。
+
+无测试本身不自动成为 finding。说明本次改变的哪个重要行为无法被现有测试保护，以及具体失败风险；若缺陷已在 findings 中，测试建议归入同条，避免重复计算。仅凭测试覆盖率数字不能宣布质量达标。
+
+有 UI 时按变更检查主要路径、加载/空/错误状态、键盘操作和可访问性。静态推演、实际浏览器走查、自动化结果分开记录；没有运行页面不声称视觉或交互验证通过。
+
+## 来源与有意取舍
+
+以下是本 skill 的设计来源，运行评审时无需加载来源文件：
+
+- **Codex CLI 0.159.3**（2026-10-02 本机 `codex --version`、`codex review --help` 及二进制内嵌 review prompt）：沿用新增且可行动的缺陷门槛、具体受影响代码证据、允许空 findings、P0–P3、短 diff 定位、适用仓库规则引用、单段说明和不自动修复。官方 [CLI 文档的 review 说明](https://learn.chatgpt.com/docs/codex/cli) 也列出未提交、commit、基准分支三类入口。
+- **`local/code-review`** 的 `SKILL.md`、`references/requesting-code-review.md`、`references/verification-before-completion.md`：吸收明确评审范围、证据先于结论、反馈先核实；不引入每个实现任务都必须再派 reviewer、固定包管理器或自动修复的流程。
+- **`local/code-reviewer/SKILL.md`**：吸收快速筛查逻辑、导入导出、安全和性能线索；不采用每次保存触发、固定函数行数阈值、模式匹配即报错或未经实测的速度承诺。
+- **`local/code-reviewer2/SKILL.md`** 与 `references/spec-compliance-review.md`、`references/review-checklist.md`、`references/report-template.md`：吸收先理解意图、需求映射、多维审查和可行动反馈；不强制赞美、建议代码或因需求未通过而停止其他审查。
+- **`skills/review-dev-plan/references/report-contract.md`**：沿用完整报告默认落盘、路径优先级、防覆盖、单写者、回读和失败披露。代码报告用 `.code-review.md` 区分计划报告的 `.review.md`；不继承计划的就绪状态或固定四 reviewer 编排。
+
+commit 范围、可选计划映射和 `inconclusive` 是本 skill 的扩展。默认 Markdown 是有意选择，并不宣称与 Codex 原生 review JSON schema 完全相同。以上内容是综合后的工作约定，不复制社区技能的整套协议。