peaks-loop 4.1.9 → 4.1.11

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (43) hide show
  1. package/.claude-plugin/marketplace.json +2 -2
  2. package/CHANGELOG.md +72 -0
  3. package/dist/cli/commands/_register.js +2 -0
  4. package/dist/cli/commands/code-review-commands.d.ts +1 -1
  5. package/dist/cli/commands/code-review-commands.js +23 -37
  6. package/dist/cli/commands/code-review-ocr-delegate-record.d.ts +3 -0
  7. package/dist/cli/commands/code-review-ocr-delegate-record.js +73 -0
  8. package/dist/cli/commands/code-review-ocr-delegate.d.ts +12 -0
  9. package/dist/cli/commands/code-review-ocr-delegate.js +140 -0
  10. package/dist/cli/commands/code-review-run-ocr-18.d.ts +11 -0
  11. package/dist/cli/commands/code-review-run-ocr-18.js +127 -0
  12. package/dist/cli/commands/strat-tact-command-helpers.d.ts +16 -0
  13. package/dist/cli/commands/strat-tact-command-helpers.js +162 -0
  14. package/dist/cli/commands/strat-tact-commands.d.ts +3 -0
  15. package/dist/cli/commands/strat-tact-commands.js +176 -0
  16. package/dist/services/lint/detect-ocr-18.js +1 -1
  17. package/dist/services/lint/ocr-18-acquire.d.ts +1 -1
  18. package/dist/services/lint/ocr-18-acquire.js +2 -2
  19. package/dist/services/lint/ocr-18-allowlist.d.ts +30 -0
  20. package/dist/services/lint/ocr-18-allowlist.js +165 -0
  21. package/dist/services/lint/ocr-18-delegate-packet.d.ts +84 -0
  22. package/dist/services/lint/ocr-18-delegate-packet.js +175 -0
  23. package/dist/services/lint/ocr-18-delegate-payload.d.ts +67 -0
  24. package/dist/services/lint/ocr-18-delegate-payload.js +208 -0
  25. package/dist/services/lint/ocr-18-delegate-record.d.ts +42 -0
  26. package/dist/services/lint/ocr-18-delegate-record.js +223 -0
  27. package/dist/services/lint/ocr-18-language-routing.d.ts +96 -0
  28. package/dist/services/lint/ocr-18-language-routing.js +148 -0
  29. package/dist/services/lint/ocr-18-multi.d.ts +54 -0
  30. package/dist/services/lint/ocr-18-multi.js +184 -0
  31. package/dist/services/lint/ocr-multilang-adapter.d.ts +45 -7
  32. package/dist/services/lint/ocr-multilang-adapter.js +133 -94
  33. package/dist/services/rd/ast-gate.d.ts +19 -12
  34. package/dist/services/rd/ast-gate.js +10 -0
  35. package/dist/services/rd/canonical-hash.d.ts +1 -0
  36. package/dist/services/rd/canonical-hash.js +38 -0
  37. package/dist/services/rd/impl.js +2 -8
  38. package/dist/services/rd/strategy.js +2 -8
  39. package/dist/services/rd/types.d.ts +10 -10
  40. package/dist/services/rd/types.js +21 -10
  41. package/package.json +10 -10
  42. package/skills/bee/peaks-rd/SKILL.md +57 -3
  43. package/skills/bee/peaks-rd/references/ocr-multilang-1.8.md +314 -111
