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,66 @@
1
+ /** Where a rule came from. */
2
+ export type RuleLayer = 'project' | 'language' | 'curated';
3
+ /** One effective rule, tagged with the layer that produced it. */
4
+ export interface EffectiveRule {
5
+ readonly layer: RuleLayer;
6
+ /** The concrete source: `eslint`, `ocr:system`, `ecc:typescript`, … */
7
+ readonly source: string;
8
+ /** The scope the rule was resolved for — a glob, or the files it covers. */
9
+ readonly pattern: string;
10
+ /** The rule text itself. */
11
+ readonly rule: string;
12
+ }
13
+ /** The three layers, read for one file set. */
14
+ export interface RuleSet {
15
+ /** The files the rules were read for, POSIX-normalized and deduplicated. */
16
+ readonly files: readonly string[];
17
+ readonly rules: readonly EffectiveRule[];
18
+ /** The lint tools the project declared, by name. */
19
+ readonly detectedTools: readonly string[];
20
+ /**
21
+ * Why the read looks the way it does. NEVER empty: a layer that could not
22
+ * be read says so here, because "no rules found" and "the layer never ran"
23
+ * are different answers and this repository has been bitten by that
24
+ * distinction before.
25
+ */
26
+ readonly reason: string;
27
+ }
28
+ /** A lint tool the project declared for itself. */
29
+ export interface ProjectLintTool {
30
+ /** The tool's name (`eslint`, `ruff`, `golangci-lint`, …). */
31
+ readonly name: string;
32
+ /** Where the project declared it — the declaration site, not a guess. */
33
+ readonly declaredBy: string;
34
+ /** The command the project declared. */
35
+ readonly command: string;
36
+ }
37
+ /** The outcome of looking for the project's own lint tooling. */
38
+ export interface ProjectLintToolDetection {
39
+ readonly tools: readonly ProjectLintTool[];
40
+ /**
41
+ * The explicit reason when no tool was found — never a silent empty list.
42
+ */
43
+ readonly reason: string;
44
+ /** Declaration sites that could not be read (malformed, unreadable, …). */
45
+ readonly problems: readonly string[];
46
+ }
47
+ /** The result of running one external tool as a subprocess. */
48
+ export type ToolInvocation = {
49
+ readonly ok: true;
50
+ readonly stdout: string;
51
+ } | {
52
+ readonly ok: false;
53
+ readonly reason: string;
54
+ };
55
+ /**
56
+ * The seams a test replaces so a rule read never spawns anything. Production
57
+ * callers pass nothing: every seam falls back to the real tool.
58
+ */
59
+ export interface RulePreReadDeps {
60
+ /** Replaces the OCR delegate rule invocation. */
61
+ readonly invokeDelegate?: (args: readonly string[], cwd: string) => ToolInvocation;
62
+ /** Replaces the invocation of a project's own lint tool. */
63
+ readonly invokeProjectTool?: (argv: readonly string[], cwd: string) => ToolInvocation;
64
+ /** Replaces the lookup of the curated (ECC) rule root. */
65
+ readonly resolveCuratedRoot?: () => string | null;
66
+ }
@@ -0,0 +1,22 @@
1
+ // src/services/lint/rule-pre-read-types.ts
2
+ //
3
+ // The shapes the rule pre-read speaks in.
4
+ //
5
+ // THREE LAYERS, THREE QUESTIONS. A rule set is only useful if a reader can
6
+ // tell WHERE a rule came from, because the three sources answer different
7
+ // questions and a fix that ignores one of them is still a fix that gets
8
+ // rejected:
9
+ //
10
+ // - `project` — "what will THIS project's gate reject?" (the project's own
11
+ // lint tooling, asked for its effective configuration)
12
+ // - `language` — "how should code in this language be written?" (the OCR
13
+ // delegate rule channel: deterministic, no key, no LLM call)
14
+ // - `curated` — "what are the general rules for this language?" (the ECC
15
+ // curated rule sets)
16
+ //
17
+ // `pattern` is the scope a rule was resolved for: a glob for the language and
18
+ // curated layers (the same pattern's text is emitted ONCE, never once per
19
+ // file), and the file list a project's resolved configuration covers for the
20
+ // project layer (a project's configuration is resolved per file, so the files
21
+ // that share one are named together).
22
+ export {};
@@ -0,0 +1,20 @@
1
+ import type { RulePreReadDeps, RuleSet } from './rule-pre-read-types.js';
2
+ export type { EffectiveRule, ProjectLintTool, ProjectLintToolDetection, RuleLayer, RulePreReadDeps, RuleSet, ToolInvocation } from './rule-pre-read-types.js';
3
+ export { detectProjectLintTools, NO_LINT_TOOL_REASON } from './project-lint-tool-detection.js';
4
+ /** The reason a read with no problem reports. */
5
+ export declare const RULES_RESOLVED_REASON = "all three layers resolved";
6
+ /**
7
+ * The effective rules for a file set, from all three layers.
8
+ *
9
+ * The returned `reason` is never empty: it names every layer that could not
10
+ * be read, and says so plainly when all three were.
11
+ */
12
+ export declare function readEffectiveRules(projectRoot: string, files: readonly string[], deps?: RulePreReadDeps): RuleSet;
13
+ /**
14
+ * The file set, repo-relative and POSIX-normalized.
15
+ *
16
+ * One file must be one string: a Windows path and a POSIX path naming the same
17
+ * file would otherwise be two entries, and a rule that governs one of them
18
+ * would look like it governs only half of the file.
19
+ */
20
+ export declare function normalizeFileSet(projectRoot: string, files: readonly string[]): readonly string[];
@@ -0,0 +1,145 @@
1
+ // src/services/lint/rule-pre-read.ts
2
+ //
3
+ // The rule pre-read — "what are the rules in force for these files?"
4
+ //
5
+ // THREE LAYERS, THREE QUESTIONS, NONE OF THEM OPTIONAL:
6
+ //
7
+ // L1 `project` — what will THIS project's gate reject? The project's own
8
+ // lint tooling, asked for its effective configuration.
9
+ // L2 `language` — how should code in this language be written? The OCR
10
+ // delegate rule channel: deterministic, no API key, no LLM
11
+ // call, and it accepts a plain path list.
12
+ // L3 `curated` — what are the general rules for this language? The ECC
13
+ // curated rule sets, matched by the file patterns each rule
14
+ // file declares.
15
+ //
16
+ // WHY THE FILE SET IS NEVER INSPECTED FOR A LANGUAGE. The mechanism is "ask
17
+ // the project what it declares", not "we support these languages". Nothing in
18
+ // this module — or in the three it composes — branches on the language of a
19
+ // file. A Go project, a Python project and a TypeScript project travel the
20
+ // same path; which rules come back is decided by what those projects declare.
21
+ //
22
+ // GROUPING IS WHAT KEEPS A FIX PROMPT SMALL. One TypeScript pattern carries
23
+ // about 2 KB of rule text, so the same pattern's text is emitted ONCE, never
24
+ // once per file. The layers that resolve per file (the project's own
25
+ // configuration) are grouped by the resolved text instead, so files that share
26
+ // a configuration share one entry.
27
+ //
28
+ // ZERO IS NOT "NEVER RAN". Every layer that could not be read says so in the
29
+ // reason, so a caller can tell "there are no rules" from "the layer was
30
+ // never asked".
31
+ import { buildDelegateRuleArgs, parseDelegateRules } from './ocr-18-delegate-payload.js';
32
+ import { invokeOcr } from './ocr-multilang-adapter.js';
33
+ import { readCuratedRules, resolveCuratedRulesRoot } from './curated-rule-reader.js';
34
+ import { detectProjectLintTools, NO_LINT_TOOL_REASON } from './project-lint-tool-detection.js';
35
+ import { readProjectLintRules } from './project-lint-tool-rules.js';
36
+ import { repoRelativeKey } from '../../shared/path-utils.js';
37
+ export { detectProjectLintTools, NO_LINT_TOOL_REASON } from './project-lint-tool-detection.js';
38
+ /** How long the language rule channel may take. */
39
+ const DELEGATE_TIMEOUT_MS = 60_000;
40
+ /** The reason a read with no problem reports. */
41
+ export const RULES_RESOLVED_REASON = 'all three layers resolved';
42
+ /**
43
+ * The effective rules for a file set, from all three layers.
44
+ *
45
+ * The returned `reason` is never empty: it names every layer that could not
46
+ * be read, and says so plainly when all three were.
47
+ */
48
+ export function readEffectiveRules(projectRoot, files, deps = {}) {
49
+ const normalized = normalizeFileSet(projectRoot, files);
50
+ const detection = detectProjectLintTools(projectRoot);
51
+ const reasons = [];
52
+ const rules = [];
53
+ if (detection.tools.length === 0) {
54
+ reasons.push(detection.reason === '' ? NO_LINT_TOOL_REASON : detection.reason);
55
+ }
56
+ else {
57
+ const project = readProjectLintRules(projectRoot, detection.tools, normalized, deps);
58
+ rules.push(...project.rules);
59
+ reasons.push(...project.reasons);
60
+ }
61
+ const language = readLanguageRules(projectRoot, normalized, deps);
62
+ rules.push(...language.rules);
63
+ reasons.push(...language.reasons);
64
+ const curated = readCuratedRules(normalized, curatedRootFor(deps));
65
+ rules.push(...curated.rules);
66
+ reasons.push(...curated.reasons);
67
+ return {
68
+ files: normalized,
69
+ rules,
70
+ detectedTools: detection.tools.map((tool) => tool.name),
71
+ reason: reasons.length === 0 ? RULES_RESOLVED_REASON : reasons.join('; ')
72
+ };
73
+ }
74
+ /**
75
+ * The file set, repo-relative and POSIX-normalized.
76
+ *
77
+ * One file must be one string: a Windows path and a POSIX path naming the same
78
+ * file would otherwise be two entries, and a rule that governs one of them
79
+ * would look like it governs only half of the file.
80
+ */
81
+ export function normalizeFileSet(projectRoot, files) {
82
+ const set = new Set();
83
+ for (const raw of files) {
84
+ if (typeof raw !== 'string' || raw.length === 0)
85
+ continue;
86
+ const relative = repoRelativeKey(raw, projectRoot).replace(/^\.\//, '');
87
+ if (relative.length > 0)
88
+ set.add(relative);
89
+ }
90
+ return [...set].sort();
91
+ }
92
+ /**
93
+ * L2 — the language rule channel.
94
+ *
95
+ * The channel is deterministic: it takes a path list and returns rule text
96
+ * grouped by pattern. No key is read and no model is called.
97
+ */
98
+ function readLanguageRules(projectRoot, files, deps) {
99
+ if (files.length === 0)
100
+ return { rules: [], reasons: [] };
101
+ const invoked = invokeDelegateChannel(files, projectRoot, deps);
102
+ if (!invoked.ok) {
103
+ return { rules: [], reasons: [`the language rule channel failed: ${invoked.reason}`] };
104
+ }
105
+ const parsed = parseDelegateRules(invoked.stdout);
106
+ if (!parsed.ok) {
107
+ return { rules: [], reasons: [`the language rule channel failed: ${parsed.rawOutput}`] };
108
+ }
109
+ const rules = [];
110
+ const seen = new Set();
111
+ for (const group of parsed.groups) {
112
+ // The same pattern's text is emitted ONCE — not once per file it covers.
113
+ const key = `${group.source} ${group.pattern}`;
114
+ if (seen.has(key))
115
+ continue;
116
+ seen.add(key);
117
+ rules.push({
118
+ layer: 'language',
119
+ source: `ocr:${group.source}`,
120
+ pattern: group.pattern,
121
+ rule: group.rule
122
+ });
123
+ }
124
+ return { rules, reasons: [] };
125
+ }
126
+ /** The language rule channel, through the test seam when there is one. */
127
+ function invokeDelegateChannel(files, projectRoot, deps) {
128
+ const args = buildDelegateRuleArgs(files, {});
129
+ if (deps.invokeDelegate !== undefined)
130
+ return deps.invokeDelegate(args, projectRoot);
131
+ const invoked = invokeOcr(args, projectRoot, DELEGATE_TIMEOUT_MS);
132
+ if (!invoked.ok) {
133
+ return { ok: false, reason: `${invoked.state}: ${invoked.rawOutput}` };
134
+ }
135
+ return { ok: true, stdout: invoked.stdout };
136
+ }
137
+ /** Where the curated rule sets live, through the test seam when there is one. */
138
+ function curatedRootFor(deps) {
139
+ if (deps.resolveCuratedRoot === undefined)
140
+ return resolveCuratedRulesRoot();
141
+ const path = deps.resolveCuratedRoot();
142
+ return path === null
143
+ ? { ok: false, reason: 'the curated rule sets are not available' }
144
+ : { ok: true, path };
145
+ }
@@ -2,6 +2,7 @@ import { readdir } from 'node:fs/promises';
2
2
  import { join } from 'node:path';
3
3
  import { isDirectory } from 'peaks-loop-shared/fs';
4
4
  import { detectBackendDirs, detectBackendFrameworks, detectMonorepoConfigs, detectNestedServiceEvidence, detectNextApiRoutes, detectNextServerActions, detectSwagger, GREENFIELD_MAX_SRC_FILES, GREENFIELD_MAX_LOCKFILE_DAYS, HIGH_CONFIDENCE_SIGNAL_COUNT, LEGACY_MIN_SRC_FILES, lockfileAgeDays, LOCKFILE_STALE_DAYS, readPackageJsonDeps } from './archetype-detection.js';
5
+ import { detectFrontendEvidence, frontendSignals, readRootBin } from './frontend-evidence.js';
5
6
  async function countSrcFiles(projectRoot, max = 500) {
6
7
  const srcDir = join(projectRoot, 'src');
7
8
  if (!(await isDirectory(srcDir))) {
@@ -93,9 +94,16 @@ function decideArchetype(detected) {
93
94
  matched: detected.lockfileAgeDays !== null && detected.lockfileAgeDays > LOCKFILE_STALE_DAYS,
94
95
  detail: detected.lockfileAgeDays === null ? 'no lockfile' : `${detected.lockfileAgeDays} days`
95
96
  });
97
+ signals.push(...frontendSignals(detected.hasBin, detected.frontendEvidence));
96
98
  if (!detected.hasPackageJson) {
97
99
  return { archetype: 'unknown', confidence: 'low', signals };
98
100
  }
101
+ // A published CLI is not a frontend. `bin` + no backend + no frontend
102
+ // evidence used to fall through to `frontend-monorepo` (monorepo config) or
103
+ // `legacy-frontend`, and `decideFrontendOnly` then called it frontend-only.
104
+ if (detected.hasBin && !hasBackend && detected.frontendEvidence === null) {
105
+ return { archetype: 'cli', confidence: 'high', signals };
106
+ }
99
107
  // Monorepo detection runs BEFORE the backend check: a monorepo with
100
108
  // a packages/server dir is a fullstack-monorepo, NOT legacy-fullstack.
101
109
  // backend sub-package fell through to `legacy-fullstack` because
@@ -146,17 +154,21 @@ function decideArchetype(detected) {
146
154
  return { archetype: 'unknown', confidence: 'low', signals };
147
155
  }
148
156
  function decideFrontendOnly(report) {
149
- if (report.archetype === 'legacy-frontend' || report.archetype === 'frontend-monorepo') {
150
- return { frontendOnly: true, reason: `archetype=${report.archetype}` };
157
+ if (report.archetype === 'cli') {
158
+ return { frontendOnly: false, reason: 'archetype=cli' };
151
159
  }
152
160
  const noBackend = !hasBackendEvidence(report.detected);
153
- if (noBackend && !report.detected.hasSwaggerOrProto) {
154
- return { frontendOnly: true, reason: 'no-backend-no-swagger' };
155
- }
156
- if (noBackend) {
161
+ if (noBackend && report.detected.hasSwaggerOrProto) {
157
162
  return { frontendOnly: false, reason: 'swagger-or-proto-present' };
158
163
  }
159
- return { frontendOnly: false, reason: 'backend-detected' };
164
+ if (!noBackend) {
165
+ return { frontendOnly: false, reason: 'backend-detected' };
166
+ }
167
+ const evidence = report.detected.frontendEvidence;
168
+ if (evidence === null) {
169
+ return { frontendOnly: false, reason: 'no-frontend-evidence' };
170
+ }
171
+ return { frontendOnly: true, reason: `frontend-evidence=${evidence}` };
160
172
  }
161
173
  /**
162
174
  * Three frontend integration scenarios, from the signals `detected`
@@ -177,7 +189,9 @@ function decideIntegrationMode(report) {
177
189
  export async function scanArchetype(options) {
178
190
  const { projectRoot } = options;
179
191
  const { exists: hasPackageJson, deps } = await readPackageJsonDeps(projectRoot);
192
+ const hasBin = await readRootBin(projectRoot);
180
193
  const backendFrameworks = await detectBackendFrameworks(deps);
194
+ const frontendEvidence = await detectFrontendEvidence(projectRoot, deps);
181
195
  const hasNext = Object.prototype.hasOwnProperty.call(deps, 'next');
182
196
  const hasNextApiRoutes = await detectNextApiRoutes(projectRoot, hasNext);
183
197
  const backendDirsPresent = await detectBackendDirs(projectRoot);
@@ -200,7 +214,9 @@ export async function scanArchetype(options) {
200
214
  hasNextApiRoutes,
201
215
  srcFileCount,
202
216
  backendDirsPresent,
203
- lockfileAgeDays: ageDays
217
+ lockfileAgeDays: ageDays,
218
+ hasBin,
219
+ frontendEvidence
204
220
  };
205
221
  const { archetype, confidence, signals } = decideArchetype(detected);
206
222
  const base = { archetype, confidence, signals, detected };
@@ -0,0 +1,19 @@
1
+ import type { ArchetypeSignal } from './scan-types.js';
2
+ /** Each list entry is the evidence CLASS returned to the caller, so the report
3
+ * can say what it saw instead of only the verdict. */
4
+ export declare const FRONTEND_FRAMEWORK_DEPS: string[];
5
+ export declare const FRONTEND_STYLE_DEPS: string[];
6
+ export declare const FRONTEND_APPLICATION_ROOTS: string[];
7
+ /** Upper bound on directory entries inspected per scan. An absent signal is the
8
+ * common case (every CLI and library), so the walk must stop even in a huge
9
+ * tree; a miss costs one skipped UI flow, a false positive costs a wrong
10
+ * project classification. */
11
+ export declare const FRONTEND_EVIDENCE_MAX_ENTRIES = 2000;
12
+ export declare function readRootBin(projectRoot: string): Promise<boolean>;
13
+ /** `null` when the repository has no positive frontend signal. Order is
14
+ * deliberate: a framework dep is stronger than a style dep, which is stronger
15
+ * than a file that could be a one-off. */
16
+ export declare function detectFrontendEvidence(projectRoot: string, deps: Record<string, string>): Promise<string | null>;
17
+ /** The two report signals this probe contributes, so the archetype service does
18
+ * not spend its line budget rebuilding them. */
19
+ export declare function frontendSignals(hasBin: boolean, evidence: string | null): ArchetypeSignal[];
@@ -0,0 +1,142 @@
1
+ // Positive frontend evidence for `scanArchetype`.
2
+ //
3
+ // "No backend" is not evidence of a frontend: a TypeScript CLI has neither and
4
+ // was reported `frontendOnly: true`. This module answers the opposite question —
5
+ // does the repository declare a frontend framework, a CSS-adjacent dependency,
6
+ // or carry a css/html-family asset under an application root? A `null` answer is
7
+ // the absence of an observation, and the caller reports it as
8
+ // `no-frontend-evidence`.
9
+ //
10
+ // The walk is scoped to application roots on purpose: an unscoped tree walk
11
+ // finds `examples/video-demo/src/styles.css` and the HTML under `skills/`, and
12
+ // calls a CLI a frontend.
13
+ import { readdir } from 'node:fs/promises';
14
+ import { join } from 'node:path';
15
+ import { isDirectory, pathExists, readText } from 'peaks-loop-shared/fs';
16
+ /** Each list entry is the evidence CLASS returned to the caller, so the report
17
+ * can say what it saw instead of only the verdict. */
18
+ export const FRONTEND_FRAMEWORK_DEPS = [
19
+ 'react',
20
+ 'react-dom',
21
+ 'vue',
22
+ 'svelte',
23
+ 'next',
24
+ 'nuxt',
25
+ '@angular/core',
26
+ 'solid-js',
27
+ 'preact',
28
+ 'astro',
29
+ 'gatsby',
30
+ 'remix'
31
+ ];
32
+ export const FRONTEND_STYLE_DEPS = [
33
+ 'tailwindcss',
34
+ 'sass',
35
+ 'less',
36
+ 'postcss',
37
+ 'styled-components',
38
+ '@emotion/react',
39
+ 'bootstrap'
40
+ ];
41
+ export const FRONTEND_APPLICATION_ROOTS = ['src', 'app', 'pages', 'components', 'public'];
42
+ /** Upper bound on directory entries inspected per scan. An absent signal is the
43
+ * common case (every CLI and library), so the walk must stop even in a huge
44
+ * tree; a miss costs one skipped UI flow, a false positive costs a wrong
45
+ * project classification. */
46
+ export const FRONTEND_EVIDENCE_MAX_ENTRIES = 2000;
47
+ const ASSET_EXTENSIONS = /\.(css|scss|sass|less|styl|html|htm|vue|svelte)$/;
48
+ /** Generated / installed trees never hold the project's own styles. */
49
+ const WALK_SKIP_DIRS = new Set(['node_modules', 'dist', 'build', 'out', 'coverage']);
50
+ function firstDeclared(deps, names) {
51
+ return names.find((name) => Object.prototype.hasOwnProperty.call(deps, name)) ?? null;
52
+ }
53
+ /** `bin` counts only when it points somewhere: a string or an object of strings. */
54
+ function hasNonEmptyBin(bin) {
55
+ if (typeof bin === 'string')
56
+ return bin.trim().length > 0;
57
+ if (bin === null || typeof bin !== 'object')
58
+ return false;
59
+ return Object.values(bin).some((value) => typeof value === 'string' && value.trim().length > 0);
60
+ }
61
+ export async function readRootBin(projectRoot) {
62
+ const pkgPath = join(projectRoot, 'package.json');
63
+ if (!(await pathExists(pkgPath)))
64
+ return false;
65
+ try {
66
+ const parsed = JSON.parse(await readText(pkgPath));
67
+ return hasNonEmptyBin(parsed.bin);
68
+ }
69
+ catch {
70
+ // An unreadable manifest is not a CLI claim, and not an absence of one
71
+ // either; `false` says only "no bin evidence was observed".
72
+ return false;
73
+ }
74
+ }
75
+ function isAssetFile(entry) {
76
+ return !entry.isDirectory() && ASSET_EXTENSIONS.test(entry.name);
77
+ }
78
+ function isSkippedDir(name) {
79
+ return name.startsWith('.') || WALK_SKIP_DIRS.has(name);
80
+ }
81
+ async function readDirSafe(dir) {
82
+ return readdir(dir, { withFileTypes: true }).catch(() => []);
83
+ }
84
+ async function assetUnderRoot(rootDir) {
85
+ const queue = [rootDir];
86
+ let inspected = 0;
87
+ while (queue.length > 0 && inspected < FRONTEND_EVIDENCE_MAX_ENTRIES) {
88
+ const current = queue.shift();
89
+ if (current === undefined)
90
+ break;
91
+ const entries = await readDirSafe(current);
92
+ inspected += entries.length;
93
+ if (entries.some(isAssetFile))
94
+ return true;
95
+ for (const entry of entries) {
96
+ if (entry.isDirectory() && !isSkippedDir(entry.name)) {
97
+ queue.push(join(current, entry.name));
98
+ }
99
+ }
100
+ }
101
+ return false;
102
+ }
103
+ /** The class names the whole asset family, not the extension that matched:
104
+ * a css, html, vue, or svelte file under `<root>` is `asset-under-<root>`. */
105
+ async function assetUnderApplicationRoots(projectRoot) {
106
+ for (const root of FRONTEND_APPLICATION_ROOTS) {
107
+ const rootDir = join(projectRoot, root);
108
+ if (!(await isDirectory(rootDir)))
109
+ continue;
110
+ if (await assetUnderRoot(rootDir))
111
+ return `asset-under-${root}`;
112
+ }
113
+ return null;
114
+ }
115
+ /** `null` when the repository has no positive frontend signal. Order is
116
+ * deliberate: a framework dep is stronger than a style dep, which is stronger
117
+ * than a file that could be a one-off. */
118
+ export async function detectFrontendEvidence(projectRoot, deps) {
119
+ const framework = firstDeclared(deps, FRONTEND_FRAMEWORK_DEPS);
120
+ if (framework !== null)
121
+ return framework;
122
+ const style = firstDeclared(deps, FRONTEND_STYLE_DEPS);
123
+ if (style !== null)
124
+ return style;
125
+ return assetUnderApplicationRoots(projectRoot);
126
+ }
127
+ /** The two report signals this probe contributes, so the archetype service does
128
+ * not spend its line budget rebuilding them. */
129
+ export function frontendSignals(hasBin, evidence) {
130
+ return [
131
+ {
132
+ name: 'bin',
133
+ matched: hasBin,
134
+ detail: hasBin ? 'package.json declares bin' : 'no bin in package.json'
135
+ },
136
+ {
137
+ name: 'frontend-evidence',
138
+ matched: evidence !== null,
139
+ detail: evidence ?? 'no frontend framework, style dependency, or css/html under an application root'
140
+ }
141
+ ];
142
+ }
@@ -1,4 +1,4 @@
1
- export type ProjectArchetype = 'greenfield' | 'legacy-frontend' | 'legacy-fullstack' | 'frontend-monorepo' | 'fullstack-monorepo' | 'unknown';
1
+ export type ProjectArchetype = 'greenfield' | 'legacy-frontend' | 'legacy-fullstack' | 'frontend-monorepo' | 'fullstack-monorepo' | 'cli' | 'unknown';
2
2
  export type ArchetypeSignal = {
3
3
  name: string;
4
4
  matched: boolean;
@@ -39,6 +39,13 @@ export type ArchetypeReport = {
39
39
  srcFileCount: number;
40
40
  backendDirsPresent: string[];
41
41
  lockfileAgeDays: number | null;
42
+ /** The root `package.json` declares a non-empty `bin` entry. */
43
+ hasBin: boolean;
44
+ /** The strongest positive frontend signal observed, or `null` when none
45
+ * was. A frontend framework dep, a CSS-adjacent dep, or a css/html-family
46
+ * asset under an application root. `frontendOnly` is derived from this,
47
+ * never from "the repository is not a backend". */
48
+ frontendEvidence: string | null;
42
49
  };
43
50
  };
44
51
  export type VisualTokenSource = {
@@ -30,10 +30,10 @@ export declare const SkillSearchInputSchema: z.ZodObject<{
30
30
  status: "status";
31
31
  resume: "resume";
32
32
  audit: "audit";
33
- "final-review": "final-review";
34
- content: "content";
35
- ide: "ide";
36
33
  test: "test";
34
+ ide: "ide";
35
+ content: "content";
36
+ "final-review": "final-review";
37
37
  doctor: "doctor";
38
38
  research: "research";
39
39
  triage: "triage";
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "peaks-loop",
3
- "version": "4.1.11",
3
+ "version": "4.1.13",
4
4
  "description": "Loop Engineering CLI — workflow primitive / loop guards / evaluators / slice orchestration",
5
5
  "author": "SquabbyZ",
6
6
  "keywords": [
@@ -129,10 +129,10 @@
129
129
  "picomatch": "4.0.7",
130
130
  "yaml": "^2.9.1",
131
131
  "zod": "^4.6.7",
132
- "peaks-loop-internal-runtime": "0.0.51",
133
- "peaks-loop-shared": "0.0.100",
134
- "peaks-loop-mut": "0.1.65",
135
- "peaks-loop-shared-channel": "0.0.68"
132
+ "peaks-loop-internal-runtime": "0.0.53",
133
+ "peaks-loop-shared": "0.0.102",
134
+ "peaks-loop-shared-channel": "0.0.70",
135
+ "peaks-loop-mut": "0.1.67"
136
136
  },
137
137
  "devDependencies": {
138
138
  "@changesets/cli": "2.31.1",
@@ -60,7 +60,19 @@ npx vitest run tests/unit/<file>.test.ts --no-coverage
60
60
 
61
61
  目的:防"改一处坏一处"。比全 suite 快 10-50×。
62
62
 
63
- ### 6. 写一个 commit message(先不 commit)
63
+ ### 6. lint 腿 —— 写完立刻查,不要等提交时
64
+
65
+ ```bash
66
+ peaks lint check --scope <刚改的文件> --json
67
+ ```
68
+
69
+ 只查刚改的那个文件,不扫全项目(扫全项目跟跑全 suite 一样慢,就白搭了 micro-cycle 的意义)。
70
+ `peaks lint check` 是只读 ESLint 校验器,不会写任何文件。
71
+
72
+ **红了就在同一个上下文里改**(同一轮 micro-cycle 内,改完重跑本腿),不要留到 pre-commit / pre-push ——
73
+ 那时上下文已经换了,返工成本是这里的十倍以上。
74
+
75
+ ### 7. 写一个 commit message(先不 commit)
64
76
 
65
77
  ```bash
66
78
  git add -p
@@ -174,7 +174,8 @@ section.
174
174
 
175
175
  ## What this lane does not write
176
176
 
177
- No sub-agent dispatches. No Gate A–G file chain. No `peaks request transition` state machine.
177
+ No sub-agent dispatches — the read-only diagnosis fan-out of batch mode below is the one
178
+ exception. No Gate A–G file chain. No `peaks request transition` state machine.
178
179
  No planning or review documents — no tech doc, bug analysis, review envelope, audit envelope,
179
180
  QA report or verdict. No job shape, no slice DAG, no swarm fan-out, no PRD phase, no
180
181
  orchestrator-to-implementer handoff.
@@ -183,3 +184,41 @@ Keep the parts that cost no wall-clock, because they are habits rather than cere
183
184
  file before editing it, the TDD micro-cycle, the four Karpathy guidelines, one codegraph
184
185
  query for the affected surface, one sentence before you start on what you will change and
185
186
  why, and nothing dropped in the project root.
187
+
188
+ ## Batch mode (批量模式)
189
+
190
+ **When it engages.** The user gives you **two or more mutually independent** bugs or small
191
+ requirements in one go. That is the whole trigger — nothing to configure, no threshold to
192
+ clear. **One item is not a batch:** a single task takes exactly the path it takes today —
193
+ no diagnosis fan-out, no rule pre-read, no topology step — and none of the machinery below
194
+ applies to it. Batch mode is an addition to this lane, never a substitute for it.
195
+
196
+ **The four phases.**
197
+
198
+ 1. **Parallel read-only diagnosis.** One reader per item, each reporting the root cause,
199
+ the files it expects to touch, and whether it hit a risk surface.
200
+ 2. **Topology.** The measured file sets decide what may run together: items whose file
201
+ sets are disjoint may proceed together, and an item that collides with another is
202
+ deferred behind it.
203
+ 3. **Fix.** Each item is fixed from its own diagnosis rather than from a fresh one, and
204
+ every item runs its scoped test as soon as it is fixed.
205
+ 4. **One unified verification.** The whole batch goes through the acceptance gate
206
+ **once** — the gate that §1 of `../peaks-code/references/fast-lane-norm.md` names, the
207
+ same one a single task runs. Only the count changes; the strictness does not. A red
208
+ unified verification points at the integration between items rather than at one item:
209
+ an item's own breakage is caught by its own scoped test.
210
+
211
+ **The diagnosis phase is read-only.** A diagnostician reads and reports; it does not edit.
212
+ `Edit`, `Write` and `MultiEdit` are forbidden there, and the reason is mechanical rather
213
+ than stylistic: the file set it reports is the only input the topology step has, so a
214
+ diagnostician that also wrote files would be reporting a guess.
215
+
216
+ **Risk surfaces are judged per item, not per batch.** An item that touches any of the risk
217
+ surfaces in §2 of `../peaks-code/references/fast-lane-norm.md` is pulled out of the batch
218
+ and takes the single-task path on its own. That list lives in the norm and is not restated
219
+ here; read it, judge each item against it, and pull the ones that hit it. A batch is not a
220
+ way to carry a task that does not belong in this lane.
221
+
222
+ **Where this lane leaves the window.** Batch mode is the only place it does, and only for
223
+ the read-only diagnosis phase: the diagnosis fan-out writes nothing, and every write stays
224
+ in this window.