peaks-loop 4.1.11 → 4.1.13

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 (80) hide show
  1. package/.claude-plugin/marketplace.json +2 -2
  2. package/CHANGELOG.md +88 -0
  3. package/README-en.md +1 -1
  4. package/README.md +1 -1
  5. package/dist/cli/commands/_register.js +2 -0
  6. package/dist/cli/commands/batch-commands.d.ts +6 -0
  7. package/dist/cli/commands/batch-commands.js +70 -0
  8. package/dist/cli/commands/batch-diagnose-command.d.ts +10 -0
  9. package/dist/cli/commands/batch-diagnose-command.js +196 -0
  10. package/dist/cli/commands/batch-diagnose-envelope.d.ts +25 -0
  11. package/dist/cli/commands/batch-diagnose-envelope.js +60 -0
  12. package/dist/cli/commands/batch-diagnose-record.d.ts +21 -0
  13. package/dist/cli/commands/batch-diagnose-record.js +51 -0
  14. package/dist/cli/commands/batch-item-input.d.ts +59 -0
  15. package/dist/cli/commands/batch-item-input.js +113 -0
  16. package/dist/cli/commands/batch-report-command.d.ts +22 -0
  17. package/dist/cli/commands/batch-report-command.js +199 -0
  18. package/dist/cli/commands/core/skill-context-verdict.d.ts +16 -1
  19. package/dist/cli/commands/core/skill-context-verdict.js +38 -8
  20. package/dist/cli/commands/lint-commands.js +8 -0
  21. package/dist/cli/commands/lint-rules-command.d.ts +14 -0
  22. package/dist/cli/commands/lint-rules-command.js +44 -0
  23. package/dist/services/batch/batch-active-batch.d.ts +55 -0
  24. package/dist/services/batch/batch-active-batch.js +127 -0
  25. package/dist/services/batch/batch-context-reminder.d.ts +85 -0
  26. package/dist/services/batch/batch-context-reminder.js +201 -0
  27. package/dist/services/batch/batch-diagnosis-finding.d.ts +25 -0
  28. package/dist/services/batch/batch-diagnosis-finding.js +227 -0
  29. package/dist/services/batch/batch-diagnosis-report-store.d.ts +49 -0
  30. package/dist/services/batch/batch-diagnosis-report-store.js +133 -0
  31. package/dist/services/batch/batch-diagnosis-summary.d.ts +31 -0
  32. package/dist/services/batch/batch-diagnosis-summary.js +129 -0
  33. package/dist/services/batch/batch-diagnosis.d.ts +36 -0
  34. package/dist/services/batch/batch-diagnosis.js +107 -0
  35. package/dist/services/batch/batch-entry.d.ts +22 -0
  36. package/dist/services/batch/batch-entry.js +42 -0
  37. package/dist/services/batch/batch-fix-agent.d.ts +39 -0
  38. package/dist/services/batch/batch-fix-agent.js +126 -0
  39. package/dist/services/batch/batch-fix-types.d.ts +85 -0
  40. package/dist/services/batch/batch-fix-types.js +11 -0
  41. package/dist/services/batch/batch-fix.d.ts +15 -0
  42. package/dist/services/batch/batch-fix.js +229 -0
  43. package/dist/services/batch/batch-phase-advance.d.ts +45 -0
  44. package/dist/services/batch/batch-phase-advance.js +105 -0
  45. package/dist/services/batch/batch-progress-store.d.ts +52 -0
  46. package/dist/services/batch/batch-progress-store.js +219 -0
  47. package/dist/services/batch/batch-progress-types.d.ts +79 -0
  48. package/dist/services/batch/batch-progress-types.js +10 -0
  49. package/dist/services/batch/batch-recovery.d.ts +5 -0
  50. package/dist/services/batch/batch-recovery.js +24 -0
  51. package/dist/services/batch/batch-verify.d.ts +93 -0
  52. package/dist/services/batch/batch-verify.js +216 -0
  53. package/dist/services/code/auto-compact-decision.d.ts +17 -0
  54. package/dist/services/code/auto-compact-decision.js +6 -0
  55. package/dist/services/code/auto-compact-orchestrator.js +6 -0
  56. package/dist/services/code/batch-compaction-point.d.ts +45 -0
  57. package/dist/services/code/batch-compaction-point.js +99 -0
  58. package/dist/services/code/orchestrator-can-do-probes.d.ts +10 -0
  59. package/dist/services/code/orchestrator-can-do-probes.js +12 -2
  60. package/dist/services/context/context-schema.d.ts +1 -1
  61. package/dist/services/lint/curated-rule-reader.d.ts +37 -0
  62. package/dist/services/lint/curated-rule-reader.js +179 -0
  63. package/dist/services/lint/project-lint-declarations.d.ts +27 -0
  64. package/dist/services/lint/project-lint-declarations.js +217 -0
  65. package/dist/services/lint/project-lint-tool-detection.d.ts +14 -0
  66. package/dist/services/lint/project-lint-tool-detection.js +208 -0
  67. package/dist/services/lint/project-lint-tool-rules.d.ts +19 -0
  68. package/dist/services/lint/project-lint-tool-rules.js +199 -0
  69. package/dist/services/lint/rule-pre-read-types.d.ts +66 -0
  70. package/dist/services/lint/rule-pre-read-types.js +22 -0
  71. package/dist/services/lint/rule-pre-read.d.ts +20 -0
  72. package/dist/services/lint/rule-pre-read.js +145 -0
  73. package/dist/services/scan/archetype-service.js +24 -8
  74. package/dist/services/scan/frontend-evidence.d.ts +19 -0
  75. package/dist/services/scan/frontend-evidence.js +142 -0
  76. package/dist/services/scan/scan-types.d.ts +8 -1
  77. package/dist/services/skill/skill-search-service.d.ts +3 -3
  78. package/package.json +5 -5
  79. package/skills/peaks-code/references/micro-cycle.md +13 -1
  80. package/skills/peaks-race-code/SKILL.md +40 -1