@@ -1,13 +1,13 @@
1
1
  {
2
2
  "metadata": {
3
3
  "pluginRoot": ".",
4
- "version": "4.1.9"
4
+ "version": "4.1.11"
5
5
  },
6
6
  "plugins": [
7
7
  {
8
8
  "name": "peaks-loop",
9
9
  "description": "Loop Engineering CLI — workflow primitive / loop guards / evaluators / slice orchestration",
10
- "version": "4.1.9",
10
+ "version": "4.1.11",
11
11
  "author": {
12
12
  "name": "SquabbyZ"
13
13
  },
package/CHANGELOG.md CHANGED
@@ -1,5 +1,77 @@
1
1
  # Changelog
2
2
 
3
+ ## 4.1.11 — 2026-10-20(生产依赖升版、OCR 全语言路由,与 delegation 双阶段评审路径)
4
+
5
+ **版本级别**: 未发布区间 `v4.1.10..HEAD` 共 **3 个 commit**(**2 feat / 1 refactor**)。取 **patch**,依维护者 2026-07-22 的常设规则"默认版本新增采用最小的版本位"。`peaks code-review run-ocr-18` 新增 `--languages auto|<csv>` 与 `--delegate` 两条路径、新增 `peaks code-review ocr-delegate-record` 一个动词,均是在既有 service 之上的新入口;既有的 `--language <lang>` 单语言路径与 API 路径行为不变,无破坏性变更。
6
+
7
+ ### 1. 五个生产依赖升到各自大版本内最新(`194eccf5`)
8
+
9
+ - `@alibaba-group/open-code-review` `^1.8.9` → `^1.13.1`;`@upstash/context7-mcp` `^4.0.2` → `^4.4.4`;`picomatch` `4.0.4` → `4.0.7`(保留精确 pin);`yaml` `^2.9.0` → `^2.9.1`;`zod` `^4.4.3` → `^4.6.7`(根包与 `peaks-loop-mut` 同步)。
10
+ - `commander ^12.1.0`、`fzf ^0.5.2`、`@colbymchenry/codegraph 1.6.2` **经实测已是各自大版本内最新**,未改版本号——先量后改,而不是把所有条目都动一遍。
11
+ - `devDependencies` 全程未动,含被锁定的 `vitest 4.1.10`。锁文件里仍会解析出 `picomatch@4.0.4`,那是 vitest 自身钉死的传递依赖,不是漏升。
12
+
13
+ ### 2. OCR 桥的既有缺陷(`194eccf5`)
14
+
15
+ 升级过程中量出该桥**从未真正工作过**:它把 `--filter-language` 传给一个在 1.8.9 与 1.13.1 中都不存在的参数,并按 `findings[]` 解析一个真实信封里没有的字段(真实为 `comments[]`,字段是 `path` / `content` / `start_line` / `end_line` / `severity` / `category`)。测试一直是绿的,因为测试 mock 了子进程、喂的是适配器自己编造的 payload。
16
+
17
+ - `OCR_18_PACKAGE` 同步到 `1.13.1`——只改 `package.json` 不会改变运行时,npx 取的是这个常量。
18
+ - argv 去掉不存在的参数,保留 `--format json` 与 git 范围参数;解析改为读真实 `comments[]`,severity 映射扩展到 `critical/high/medium/low`。
19
+ - 语言路由改为**评审后按扩展名过滤**,并在代码里写明:评审仍覆盖整个 diff,被限定的是上报结果,而不是 LLM 被要求查看的范围。
20
+
21
+ ### 3. 全语言覆盖与自动识别(`e905f8eb`)
22
+
23
+ - 语言表**以上游自身的 `supported_file_types.json` 与 `rule_docs` 为准**内置,57 语言 / 97 扩展名;有漂移测试盯着内置副本与路由表,语言缺路由会直接红。
24
+ - `--languages auto` 从 git 范围识别语言,**一次 OCR 调用**产出按语言分组的 findings——Python+Go 的改动此前要跑两次同样的全量评审。范围里没有可路由语言时**完全不启动**(实测 128ms、零 spawn),而不是花一次调用去发现无事可做。
25
+ - 四种结果保持可区分:有发现 / 零发现 / 格式不受支持(`unsupportedFiles`)/ OCR 不可用(`state`);测试断言的是"干净但空"与"没跑成"**不相等**,不是两个不同的名字。
26
+ - `.mts` / `.cts` 不路由:上游 1.13.1 的白名单确实没有它们,`--preview` 报 `unsupported_ext`——已实测量并记录,不是遗漏。
27
+ - peaks-rd Gate B3 在 diff 命中任一语言时调用该步骤;TS/JS 双轨,ESLint 仍为主闸、OCR 为辅,每条 finding 标注来源工具。调用方传入的 ref 若以 `-` 开头在边界处即被拒,避免选项注入。
28
+
29
+ ### 4. Delegation 成为真正的评审路径(`7dc79de1`)
30
+
31
+ - 此前 `ocr-18-delegate-preview` 拿**评审解析器**去解析一个**文件清单**,从未产出过 finding。现在拆成两阶段:CLI 产出评审包(选中的文件与其 pattern、被排除的文件、按组解析后的规则文本、git 范围、成本面),宿主 agent 用自己的模型审,再由 `ocr-delegate-record` 校验并记录。
32
+ - **不需要任何 API key,不写 `~/.opencodereview`**。评审发生在会话本身的模型上。
33
+ - 记录下来的 finding 带 `attribution: ocr-delegate`,宿主模型的结论不会继承 OCR 的 benchmark 背书。
34
+ - **"没跑"与"干净"是两个文件而非两个名字**:包是 `state: awaiting-envelope` + `findings: null`,完成的评审是另一份带 `findings: []` 的文档;不存在任何一份文档能同时读成两者。
35
+ - 信封按不可信输入处理:逐字段类型校验,未知 severity 拒绝而非降级为 `info`,格式错误指名条目下标而非跳过;包路径限制在项目根内。
36
+ - 该路径在实现过程中被**真实跑通并用于审查自身**:出包 → 宿主模型按包内规则审 → 回录,抓到一个真实缺陷(`findings !== null` 的判断与自身报错语义相反),修复后重跑一致。
37
+
38
+ ### 5. 证据
39
+
40
+ - 全量 `pnpm test:unit`:**538 files / 5967 passed / 3 skipped**,exit 0(3 个 skip 为既有 `@slow` / `@replay` 标记)。
41
+ - 作用域运行:`tests/unit/services/lint/` + `tests/unit/cli/commands/` 58 files / 597 passed;树型层(`standards` + `lint` + 根)60 files / 616 passed。
42
+ - `tsc --noEmit`、`pnpm build`、`node .husky/peaks-gate.mjs repo` 全绿;构建后工作树保持干净(已提交的生成物与源码一致);`peaks changeset check` 通过;`no-ai-co-author-trailer` 7/7。
43
+ - 三个 slice 均 `verify-pipeline complete: true`、0 个失败 gate;security / perf 审计各自出件(delegation slice 两门均为 `pass`);karpathy 复核共 7 条发现全部关闭。
44
+ - 未执行且如实记录:OCR 自身的付费 `ocr review` 路径从未真正跑过——delegation 落地后它不再是必需路径。
45
+
46
+ ## 4.1.10 — 2026-10-20(STRAT→TACT→MUT 生产者链,canonical digest 递归修复)
47
+
48
+ **版本级别**: 未发布区间 `v4.1.9..HEAD` 共 **3 个 commit**(**1 feat / 1 fix / 1 docs**)。取 **patch**,依维护者 2026-07-22 的常设规则"默认版本新增采用最小的版本位"。CLI 新增 `peaks strat` / `peaks tact` 两个动词组,均为既有 service 的薄包装;无破坏性变更(canonical digest 的值变了,但只影响修复前产生的临时 artifact)。
49
+
50
+ ### 1. STRAT → TACT → MUT 生产者链(`45b378e9`,backlog §16 / §9.2)
51
+
52
+ - `peaks strat write`:写 strategy.md + `<out>.json`,生成 STRAT.sig。
53
+ - `peaks tact write`:校验 strategy JSON 的递归 sha256 与 markdown 的 `STRAT.sig:` 行,注册 STRAT.sig,跑 AST gate,写 impl.json(`inputSig` = STRAT.sig)。
54
+ - `peaks tact read`:重新校验 impl.json 并输出 `{ sha256, inputSig, changedFiles, astGateResult }`——文档里长期缺失的命令现在真实存在。
55
+ - 单轴写入守卫(`--session-id` 必填、`--out` 必须在 `.peaks/_runtime/<sid>/` 下)、`--changed-files` 项目内包含校验、AST 违规/篡改 artifact 的命名 refusal。
56
+ - 端到端测试:`strat write → tact write → tact read → mut`,`mut-report.json#inputSig` 等于 TACT.sig,并覆盖 passing-threshold 分支。
57
+
58
+ ### 2. Canonical digest 递归修复(`45b378e9`)
59
+
60
+ - 旧实现 `JSON.stringify(rest, Object.keys(rest).sort())` 是数组 replacer,会在每一层过滤 key,导致嵌套对象(`astGateResult` 等)被哈希成 `{}`;伪造嵌套 verdict 仍能通过验证。
61
+ - 现在逐层排序 key,verifier 对**解析前原始 JSON**求哈希,`StrategyOutput` / `ImplOutput` 及嵌套 schema 均为 `.strict()`。嵌套字段、数组项、未知字段的篡改全部拒绝。
62
+ - 注:digest 是 checksum 不是 MAC;同时改内容并重算签名的 artifact 仍会通过(H8 固有)。
63
+
64
+ ### 3. Backlog 与测试稳定性(`442c0e96`、`77a38b82`)
65
+
66
+ - §2.38 关闭:`peaks job add-slice` 已存在并追加 ledger。
67
+ - §9.50 关闭:AC-6 的 macOS gate 已在 CI 中通过。
68
+ - 全量 pre-push 暴露并修复:`tact read` 注册后的 invocation-check 夹具,以及 rule-D 对 `requireSessionAxis` 守卫的识别(补 `isUnsafePathInput`)。
69
+
70
+ ### 4. 证据
71
+
72
+ - 531 files / 5798 tests 在 pre-push 全量套件中通过;`tsc --noEmit`、`pnpm build`、repo/staged gate 全绿。
73
+ - code review(两轮,HIGH 已修)PASS-WITH-FINDINGS;Karpathy pass;security `warn`(1 LOW,词法单轴 symlink);perf `warn`(1 LOW,AST gate 双跑);QA PASS(AC1–AC9);`verify-pipeline complete: true`。
74
+
3
75
  ## 4.1.9 — 2026-10-19(Step 0.8 gate:remedy 豁免、provisional 决策与 exit code 可见性)
4
76
 
5
77
  **版本级别**: 未发布区间 `v4.1.8..HEAD` 共 **6 个 commit**(**2 fix / 1 style / 3 docs**)。取 **patch**,依维护者 2026-07-22 的常设规则"默认版本新增采用最小的版本位"。无破坏性 CLI 变更。
@@ -75,6 +75,7 @@ import { registerSliceReviewCommands } from './slice-review-commands.js';
75
75
  import { registerSmokeCommands } from './smoke-commands.js';
76
76
  import { registerSopCommands } from './sop-commands.js';
77
77
  import { registerStatusLineCommands } from './statusline-commands.js';
78
+ import { registerStratTactCommands } from './strat-tact-commands.js';
78
79
  import { registerSpillDemoCommand } from './spill-demo-command.js';
79
80
  import { registerSubAgentCommands } from './sub-agent-commands.js';
80
81
  import { registerSubAgentShutdownCommands } from './sub-agent-shutdown-commands.js';
@@ -174,6 +175,7 @@ const REGISTRATIONS = [
174
175
  ['dashboard-commands', registerDashboardCommands],
175
176
  ['best-practice-scan-command', registerBestPracticeScanCommand],
176
177
  ['mut-commands', registerMutCommands],
178
+ ['strat-tact-commands', registerStratTactCommands],
177
179
  ['fixture-commands', registerFixtureCommands],
178
180
  ['reviewer-commands', registerReviewerCommands],
179
181
  ['ide-commands', registerIdeCommands],
@@ -1,5 +1,5 @@
1
1
  /**
2
- * peaks code-review * CLI surface — ECC bridge + OCR 1.8.x.
2
+ * peaks code-review * CLI surface — ECC bridge + OCR 1.x.
3
3
  */
4
4
  import type { Command } from 'commander';
5
5
  import { type ProgramIO } from '../cli-helpers.js';
@@ -2,22 +2,25 @@ import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
2
2
  import { fail, ok } from 'peaks-loop-shared/result';
3
3
  import { detectOcr18 } from '../../services/lint/detect-ocr-18.js';
4
4
  import { acquireOcr18 } from '../../services/lint/ocr-18-acquire.js';
5
- import { OCR_18_LANGUAGES, OCR_18_PACKAGE, runOcr18 } from '../../services/lint/ocr-multilang-adapter.js';
6
- const SUPPORTED_LANGUAGES_SET = new Set(OCR_18_LANGUAGES);
5
+ import { OCR_18_PACKAGE } from '../../services/lint/ocr-multilang-adapter.js';
6
+ import { runDelegatePreview } from '../../services/lint/ocr-18-delegate-payload.js';
7
+ import { registerRunOcr18Command } from './code-review-run-ocr-18.js';
8
+ import { registerOcrDelegateRecordCommand } from './code-review-ocr-delegate-record.js';
7
9
  /** What a caller can do when the acquisition did not land the package. */
8
10
  const ACQUIRE_RETRY_ACTION = 'Re-run `peaks code-review acquire-ocr-18` once the network is available.';
9
11
  export function registerCodeReviewCommands(program, io) {
10
12
  const codeReview = program
11
13
  .command('code-review', { hidden: true })
12
- .description('Code-review primitives for peaks-rd Gate B3. ECC bridge (JS/TS) + OCR 1.8.x multi-language.');
14
+ .description('Code-review primitives for peaks-rd Gate B3. ECC bridge (JS/TS) + OCR 1.x multi-language.');
15
+ registerRunOcr18Command(codeReview, io);
13
16
  addJsonOption(codeReview
14
17
  .command('detect-ocr-18')
15
- .description('Read-only probe: returns the 5-state OCR 1.8.x runtime envelope (ready / ocr18-missing / binary-missing / llm-config-missing / detection-failed).')).action((options) => {
18
+ .description('Read-only probe: returns the 5-state OCR 1.x runtime envelope (ready / ocr18-missing / binary-missing / llm-config-missing / detection-failed).')).action((options) => {
16
19
  try {
17
20
  const result = detectOcr18();
18
21
  const envelope = result.state === 'ready'
19
22
  ? ok('code-review.detect-ocr-18', result, [...result.warnings], [...result.nextActions])
20
- : fail('code-review.detect-ocr-18', result.state.toUpperCase().replace(/-/g, '_'), `ocr 1.8.x is not ready: ${result.state}`, result, [...result.nextActions]);
23
+ : fail('code-review.detect-ocr-18', result.state.toUpperCase().replace(/-/g, '_'), `ocr 1.x is not ready: ${result.state}`, result, [...result.nextActions]);
21
24
  printResult(io, envelope, options.json);
22
25
  if (result.state !== 'ready')
23
26
  process.exitCode = 0; // soft-fail
@@ -28,7 +31,7 @@ export function registerCodeReviewCommands(program, io) {
28
31
  });
29
32
  addJsonOption(codeReview
30
33
  .command('acquire-ocr-18')
31
- .description('Acquire the OCR 1.8.x reviewer: runs the pinned npx package VISIBLY (npm progress on the ' +
34
+ .description('Acquire the OCR 1.x reviewer: runs the pinned npx package VISIBLY (npm progress on the ' +
32
35
  'terminal) and installs it once when it is not already cached. The companion to the read-only ' +
33
36
  '`detect-ocr-18` probe, which never installs.')).action(async (options) => {
34
37
  const command = 'code-review.acquire-ocr-18';
@@ -81,38 +84,21 @@ export function registerCodeReviewCommands(program, io) {
81
84
  }
82
85
  });
83
86
  addJsonOption(codeReview
84
- .command('run-ocr-18')
85
- .description('Invoke `ocr review --filter-language <lang>` (or `ocr delegate preview` when --delegate) for one of 8 supported languages.')
86
- .option('--language <lang>', `target language: ${OCR_18_LANGUAGES.join(' | ')}`)
87
- .option('--from <ref>', 'git ref to diff from (e.g. main)')
88
- .option('--to <ref>', 'git ref to diff to (e.g. HEAD)')
89
- .option('--commit <sha>', 'specific commit SHA to review')
90
- .option('--delegate', 'use Delegation Mode (no LLM key required)')).action((options) => {
91
- const language = options.language;
92
- if (language === undefined || !SUPPORTED_LANGUAGES_SET.has(language)) {
93
- printResult(io, fail('code-review.run-ocr-18', 'LANGUAGE_UNSUPPORTED', `unsupported language: ${language ?? '<missing>'}`, { state: 'language-unsupported', supported: OCR_18_LANGUAGES }, [`Pick one of: ${OCR_18_LANGUAGES.join(', ')}`]), options.json);
87
+ .command('ocr-18-delegate-preview')
88
+ .description('Print the file selection `ocr delegate preview` returns (no LLM key required). A ' +
89
+ 'SELECTION preview, not a review: use `run-ocr-18 --delegate --rid <rid>` for the ' +
90
+ 'packet the host agent reviews, then `ocr-delegate-record`.')).action((options) => {
91
+ // No language: `ocr delegate preview` takes none, and the language used to
92
+ // be passed here as a value delegate mode discarded.
93
+ const result = runDelegatePreview(process.cwd());
94
+ if (!result.ok) {
95
+ printResult(io, fail('code-review.ocr-18-delegate-preview', result.state.toUpperCase().replace(/-/g, '_'), `ocr 1.x state: ${result.state}`, { state: result.state, rawOutput: result.rawOutput }, ['Re-run `peaks code-review detect-ocr-18 --json` to refresh.']), options.json);
94
96
  return;
95
97
  }
96
- const result = runOcr18({
97
- cwd: process.cwd(),
98
- language: language,
99
- ...(options.from !== undefined ? { from: options.from } : {}),
100
- ...(options.to !== undefined ? { to: options.to } : {}),
101
- ...(options.commit !== undefined ? { commit: options.commit } : {}),
102
- ...(options.delegate === true ? { delegate: true } : {})
103
- });
104
- const envelope = result.state === 'ok'
105
- ? ok('code-review.run-ocr-18', result, [], [])
106
- : fail('code-review.run-ocr-18', result.state.toUpperCase().replace(/-/g, '_'), `ocr 1.8.x state: ${result.state}`, result, ['Re-run `peaks code-review detect-ocr-18 --json` to refresh.']);
107
- printResult(io, envelope, options.json);
108
- });
109
- addJsonOption(codeReview
110
- .command('ocr-18-delegate-preview')
111
- .description('Print the Delegation Mode spec for the host agent (no LLM key required).')).action((options) => {
112
- const result = runOcr18({ cwd: process.cwd(), language: 'python', delegate: true });
113
- const envelope = result.state === 'ok'
114
- ? ok('code-review.ocr-18-delegate-preview', result, [], [])
115
- : fail('code-review.ocr-18-delegate-preview', result.state.toUpperCase().replace(/-/g, '_'), `ocr 1.8.x state: ${result.state}`, result, ['Re-run `peaks code-review detect-ocr-18 --json` to refresh.']);
116
- printResult(io, envelope, options.json);
98
+ printResult(io, ok('code-review.ocr-18-delegate-preview', result.preview, [], [
99
+ 'This is a selection preview — no review ran.',
100
+ 'For a review: `peaks code-review run-ocr-18 --delegate --rid <rid> --json`, then record the findings.'
101
+ ]), options.json);
117
102
  });
103
+ registerOcrDelegateRecordCommand(codeReview, io);
118
104
  }
@@ -0,0 +1,3 @@
1
+ import type { Command } from 'commander';
2
+ import { type ProgramIO } from '../cli-helpers.js';
3
+ export declare function registerOcrDelegateRecordCommand(codeReview: Command, io: ProgramIO): void;
@@ -0,0 +1,73 @@
1
+ /**
2
+ * `peaks code-review ocr-delegate-record` — phase 2 of the no-credential path.
3
+ *
4
+ * Takes the host agent's findings envelope, validates it against the packet it
5
+ * names, and records the findings with `ocr-delegate` attribution. No LLM call
6
+ * and no provider key: the review already happened in the agent's own model.
7
+ *
8
+ * Split from the phase-1 verb along the same seam as the services: this file
9
+ * never spawns OCR and never resolves a session.
10
+ */
11
+ import { readFileSync } from 'node:fs';
12
+ import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
13
+ import { fail, ok } from 'peaks-loop-shared/result';
14
+ import { recordDelegateFindings } from '../../services/lint/ocr-18-delegate-record.js';
15
+ const COMMAND = 'code-review.ocr-delegate-record';
16
+ function isRefusal(value) {
17
+ return 'code' in value;
18
+ }
19
+ function readEnvelope(envelopePath) {
20
+ try {
21
+ return { ok: true, text: readFileSync(envelopePath, 'utf8') };
22
+ }
23
+ catch (error) {
24
+ return {
25
+ code: 'ENVELOPE_INVALID',
26
+ message: `--envelope must be a path to a readable JSON file: ${envelopePath} (${getErrorMessage(error)})`
27
+ };
28
+ }
29
+ }
30
+ function printRecorded(io, options, result) {
31
+ printResult(io, ok(COMMAND, {
32
+ state: result.document.state,
33
+ attribution: result.document.attribution,
34
+ packet: result.document.packet,
35
+ findingsPath: result.findingsPath,
36
+ findings: result.document.findings,
37
+ summary: result.document.summary
38
+ }, result.replaced ? ['An earlier findings file for this packet was replaced.'] : [], [`Cite ${result.findingsPath} in the RD code-review artifact.`]), options.json);
39
+ }
40
+ function recordAction(io, options) {
41
+ const envelope = readEnvelope(options.envelope);
42
+ if (isRefusal(envelope)) {
43
+ printResult(io, fail(COMMAND, envelope.code, envelope.message, { state: 'record-refused' }, [
44
+ 'Write the findings envelope first, then re-run this verb.'
45
+ ]), options.json);
46
+ process.exitCode = 1;
47
+ return;
48
+ }
49
+ const result = recordDelegateFindings({
50
+ projectRoot: options.project ?? process.cwd(),
51
+ packetPath: options.packet,
52
+ envelopeText: envelope.text
53
+ });
54
+ if (!result.ok) {
55
+ printResult(io, fail(COMMAND, result.code, result.message, { state: 'record-refused' }, [
56
+ 'Nothing was recorded — this is not a clean review.'
57
+ ]), options.json);
58
+ process.exitCode = 1;
59
+ return;
60
+ }
61
+ printRecorded(io, options, result);
62
+ }
63
+ export function registerOcrDelegateRecordCommand(codeReview, io) {
64
+ addJsonOption(codeReview
65
+ .command('ocr-delegate-record')
66
+ .description('Validate a host-agent findings envelope against its delegation packet and record it ' +
67
+ 'with `ocr-delegate` attribution. No LLM call and no provider key.')
68
+ .requiredOption('--packet <path>', 'the packet written by `run-ocr-18 --delegate --rid <rid>`')
69
+ .requiredOption('--envelope <path>', 'path to the JSON findings envelope file authored by the host agent')
70
+ .option('--project <path>', 'target project root (defaults to cwd)')).action((options) => {
71
+ recordAction(io, options);
72
+ });
73
+ }
@@ -0,0 +1,12 @@
1
+ import { type ProgramIO } from '../cli-helpers.js';
2
+ export type DelegateRunOptions = {
3
+ rid?: string;
4
+ sessionId?: string;
5
+ language?: string;
6
+ languages?: string;
7
+ from?: string;
8
+ to?: string;
9
+ commit?: string;
10
+ json?: boolean;
11
+ };
12
+ export declare function runDelegatePacket(io: ProgramIO, options: DelegateRunOptions): void;
@@ -0,0 +1,140 @@
1
+ /**
2
+ * `peaks code-review` delegation verbs — the two-phase, no-credential review path.
3
+ *
4
+ * Phase 1 (`run-ocr-18 --delegate`) writes a packet: OCR's deterministic file
5
+ * selection, the pattern that selected each file, the resolved rules, the range
6
+ * and the cost. Phase 2 (`ocr-delegate-record`) validates the host agent's
7
+ * findings envelope and records it with `ocr-delegate` attribution.
8
+ *
9
+ * Neither phase calls an LLM and neither reads a provider key: the agent that
10
+ * holds the tools reviews with the model it is already running on.
11
+ */
12
+ import { join } from 'node:path';
13
+ import { getErrorMessage, printResult } from '../cli-helpers.js';
14
+ import { fail, ok } from 'peaks-loop-shared/result';
15
+ import { collectDelegatePacket, isDelegateRid, writeDelegatePacket } from '../../services/lint/ocr-18-delegate-packet.js';
16
+ import { getSessionDir } from '../../services/session/getSessionDir.js';
17
+ import { getCurrentSessionId } from '../../services/skills/skill-presence-service.js';
18
+ const RUN_COMMAND = 'code-review.run-ocr-18';
19
+ /** Reported by both phases, so a caller never has to guess the field name. */
20
+ const NOT_A_CLEAN_REVIEW = 'Nothing was reviewed — this is not a clean review.';
21
+ const NOT_LANGUAGE_SCOPED = '`--delegate` is not language-scoped — `ocr delegate preview` takes no language.';
22
+ function refused(target) {
23
+ return 'code' in target;
24
+ }
25
+ function refuse(io, options, code, message) {
26
+ printResult(io, fail(RUN_COMMAND, code, message, { state: 'packet-refused' }, [NOT_A_CLEAN_REVIEW]), options.json);
27
+ }
28
+ function resolveSession(options, projectRoot) {
29
+ const sessionId = options.sessionId ?? process.env['PEAKS_SESSION_ID'] ?? getCurrentSessionId(projectRoot);
30
+ return sessionId === null || sessionId === undefined || sessionId.length === 0 ? null : sessionId;
31
+ }
32
+ /** Everything `--delegate` cannot express is refused here, before anything is spawned. */
33
+ function delegateTarget(options, projectRoot) {
34
+ if (options.languages !== undefined && options.languages.trim().toLowerCase() !== 'auto') {
35
+ return {
36
+ code: 'LANGUAGE_FLAGS_CONFLICT',
37
+ message: `${NOT_LANGUAGE_SCOPED} Use \`--languages auto\`.`
38
+ };
39
+ }
40
+ if (options.language !== undefined) {
41
+ return { code: 'LANGUAGE_FLAGS_CONFLICT', message: NOT_LANGUAGE_SCOPED };
42
+ }
43
+ const rid = options.rid?.trim();
44
+ if (rid === undefined || rid.length === 0) {
45
+ return {
46
+ code: 'RID_REQUIRED',
47
+ message: '`--delegate` writes a durable packet named after the request; pass `--rid <rid>`.'
48
+ };
49
+ }
50
+ // The rid names a file, so it is validated before it is ever joined into a path.
51
+ if (!isDelegateRid(rid)) {
52
+ return {
53
+ code: 'INVALID_RID',
54
+ message: `\`--rid\` must be a single path segment: ${rid}`
55
+ };
56
+ }
57
+ const sessionId = resolveSession(options, projectRoot);
58
+ if (sessionId === null) {
59
+ return {
60
+ code: 'NO_ACTIVE_SESSION',
61
+ message: 'No session is bound: pass `--session-id <sid>` or set PEAKS_SESSION_ID.'
62
+ };
63
+ }
64
+ return { rid, sessionId };
65
+ }
66
+ function rangeOf(options) {
67
+ return {
68
+ ...(options.from !== undefined ? { from: options.from } : {}),
69
+ ...(options.to !== undefined ? { to: options.to } : {}),
70
+ ...(options.commit !== undefined ? { commit: options.commit } : {})
71
+ };
72
+ }
73
+ function printUnavailable(io, options, failure, data) {
74
+ printResult(io, fail(RUN_COMMAND, failure.state.toUpperCase().replace(/-/g, '_'), `ocr 1.x state: ${failure.state}`, data, ['Re-run `peaks code-review detect-ocr-18 --json` to refresh.', NOT_A_CLEAN_REVIEW]), options.json);
75
+ }
76
+ function printCollected(io, options, collected, packetPath) {
77
+ const data = { ...collected.packet, packetPath };
78
+ if (collected.failure !== null) {
79
+ printUnavailable(io, options, collected.failure, data);
80
+ return;
81
+ }
82
+ if (collected.packet.state !== 'awaiting-envelope') {
83
+ printResult(io, ok(RUN_COMMAND, data, [
84
+ `Delegation packet state: ${collected.packet.state} — nothing was handed to the host agent.`,
85
+ NOT_A_CLEAN_REVIEW
86
+ ], []), options.json);
87
+ return;
88
+ }
89
+ printResult(io, ok(RUN_COMMAND, data, [...collected.packet.warnings], [
90
+ 'Review the selected files against the resolved rules, then record the findings:',
91
+ `peaks code-review ocr-delegate-record --packet ${packetPath} --envelope <path to the findings envelope file> --json`
92
+ ]), options.json);
93
+ }
94
+ function collectOrReport(io, options, target, projectRoot) {
95
+ try {
96
+ return collectDelegatePacket({
97
+ cwd: projectRoot,
98
+ rid: target.rid,
99
+ session: target.sessionId,
100
+ range: rangeOf(options)
101
+ });
102
+ }
103
+ catch (error) {
104
+ printResult(io, fail(RUN_COMMAND, 'OCR18_DETECT_FAILED', getErrorMessage(error), { state: 'detection-failed' }, ['The git range could not be read, so nothing was reviewed.', NOT_A_CLEAN_REVIEW]), options.json);
105
+ return null;
106
+ }
107
+ }
108
+ function writeOrReport(io, options, packetPath, collected) {
109
+ try {
110
+ writeDelegatePacket(packetPath, collected.packet);
111
+ return true;
112
+ }
113
+ catch (error) {
114
+ printResult(io, fail(RUN_COMMAND, 'OCR18_PACKET_WRITE_FAILED', getErrorMessage(error), { state: 'packet-write-failed', packetPath }, ['Check that the session directory is writable.', NOT_A_CLEAN_REVIEW]), options.json);
115
+ process.exitCode = 1;
116
+ return false;
117
+ }
118
+ }
119
+ export function runDelegatePacket(io, options) {
120
+ const projectRoot = process.cwd();
121
+ const target = delegateTarget(options, projectRoot);
122
+ if (refused(target)) {
123
+ refuse(io, options, target.code, target.message);
124
+ return;
125
+ }
126
+ let packetPath;
127
+ try {
128
+ packetPath = join(getSessionDir(projectRoot, target.sessionId), 'rd', 'ocr-delegate', `${target.rid}-packet.json`);
129
+ }
130
+ catch (error) {
131
+ refuse(io, options, 'INVALID_SESSION_ID', getErrorMessage(error));
132
+ return;
133
+ }
134
+ const collected = collectOrReport(io, options, target, projectRoot);
135
+ if (collected === null)
136
+ return;
137
+ if (!writeOrReport(io, options, packetPath, collected))
138
+ return;
139
+ printCollected(io, options, collected, packetPath);
140
+ }
@@ -0,0 +1,11 @@
1
+ /**
2
+ * `peaks code-review run-ocr-18` — the single-language and multi-language entry
3
+ * point into the OCR 1.x bridge.
4
+ *
5
+ * Split out of `code-review-commands.ts` along the file-size policy's 300-line
6
+ * cap, and along a real seam: this file owns flag precedence and envelope
7
+ * shape, the adapter owns argv and spawning.
8
+ */
9
+ import type { Command } from 'commander';
10
+ import { type ProgramIO } from '../cli-helpers.js';
11
+ export declare function registerRunOcr18Command(codeReview: Command, io: ProgramIO): void;
@@ -0,0 +1,127 @@
1
+ import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
2
+ import { fail, ok } from 'peaks-loop-shared/result';
3
+ import { detectOcr18 } from '../../services/lint/detect-ocr-18.js';
4
+ import { runOcr18 } from '../../services/lint/ocr-multilang-adapter.js';
5
+ import { runOcr18Multi } from '../../services/lint/ocr-18-multi.js';
6
+ import { OCR_18_LANGUAGES, parseLanguageSelection } from '../../services/lint/ocr-18-language-routing.js';
7
+ import { runDelegatePacket } from './code-review-ocr-delegate.js';
8
+ const COMMAND = 'code-review.run-ocr-18';
9
+ const SUPPORTED_LANGUAGES_SET = new Set(OCR_18_LANGUAGES);
10
+ const ROUTED_LANGUAGES = OCR_18_LANGUAGES.join(', ');
11
+ /** The refusal both language flags must produce: it says which one to keep. */
12
+ const BOTH_LANGUAGE_FLAGS = 'Pass `--language <lang>` for a single language, or `--languages auto|<csv>` for many — not both.';
13
+ /** The git range the review covers; an empty object means "the workspace". */
14
+ function rangeOf(options) {
15
+ return {
16
+ ...(options.from !== undefined ? { from: options.from } : {}),
17
+ ...(options.to !== undefined ? { to: options.to } : {}),
18
+ ...(options.commit !== undefined ? { commit: options.commit } : {})
19
+ };
20
+ }
21
+ function printLanguageRefusal(io, options, message) {
22
+ printResult(io, fail(COMMAND, 'LANGUAGE_FLAGS_CONFLICT', message, { state: 'language-unsupported' }, [message]), options.json);
23
+ }
24
+ function runSingle(io, options) {
25
+ const language = options.language;
26
+ if (language === undefined || !SUPPORTED_LANGUAGES_SET.has(language)) {
27
+ printResult(io, fail(COMMAND, 'LANGUAGE_UNSUPPORTED', `unsupported language: ${language ?? '<missing>'}`, { state: 'language-unsupported', supported: OCR_18_LANGUAGES }, [`Pick one of: ${ROUTED_LANGUAGES}`, 'Or use `--languages auto` to detect from the range.']), options.json);
28
+ return;
29
+ }
30
+ const result = runOcr18({
31
+ cwd: process.cwd(),
32
+ language,
33
+ ...rangeOf(options)
34
+ });
35
+ const envelope = result.state === 'ok'
36
+ ? ok(COMMAND, result, [], [])
37
+ : fail(COMMAND, result.state.toUpperCase().replace(/-/g, '_'), `ocr 1.x state: ${result.state}`, result, ['Re-run `peaks code-review detect-ocr-18 --json` to refresh.']);
38
+ printResult(io, envelope, options.json);
39
+ }
40
+ /** Parse the selector, or print the refusal and return null. */
41
+ function selectionFor(io, options, selector) {
42
+ try {
43
+ return parseLanguageSelection(selector);
44
+ }
45
+ catch (error) {
46
+ printResult(io, fail(COMMAND, 'LANGUAGE_UNSUPPORTED', getErrorMessage(error), { state: 'language-unsupported', supported: OCR_18_LANGUAGES }, [`Pick "auto", or one of: ${ROUTED_LANGUAGES}`]), options.json);
47
+ return null;
48
+ }
49
+ }
50
+ /** Run the one review, or print the detection failure and return null. */
51
+ function multiFor(io, options, selection) {
52
+ try {
53
+ return runOcr18Multi({
54
+ cwd: process.cwd(),
55
+ ...(selection.languages !== null ? { languages: selection.languages } : {}),
56
+ ...rangeOf(options)
57
+ });
58
+ }
59
+ catch (error) {
60
+ printResult(io, fail(COMMAND, 'OCR18_DETECT_FAILED', getErrorMessage(error), { state: 'detection-failed' }, [
61
+ 'The git range could not be read, so nothing was reviewed.'
62
+ ]), options.json);
63
+ return null;
64
+ }
65
+ }
66
+ function printMultiResult(io, options, result) {
67
+ if (result.state === 'ok') {
68
+ printResult(io, ok(COMMAND, result, [], []), options.json);
69
+ return;
70
+ }
71
+ if (result.state === 'no-routed-language') {
72
+ // An ok envelope, and an explicit one: nothing was reviewed, which is not
73
+ // the same thing as a clean review.
74
+ printResult(io, ok(COMMAND, result, [
75
+ `No routed language in the range: ${result.changedFileCount} file(s) changed, ` +
76
+ `${result.unsupportedFiles.length} not reviewable as a routed language.`,
77
+ 'Nothing was reviewed — this is not a clean review.'
78
+ ], []), options.json);
79
+ return;
80
+ }
81
+ // Unavailable: carry the detector's own state so `binary-missing` and
82
+ // `llm-config-missing` are not collapsed into one shape.
83
+ const detector = detectOcr18();
84
+ printResult(io, fail(COMMAND, result.state.toUpperCase().replace(/-/g, '_'), `ocr 1.x state: ${result.state}`, {
85
+ ...result,
86
+ detector: {
87
+ state: detector.state,
88
+ package: detector.package,
89
+ warnings: detector.warnings
90
+ }
91
+ }, [...detector.nextActions, 'Nothing was reviewed — this is not a clean review.']), options.json);
92
+ }
93
+ function runMulti(io, selector, options) {
94
+ const selection = selectionFor(io, options, selector);
95
+ if (selection === null)
96
+ return;
97
+ const result = multiFor(io, options, selection);
98
+ if (result !== null)
99
+ printMultiResult(io, options, result);
100
+ }
101
+ export function registerRunOcr18Command(codeReview, io) {
102
+ addJsonOption(codeReview
103
+ .command('run-ocr-18')
104
+ .description('Invoke `ocr review` once over the requested git range (or, with --delegate, write a delegation packet the host agent reviews without a key); findings are attributed to a language by file extension after the review.')
105
+ .option('--language <lang>', 'single target language, e.g. python | go | typescript | java')
106
+ .option('--languages <selector>', 'auto (detect from the range) or a comma-separated list, e.g. ts,js,go')
107
+ .option('--from <ref>', 'git ref to diff from (e.g. main)')
108
+ .option('--to <ref>', 'git ref to diff to (e.g. HEAD)')
109
+ .option('--commit <sha>', 'specific commit SHA to review')
110
+ .option('--delegate', 'write a delegation packet for the host agent (no LLM key required)')
111
+ .option('--rid <rid>', 'request id; names the delegation packet (required with --delegate)')
112
+ .option('--session-id <sid>', 'session id for the packet path (default: the bound session)')).action((options) => {
113
+ if (options.language !== undefined && options.languages !== undefined) {
114
+ printLanguageRefusal(io, options, BOTH_LANGUAGE_FLAGS);
115
+ return;
116
+ }
117
+ if (options.delegate === true) {
118
+ runDelegatePacket(io, options);
119
+ return;
120
+ }
121
+ if (options.languages !== undefined) {
122
+ runMulti(io, options.languages, options);
123
+ return;
124
+ }
125
+ runSingle(io, options);
126
+ });
127
+ }
@@ -0,0 +1,16 @@
1
+ import type { ProgramIO } from '../cli-helpers.js';
2
+ import { type AstGateContext } from '../../services/rd/ast-gate.js';
3
+ import { type ImplOutput, type StrategyOutput } from '../../services/rd/types.js';
4
+ export declare class CommandRefusal extends Error {
5
+ readonly code: string;
6
+ readonly remedy: string;
7
+ constructor(code: string, remedy: string, message: string);
8
+ }
9
+ export declare function emitOk(io: ProgramIO, json: boolean, payload: Record<string, unknown>, human: string[]): void;
10
+ /** Run an action body, turning a named refusal into the CLI's error surface. */
11
+ export declare function guarded(io: ProgramIO, json: boolean, command: string, body: () => Promise<void>): Promise<void>;
12
+ /** Resolve `--out` and enforce the one-axis layout. */
13
+ export declare function requireSessionAxis(project: string, sessionId: string, out: string): string;
14
+ export declare function readStrategy(path: string): Promise<StrategyOutput>;
15
+ export declare function readImpl(path: string): Promise<ImplOutput>;
16
+ export declare function parseAstContext(raw: string | undefined): AstGateContext;