@@ -0,0 +1,49 @@
1
+ /** Which report: the batch, the item, and where the session lives. */
2
+ export interface BatchDiagnosisReportRef {
3
+ readonly projectRoot: string;
4
+ readonly sessionId: string;
5
+ readonly batchId: string;
6
+ readonly itemId: string;
7
+ }
8
+ /**
9
+ * The directory one batch's diagnosis reports live in.
10
+ *
11
+ * @param projectRoot - Absolute path to the project root.
12
+ * @param sessionId - The session the batch belongs to.
13
+ * @param batchId - The batch's id.
14
+ */
15
+ export declare function batchDiagnosisReportDir(projectRoot: string, sessionId: string, batchId: string): string;
16
+ /**
17
+ * The report path for one item of one batch.
18
+ *
19
+ * @param ref - Which report: the project, the session, the batch, the item.
20
+ */
21
+ export declare function batchDiagnosisReportPath(ref: BatchDiagnosisReportRef): string;
22
+ /**
23
+ * Write one item's diagnosis report, atomically.
24
+ *
25
+ * The report is stored verbatim: it is the diagnostician's own words, and
26
+ * the summary is derived from it rather than replacing it.
27
+ *
28
+ * @param ref - Which report: the project, the session, the batch, the item.
29
+ * @param report - The report text, verbatim.
30
+ */
31
+ export declare function writeBatchDiagnosisReport(ref: BatchDiagnosisReportRef, report: string): void;
32
+ /**
33
+ * Read one item's diagnosis report.
34
+ *
35
+ * @returns The report text, or `null` when the item has no report yet.
36
+ */
37
+ export declare function readBatchDiagnosisReport(ref: BatchDiagnosisReportRef): string | null;
38
+ /**
39
+ * Read one item's diagnosis report AS THE SUMMARY the window may hold.
40
+ *
41
+ * The summary is derived from the stored report every time it is asked
42
+ * for, so the two can never drift apart: there is no second copy of the
43
+ * file set to fall out of date.
44
+ *
45
+ * @returns The summary, or `null` when there is no report, or when the
46
+ * report carries none of the sections the diagnosis prompt asks for — a
47
+ * report in another shape is read, not summarised.
48
+ */
49
+ export declare function readBatchDiagnosisSummary(ref: BatchDiagnosisReportRef): string | null;
@@ -0,0 +1,133 @@
1
+ // src/services/batch/batch-diagnosis-report-store.ts
2
+ //
3
+ // The diagnosis report's home on disk, next to the batch record it belongs
4
+ // to.
5
+ //
6
+ // WHY THE REPORT IS A FILE. A batch produces one diagnosis report per
7
+ // item, and the orchestrator's window cannot hold all of them — twenty
8
+ // reports cost ≈60 KB ≈15K tokens, and a batch produces N at once. So the
9
+ // report lands here, under the batch's own directory, and the orchestrator
10
+ // keeps only the bounded summary (see `batch-diagnosis-summary.ts`). The
11
+ // full report is read back on demand, when a phase needs the detail the
12
+ // summary left out.
13
+ //
14
+ // WHERE IT LIVES. `<sessionDir>/batch/<batchId>/diagnosis/<itemId>.md` —
15
+ // beside `progress.json`, one directory per batch, one file per item. The
16
+ // record and the reports are the same fact in two forms: the record says
17
+ // WHICH items are done, the reports say WHY.
18
+ //
19
+ // WHY THE WRITE IS ATOMIC. A reader that sees a half-written report reads
20
+ // it as a report with no sections, and the summary built from it carries
21
+ // no file set — so the topology stage would plan from an empty input
22
+ // rather than from a broken one. The write goes to a temp file in the same
23
+ // directory and is renamed over the target, the same pattern the progress
24
+ // record uses.
25
+ import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
26
+ import { dirname, join } from 'node:path';
27
+ import { isUnsafePathInput } from '../../shared/path-safety.js';
28
+ import { getSessionDir } from '../session/getSessionDir.js';
29
+ import { parseBatchDiagnosisFinding } from './batch-diagnosis-finding.js';
30
+ import { buildBatchDiagnosisSummary } from './batch-diagnosis-summary.js';
31
+ import { readBatchProgress } from './batch-progress-store.js';
32
+ const BATCH_DIR = 'batch';
33
+ const DIAGNOSIS_DIR = 'diagnosis';
34
+ const REPORT_EXTENSION = '.md';
35
+ /**
36
+ * A path segment the caller supplied, checked before it is joined.
37
+ *
38
+ * `batchId` and `itemId` both become path segments, so `..`, an absolute
39
+ * path, and a nested `a/b` would each write outside the directory the
40
+ * batch owns. The check is the same one the progress record uses.
41
+ */
42
+ function requireSegment(value, what) {
43
+ if (isUnsafePathInput(value) || value.includes('/') || value.includes('\\')) {
44
+ throw new Error(`Invalid ${what}: ${value} (must be a single safe path segment)`);
45
+ }
46
+ return value;
47
+ }
48
+ /**
49
+ * The directory one batch's diagnosis reports live in.
50
+ *
51
+ * @param projectRoot - Absolute path to the project root.
52
+ * @param sessionId - The session the batch belongs to.
53
+ * @param batchId - The batch's id.
54
+ */
55
+ export function batchDiagnosisReportDir(projectRoot, sessionId, batchId) {
56
+ requireSegment(batchId, 'batch id');
57
+ return join(getSessionDir(projectRoot, sessionId), BATCH_DIR, batchId, DIAGNOSIS_DIR);
58
+ }
59
+ /**
60
+ * The report path for one item of one batch.
61
+ *
62
+ * @param ref - Which report: the project, the session, the batch, the item.
63
+ */
64
+ export function batchDiagnosisReportPath(ref) {
65
+ const safeItemId = requireSegment(ref.itemId, 'item id');
66
+ return join(batchDiagnosisReportDir(ref.projectRoot, ref.sessionId, ref.batchId), `${safeItemId}${REPORT_EXTENSION}`);
67
+ }
68
+ /**
69
+ * The item's human name, from the batch record.
70
+ *
71
+ * The record is where the item's label lives; the report does not repeat
72
+ * it. When the record has no such item — a report written before the
73
+ * record caught up — the id stands in, so the summary still names the
74
+ * item it is about.
75
+ */
76
+ function readItemLabel(ref) {
77
+ const progress = readBatchProgress(ref.projectRoot, ref.sessionId, ref.batchId);
78
+ const item = progress?.items.find((entry) => entry.id === ref.itemId);
79
+ return item?.label ?? ref.itemId;
80
+ }
81
+ /**
82
+ * Write one item's diagnosis report, atomically.
83
+ *
84
+ * The report is stored verbatim: it is the diagnostician's own words, and
85
+ * the summary is derived from it rather than replacing it.
86
+ *
87
+ * @param ref - Which report: the project, the session, the batch, the item.
88
+ * @param report - The report text, verbatim.
89
+ */
90
+ export function writeBatchDiagnosisReport(ref, report) {
91
+ const path = batchDiagnosisReportPath(ref);
92
+ mkdirSync(dirname(path), { recursive: true });
93
+ // Temp file in the same directory, then rename: a write that fails
94
+ // halfway leaves the previous report intact rather than a truncated one.
95
+ const tmp = `${path}.tmp-${process.pid}-${Date.now()}`;
96
+ writeFileSync(tmp, report, 'utf8');
97
+ renameSync(tmp, path);
98
+ }
99
+ /**
100
+ * Read one item's diagnosis report.
101
+ *
102
+ * @returns The report text, or `null` when the item has no report yet.
103
+ */
104
+ export function readBatchDiagnosisReport(ref) {
105
+ const path = batchDiagnosisReportPath(ref);
106
+ if (!existsSync(path))
107
+ return null;
108
+ return readFileSync(path, 'utf8');
109
+ }
110
+ /**
111
+ * Read one item's diagnosis report AS THE SUMMARY the window may hold.
112
+ *
113
+ * The summary is derived from the stored report every time it is asked
114
+ * for, so the two can never drift apart: there is no second copy of the
115
+ * file set to fall out of date.
116
+ *
117
+ * @returns The summary, or `null` when there is no report, or when the
118
+ * report carries none of the sections the diagnosis prompt asks for — a
119
+ * report in another shape is read, not summarised.
120
+ */
121
+ export function readBatchDiagnosisSummary(ref) {
122
+ const report = readBatchDiagnosisReport(ref);
123
+ if (report === null)
124
+ return null;
125
+ const finding = parseBatchDiagnosisFinding(report);
126
+ if (finding === null)
127
+ return null;
128
+ return buildBatchDiagnosisSummary({
129
+ id: ref.itemId,
130
+ label: readItemLabel(ref),
131
+ finding
132
+ });
133
+ }
@@ -0,0 +1,31 @@
1
+ import { type BatchDiagnosisFinding } from './batch-diagnosis-finding.js';
2
+ /**
3
+ * The hard ceiling on the summary that may enter the orchestrator's
4
+ * window. The same 2 KB the report cap sets for a sub-agent's own final
5
+ * report: the orchestrator reads N of these, so the cap has to hold per
6
+ * report and the N has to be small.
7
+ */
8
+ export declare const BATCH_DIAGNOSIS_SUMMARY_MAX_BYTES = 2048;
9
+ /** The summary's input: which item it is about, and what was found. */
10
+ export interface BatchDiagnosisSummaryInput {
11
+ readonly id: string;
12
+ readonly label: string;
13
+ readonly finding: BatchDiagnosisFinding;
14
+ }
15
+ /**
16
+ * Cut a string to a byte budget without splitting a character.
17
+ *
18
+ * A cut that lands inside a multi-byte character produces a replacement
19
+ * character in the summary, which is a fact nobody asked for.
20
+ */
21
+ export declare function truncateToBytes(text: string, maxBytes: number): string;
22
+ /**
23
+ * Render the summary the orchestrator's window may hold.
24
+ *
25
+ * The shape is three lines under one heading: the conclusion, the file
26
+ * set, and the sketch.
27
+ *
28
+ * @param input - Which item the summary is about, and what was found.
29
+ * @returns A summary of at most {@link BATCH_DIAGNOSIS_SUMMARY_MAX_BYTES} bytes.
30
+ */
31
+ export declare function buildBatchDiagnosisSummary(input: BatchDiagnosisSummaryInput): string;
@@ -0,0 +1,129 @@
1
+ // src/services/batch/batch-diagnosis-summary.ts
2
+ //
3
+ // The bounded summary of one diagnosis report — the only form of that
4
+ // report the orchestrator's window may hold.
5
+ //
6
+ // WHY THE FULL REPORT MUST NOT ENTER THE WINDOW. Measured in this
7
+ // repository: twenty sub-agent reports cost ≈60 KB ≈15K tokens of the
8
+ // orchestrator's window. A batch produces N diagnosis reports at once, so
9
+ // the batch lane's window is hit by N reports arriving together —
10
+ // exactly the moment the orchestrator has to decide what to do next. So
11
+ // the report lands on disk (see `batch-diagnosis-report-store.ts`) and the
12
+ // window keeps only this summary: the conclusion, the file set, and a
13
+ // one-line sketch.
14
+ //
15
+ // WHY THE FILE SET IS MANDATORY IN THE SUMMARY. The topology stage plans
16
+ // the parallel waves from the MEASURED file sets and from nothing else
17
+ // (`planBatchTopology`). A summary without the file set would force the
18
+ // orchestrator to re-read N full reports to recover the one input it
19
+ // needs — which is the cost this module exists to remove. So the file set
20
+ // is the part of the summary that is never dropped.
21
+ //
22
+ // THE BUDGET IS SPENT IN A FIXED ORDER. The file set first, because it is
23
+ // the input the topology stage needs; the conclusion next; the sketch
24
+ // last, because it is the one the orchestrator can re-read from the full
25
+ // report if it must. What does not fit is cut — and what was cut is said
26
+ // out loud, because a summary that silently drops half a file set is
27
+ // worse than one that says it is partial.
28
+ import { collapse } from './batch-diagnosis-finding.js';
29
+ import { normalizeFileSet } from './batch-progress-store.js';
30
+ /**
31
+ * The hard ceiling on the summary that may enter the orchestrator's
32
+ * window. The same 2 KB the report cap sets for a sub-agent's own final
33
+ * report: the orchestrator reads N of these, so the cap has to hold per
34
+ * report and the N has to be small.
35
+ */
36
+ export const BATCH_DIAGNOSIS_SUMMARY_MAX_BYTES = 2048;
37
+ /**
38
+ * The ceiling on the conclusion inside the summary.
39
+ *
40
+ * The conclusion is "a sentence or two" by the diagnosis prompt's own
41
+ * wording; the cap keeps a chatty conclusion from eating the budget the
42
+ * file set needs.
43
+ */
44
+ const CONCLUSION_MAX_BYTES = 512;
45
+ /** The number of lines the summary renders, and so the newlines it costs. */
46
+ const SUMMARY_LINES = 4;
47
+ /** The top bits of a UTF-8 byte: set on every byte of a multi-byte character. */
48
+ const UTF8_LEAD_BITS = 0xc0;
49
+ /** The bit pattern of a UTF-8 continuation byte. */
50
+ const UTF8_CONTINUATION_BIT = 0x80;
51
+ /** The byte length of a string. The cap is a byte cap, not a character cap. */
52
+ function bytes(text) {
53
+ return Buffer.byteLength(text, 'utf8');
54
+ }
55
+ /**
56
+ * Cut a string to a byte budget without splitting a character.
57
+ *
58
+ * A cut that lands inside a multi-byte character produces a replacement
59
+ * character in the summary, which is a fact nobody asked for.
60
+ */
61
+ export function truncateToBytes(text, maxBytes) {
62
+ if (maxBytes <= 0)
63
+ return '';
64
+ const buffer = Buffer.from(text, 'utf8');
65
+ if (buffer.length <= maxBytes)
66
+ return text;
67
+ const ellipsis = '…';
68
+ const room = maxBytes - bytes(ellipsis);
69
+ if (room <= 0)
70
+ return '';
71
+ let end = room;
72
+ while (end > 0 && ((buffer[end] ?? 0) & UTF8_LEAD_BITS) === UTF8_CONTINUATION_BIT)
73
+ end -= 1;
74
+ return `${buffer.subarray(0, end).toString('utf8')}${ellipsis}`;
75
+ }
76
+ /**
77
+ * Fit as many paths as the budget allows, and say how many were left out.
78
+ *
79
+ * The file set is mandatory, so it is the last thing to be cut — but a
80
+ * file set of a hundred paths does not fit in 2 KB, and a summary that
81
+ * silently drops half of it is worse than one that says so. The full set
82
+ * stays authoritative on disk.
83
+ */
84
+ function fitFiles(files, budget) {
85
+ const kept = [];
86
+ for (const file of files) {
87
+ if (bytes([...kept, file].join(', ')) > budget)
88
+ break;
89
+ kept.push(file);
90
+ }
91
+ const omitted = files.length - kept.length;
92
+ if (omitted === 0)
93
+ return kept.join(', ');
94
+ const marker = ` …(+${omitted})`;
95
+ while (kept.length > 0 && bytes(kept.join(', ')) + bytes(marker) > budget)
96
+ kept.pop();
97
+ const room = budget - bytes(kept.join(', '));
98
+ if (room <= 0)
99
+ return kept.join(', ');
100
+ return `${kept.join(', ')}${truncateToBytes(marker, room)}`;
101
+ }
102
+ /**
103
+ * Render the summary the orchestrator's window may hold.
104
+ *
105
+ * The shape is three lines under one heading: the conclusion, the file
106
+ * set, and the sketch.
107
+ *
108
+ * @param input - Which item the summary is about, and what was found.
109
+ * @returns A summary of at most {@link BATCH_DIAGNOSIS_SUMMARY_MAX_BYTES} bytes.
110
+ */
111
+ export function buildBatchDiagnosisSummary(input) {
112
+ const header = `## ${input.id} · ${input.label}`;
113
+ const files = normalizeFileSet(input.finding.files);
114
+ const conclusion = collapse(input.finding.rootCause);
115
+ const sketch = collapse(input.finding.sketch);
116
+ const overhead = bytes(header) + bytes('结论:') + bytes('文件集:') + bytes('草图:') + SUMMARY_LINES;
117
+ let budget = BATCH_DIAGNOSIS_SUMMARY_MAX_BYTES - overhead;
118
+ let fileText = files.join(', ');
119
+ if (bytes(fileText) > budget) {
120
+ fileText = fitFiles(files, budget);
121
+ }
122
+ budget -= bytes(fileText);
123
+ const conclusionText = bytes(conclusion) > budget
124
+ ? truncateToBytes(conclusion, Math.min(budget, CONCLUSION_MAX_BYTES))
125
+ : conclusion;
126
+ budget -= bytes(conclusionText);
127
+ const sketchText = bytes(sketch) > budget ? truncateToBytes(sketch, budget) : sketch;
128
+ return `${header}\n结论:${conclusionText}\n文件集:${fileText}\n草图:${sketchText}\n`;
129
+ }
@@ -0,0 +1,36 @@
1
+ import { type FileOverlapWavePlan } from '../dispatch/file-overlap-wave-planner.js';
2
+ import type { BatchItem } from './batch-progress-types.js';
3
+ /**
4
+ * The one item a diagnostician is asked about.
5
+ *
6
+ * `symptom` is what the user reported, in the user's words. It is the
7
+ * symptom, not a diagnosis — the agent is the one that has to find the
8
+ * cause.
9
+ */
10
+ export interface BatchDiagnosisItem {
11
+ readonly id: string;
12
+ readonly label: string;
13
+ readonly symptom: string;
14
+ }
15
+ /**
16
+ * Plan the batch's waves from the file sets its items MEASURED.
17
+ *
18
+ * @param items - The batch's items, each carrying the file set its
19
+ * diagnosis reported.
20
+ * @returns The wave plan: items with disjoint file sets share a wave, and
21
+ * an item that collides with an earlier one is deferred behind it with
22
+ * the colliding file named.
23
+ */
24
+ export declare function planBatchTopology(items: readonly BatchItem[]): FileOverlapWavePlan;
25
+ /**
26
+ * Build the read-only prompt one diagnostician receives.
27
+ *
28
+ * The prompt asks for exactly the four outputs the batch pipeline
29
+ * consumes — the root cause, the files it expects to change, the risk
30
+ * surface it hit, and a fix sketch — and forbids the three write tools, so
31
+ * the file set it reports is a MEASUREMENT rather than a guess.
32
+ *
33
+ * @param item - The one item to diagnose.
34
+ * @returns The composed prompt, ready to be a sub-agent's dispatch body.
35
+ */
36
+ export declare function buildDiagnosisPrompt(item: BatchDiagnosisItem): string;
@@ -0,0 +1,107 @@
1
+ // src/services/batch/batch-diagnosis.ts
2
+ //
3
+ // The batch's diagnosis phase: the read-only prompt one diagnostician
4
+ // receives, and the topology the batch's MEASURED file sets produce.
5
+ //
6
+ // WHY THE FILE SETS ARE NORMALIZED HERE, NOT IN THE PLANNER. The wave
7
+ // planner (`planFileOverlapWaves`) matches a file by EXACT STRING EQUALITY —
8
+ // it dedupes and sorts, and nothing else. On a Windows host a
9
+ // backslash-spelled path and the same path spelled with forward slashes are
10
+ // two different strings to it, so two items that touch the SAME file look
11
+ // disjoint, land in the same wave, and two agents edit one file at once.
12
+ // `normalizeFileSet` is the one place that decides what a file set is, so
13
+ // the normalization happens HERE — on the way in — and the planner keeps
14
+ // its one job.
15
+ //
16
+ // WHY THE DIAGNOSIS IS READ-ONLY, MECHANICALLY. The file set a
17
+ // diagnostician reports is the only input the topology step has. A
18
+ // diagnostician that also wrote files would be reporting a guess about
19
+ // what it changed, and the whole measurement premise of the batch would
20
+ // be gone. So the prohibition is in the prompt the agent receives, not
21
+ // only in this file's comment.
22
+ //
23
+ // WHY THE PROMPT REUSES THE SHARED DISPATCH PREFIX. Every dispatched
24
+ // sub-agent gets the same governance prefix — the test-tool rule, the
25
+ // worktree-governance refusal, the lifecycle rules, the report cap, the
26
+ // fact-forcing gate. A diagnostician is a dispatched sub-agent like any
27
+ // other, so it gets that prefix from the one composer that owns it
28
+ // (`buildDispatchSystemPrompt`) rather than from a second hand-rolled copy
29
+ // that could drift away from it.
30
+ import { buildDispatchSystemPrompt } from '../context/build-dispatch-system-prompt.js';
31
+ import { planFileOverlapWaves } from '../dispatch/file-overlap-wave-planner.js';
32
+ import { normalizeFileSet } from './batch-progress-store.js';
33
+ /**
34
+ * The memory block a pure prompt builder carries.
35
+ *
36
+ * `buildDispatchSystemPrompt` takes a pre-fetched memory block, and the
37
+ * memory preflight is asynchronous I/O that belongs to the dispatch site,
38
+ * not to a pure prompt builder. The unavailable shape is the honest one
39
+ * here: this prompt carries no project memory block, and the composer
40
+ * renders its own "no block" form.
41
+ */
42
+ const NO_MEMORY_BLOCK = { available: false };
43
+ /**
44
+ * Plan the batch's waves from the file sets its items MEASURED.
45
+ *
46
+ * @param items - The batch's items, each carrying the file set its
47
+ * diagnosis reported.
48
+ * @returns The wave plan: items with disjoint file sets share a wave, and
49
+ * an item that collides with an earlier one is deferred behind it with
50
+ * the colliding file named.
51
+ */
52
+ export function planBatchTopology(items) {
53
+ const descriptors = items.map((item) => ({
54
+ id: item.id,
55
+ files: normalizeFileSet(item.files)
56
+ }));
57
+ return planFileOverlapWaves(descriptors);
58
+ }
59
+ /**
60
+ * Build the read-only prompt one diagnostician receives.
61
+ *
62
+ * The prompt asks for exactly the four outputs the batch pipeline
63
+ * consumes — the root cause, the files it expects to change, the risk
64
+ * surface it hit, and a fix sketch — and forbids the three write tools, so
65
+ * the file set it reports is a MEASUREMENT rather than a guess.
66
+ *
67
+ * @param item - The one item to diagnose.
68
+ * @returns The composed prompt, ready to be a sub-agent's dispatch body.
69
+ */
70
+ export function buildDiagnosisPrompt(item) {
71
+ const taskBody = [
72
+ `## Batch diagnosis — ${item.label}`,
73
+ '',
74
+ `- Item id: \`${item.id}\``,
75
+ `- Reported symptom: ${item.symptom}`,
76
+ '',
77
+ 'You are diagnosing ONE item of a batch. Other agents are diagnosing the',
78
+ 'others in parallel, on the same tree.',
79
+ '',
80
+ 'This phase is read-only (只读). You MUST NOT use Edit, Write, or MultiEdit,',
81
+ 'and you MUST NOT run any command that changes a file. Read, grep, list and',
82
+ 'read-only commands only.',
83
+ '',
84
+ 'Report exactly four things, in this order:',
85
+ '',
86
+ '1. **Root cause (根因)** — why the reported symptom happens, in a sentence',
87
+ ' or two.',
88
+ '2. **Expected files (预计文件集)** — the repo-relative paths a fix would',
89
+ ' have to touch, one per line, POSIX separators. This list is the only',
90
+ " input the batch's scheduling step has, so a path you are unsure about",
91
+ ' belongs IN the list: an item scheduled wrongly is the defect this',
92
+ ' phase exists to prevent.',
93
+ '3. **Risk surface hit (风险面命中)** — the number of the risk surface (1-7)',
94
+ " from the fast-lane norm's list (`peaks-code/references/fast-lane-norm.md`",
95
+ ' §2) that this item touches, or `none`. If you cannot read that list, say',
96
+ ' `unknown` rather than guessing a number.',
97
+ '4. **Fix sketch (修复草图)** — what the fix would look like, in a few',
98
+ ' sentences. The sketch only; do not apply it.',
99
+ '',
100
+ 'Do not fix anything. The fix is a later phase, run against your report.'
101
+ ].join('\n');
102
+ return buildDispatchSystemPrompt({
103
+ taskTitle: 'rd',
104
+ taskBody,
105
+ memoryBlock: NO_MEMORY_BLOCK
106
+ });
107
+ }
@@ -0,0 +1,22 @@
1
+ /**
2
+ * Whether a batch of independent items engages the batch machinery.
3
+ *
4
+ * `single` means: take today's path — no diagnosis fan-out, no rule
5
+ * pre-read, no topology step. `batch` means: the batch machinery may
6
+ * engage.
7
+ */
8
+ export type BatchMode = 'single' | 'batch';
9
+ /**
10
+ * The number of items at which the batch machinery engages.
11
+ *
12
+ * Two, because one item is the single-task lane's own case and the batch
13
+ * exists for the case where setup is amortized over more than one.
14
+ */
15
+ export declare const BATCH_MODE_MIN_ITEMS = 2;
16
+ /**
17
+ * Decide which path a batch of independent items takes.
18
+ *
19
+ * @param itemCount - How many independent items the user handed over.
20
+ * @returns `single` for zero or one item, `batch` for two or more.
21
+ */
22
+ export declare function decideBatchMode(itemCount: number): BatchMode;
@@ -0,0 +1,42 @@
1
+ // src/services/batch/batch-entry.ts
2
+ //
3
+ // The batch-mode entry decision: how many independent items make a batch.
4
+ //
5
+ // WHY THIS DECISION IS ITS OWN MODULE. Batch mode is an ADDITION to the
6
+ // race lane, never a substitute for it. The lane's single-task path is
7
+ // unchanged by a batch, and the only thing that decides whether a request
8
+ // takes it is how many independent items the user handed over. So the
9
+ // decision is isolated here: one function, one boundary, and every caller
10
+ // asks the same question the same way.
11
+ //
12
+ // THE BOUNDARY IS TWO, NOT ONE. One item is not a batch. The batch
13
+ // machinery — the parallel read-only diagnosis fan-out, the rule pre-read,
14
+ // the topology step — all exist to amortize setup across several
15
+ // independent items. Applied to one item they cost what they save and
16
+ // change the single-task lane's behaviour, which is the one thing the
17
+ // batch mode is forbidden from doing. So one item reads "single" and
18
+ // takes exactly the path it takes today.
19
+ //
20
+ // WHY THE COUNT IS NOT THE ONLY INPUT. This function counts ITEMS, and the
21
+ // caller is the one that has already established that the items are
22
+ // mutually independent. A batch of items that share a file is still a
23
+ // batch here: the topology step (see `batch-diagnosis.ts`) is what decides
24
+ // that two of them may not run at the same time, and folding that
25
+ // judgement in here would make the entry decision depend on the topology
26
+ // the entry decision exists to gate.
27
+ /**
28
+ * The number of items at which the batch machinery engages.
29
+ *
30
+ * Two, because one item is the single-task lane's own case and the batch
31
+ * exists for the case where setup is amortized over more than one.
32
+ */
33
+ export const BATCH_MODE_MIN_ITEMS = 2;
34
+ /**
35
+ * Decide which path a batch of independent items takes.
36
+ *
37
+ * @param itemCount - How many independent items the user handed over.
38
+ * @returns `single` for zero or one item, `batch` for two or more.
39
+ */
40
+ export function decideBatchMode(itemCount) {
41
+ return itemCount >= BATCH_MODE_MIN_ITEMS ? 'batch' : 'single';
42
+ }
@@ -0,0 +1,39 @@
1
+ import type { BatchItem } from './batch-progress-types.js';
2
+ import type { BatchFixDependencies, BatchFixDiagnosis } from './batch-fix-types.js';
3
+ /** The role the fix sub-agents are dispatched as: the lane's own RD role. */
4
+ export declare const FIX_ROLE = "rd";
5
+ /** Where the batch's record lives. */
6
+ export interface BatchFixContext {
7
+ readonly projectRoot: string;
8
+ readonly sessionId: string;
9
+ readonly batchId: string;
10
+ }
11
+ /** Everything one dispatched agent needs. */
12
+ export interface FixFrame {
13
+ readonly context: BatchFixContext;
14
+ readonly deps: BatchFixDependencies;
15
+ readonly diagnoses: Readonly<Record<string, BatchFixDiagnosis>>;
16
+ readonly rules: readonly string[];
17
+ }
18
+ /** One item, with the wave and the rid it was scheduled under. */
19
+ export interface ScheduledFix {
20
+ readonly item: BatchItem;
21
+ readonly waveIndex: number;
22
+ readonly rid: string;
23
+ }
24
+ /**
25
+ * Build the prompt one fix sub-agent receives.
26
+ *
27
+ * The prompt carries the ONE item's diagnosis and the rule list, and the
28
+ * shared governance prefix comes from the one composer that owns it — a
29
+ * second hand-rolled copy of the prefix would drift away from it.
30
+ */
31
+ export declare function buildFixPrompt(item: BatchItem, diagnosis: BatchFixDiagnosis, rules: readonly string[], rid: string): string;
32
+ /**
33
+ * Derive one agent's rid from the batch's rid and the item's id.
34
+ *
35
+ * The rid becomes a worktree branch name, so two agents may never share one.
36
+ * The item's id is sanitized into rid characters, and a collision (two ids
37
+ * that differ only in characters a rid cannot carry) is broken with a counter.
38
+ */
39
+ export declare function deriveAgentRid(baseRid: string, itemId: string, used: Set<string>): string;