peaks-loop 3.0.1 → 3.0.2

package/CHANGELOG.md

@@ -1,8 +1,12 @@
 # Changelog
 
-## [Unreleased] — 2026-06-29 — change-id shim (cleanup post v2.17.0 hard-kill)
+## [3.0.2] — 2026-07-02 — change-id shim retirement (v2.19.0) + Understand Anything hybrid context (3.0.2)
 
-**MINOR bump target: v2.19.0**. Full removal of the peaks-loop change-id axis (filesystem axis, code shim, envelope JSON slug, CLI flags). OpenSpec's independent `openspec/changes/<change-id>/` vocabulary (L4) is preserved untouched. One cleanup slice that retires the v2.17.0 shim half-life.
+**PATCH bump from 3.0.1**. Two independent slices bundled into one release:
+- **v2.19.0 change-id shim retirement** — full removal of the peaks-loop change-id axis (filesystem axis, code shim, envelope JSON slug, CLI flags). The change-id was a no-op post-v2.17.0 hard-kill; this slice retires the v2.17.0 shim half-life. OpenSpec's independent `openspec/changes/<change-id>/` vocabulary (L4) is preserved untouched.
+- **3.0.2 Understand Anything hybrid context** — new `peaks understand context` subcommand that encapsulates the UA-first / codegraph-fallback / hybrid-union routing decision in the service layer (per the peaks-loop "skill-first / CLI-auxiliary" architecture). Consumers no longer pick one or the other at the LLM level.
+
+The v2.19.0 work shipped as code commits (`f91d71c`, `5186d3d`, `b598612`, `ced835e`, `7ee9d8f`, plus follow-up tests) but was never formally released. v2.19.0 is therefore *not* a separate release line — its changes are rolled forward into 3.0.2. Future releases resume numeric sequence from 3.0.3.
 
 ### Removed — change-id shim (cleanup post v2.17.0 hard-kill)
 
@@ -70,7 +74,38 @@
 - Existing RD/QA artifacts in `.peaks/_runtime/<sid>/<role>/` remain readable; the planner no longer requires a change-id, and the change-id (if any) is embedded only as a filename slug.
 - The 2.8.3 hard-ban on `.peaks/_runtime/<YYYY-MM-DD-*>/` sibling directories is still enforced via the rewritten guard test and the inline `lstatSync` in `initWorkspace`.
 
-## [2.18.4] — 2026-06-29 — peaks-solo first-run step gates: hard-pause 1.x→2.0 upgrade + make `--mode` optional on Step 1
+## [3.0.2] — 2026-07-02 — change-id shim retirement (v2.19.0) + Understand Anything hybrid context (3.0.2)
+
+**PATCH bump from 3.0.1**. Two independent slices bundled into one release:
+- **v2.19.0 change-id shim retirement** — full removal of the peaks-loop change-id axis (filesystem axis, code shim, envelope JSON slug, CLI flags). The change-id was a no-op post-v2.17.0 hard-kill; this slice retires the v2.17.0 shim half-life. OpenSpec's independent `openspec/changes/<change-id>/` vocabulary (L4) is preserved untouched.
+- **3.0.2 Understand Anything hybrid context** — new `peaks understand context` subcommand that encapsulates the UA-first / codegraph-fallback / hybrid-union routing decision in the service layer (per the peaks-loop "skill-first / CLI-auxiliary" architecture). Consumers no longer pick one or the other at the LLM level.
+
+The v2.19.0 work shipped as code commits (`f91d71c`, `5186d3d`, `b598612`, `ced835e`, `7ee9d8f`, plus follow-up tests) but was never formally released. v2.19.0 is therefore *not* a separate release line — its changes are rolled forward into 3.0.2. Future releases resume numeric sequence from 3.0.3.
+
+### Added — `peaks understand context` (3.0.2 user-facing feature)
+
+The Understand Anything (UA) Claude Code plugin and `@colbymchenry/codegraph` are both complementary project-analysis tools. UA provides a high-level knowledge graph (tours, layers, expert prompts); codegraph provides low-level affected-file analysis. Until 3.0.2, peaks-loop consumers had to choose one or the other at the LLM level — there was no service-layer enforcement of either.
+
+This slice adds a single `peaks understand context` subcommand that encapsulates the routing decision in the service layer (per the peaks-loop "skill-first / CLI-auxiliary" architecture — see `peaks-solo` SKILL.md). The envelope carries a `source` tag so downstream consumers can audit which evidence contributed to the context.
+
+**Source routing** (deterministic, decided in `buildUnderstandContext`):
+- `ua-only` — UA knowledge graph present, no codegraph
+- `ua-missing-fallback-codegraph` — UA absent, codegraph produced evidence
+- `ua-and-codegraph-hybrid` — both present, both contribute (parallel `Promise.all`)
+- `both-missing` — neither produced evidence, exit code 2
+
+**Added files (5):**
+- `src/services/understand/understand-hybrid-service.ts` (133L, new): `buildUnderstandContext({projectRoot, files?, sampleSize?, artifactDir?, codegraphRunner?})` uses `Promise.all` to run UA scan and codegraph affected in parallel; total wall-clock = `max(uaMs, codegraphMs)`, not sum. Failures are caught into `warnings[]` (best-effort); the main envelope is always returned so consumers can audit missing evidence.
+- `src/services/understand/hybrid-types.ts` (39L, new): `UnderstandContextResult` envelope + 4-value source enum + `CodegraphContextBlock`.
+- `src/cli/commands/understand-commands.ts` (208L, +51L net): new `peaks understand context` subcommand at base path `admin/audit-logs` (the only 3rd CLI surface in the understand module family). The subcommand accepts `--project --files --sample --artifact-dir` and emits the envelope as JSON or human-readable summary.
+- `tests/unit/understand-hybrid-service.test.ts` (110L, 4 cases): `ua-only` / `fallback` / `hybrid` / `both-missing`.
+- `tests/integration/understand-hybrid-cli.test.ts` (85L, 3 cases): end-to-end CLI both-missing / ua-only / envelope-shape-stability.
+
+**Test evidence:** 7/7 vitest (4 unit + 3 integration), `tsc --noEmit` clean.
+
+The peak-loop skill-external-invocation audit pattern (capability discovery + references only + do-not-execute + Peaks authoritative) is preserved: codegraph is consumed via the existing `executeCodegraphInvocation` (no upstream installer calls); UA installation is a text `INSTALL_HINT` only.
+
+### Removed — change-id shim (cleanup post v2.17.0 hard-kill, rolled up from v2.19.0)
 
 **PATCH bump from 2.18.3**. Resolves the user-reported "新项目第一次使用 peaks-solo 时初始化完不按流程走、开发效果差、再开 session 后才正常" defect. Two surgical fixes to the first-run Solo gates (3 source files, 1 new test file, 2 test-regression updates; no schema change, no new dependencies, no public API change).
 

package/dist/src/cli/commands/understand-commands.js

@@ -1,5 +1,6 @@
 import { InvalidArgumentError } from 'commander';
 import { scanUnderstandAnything, summarizeKnowledgeGraph } from '../../services/understand/understand-scan-service.js';
+import { buildUnderstandContext } from '../../services/understand/understand-hybrid-service.js';
 import { fail, ok } from '../../shared/result.js';
 import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
 function parsePositiveInteger(value) {
@@ -109,4 +110,39 @@ export function registerUnderstandCommands(program, io) {
             process.exitCode = 1;
         }
     });
+    // Slice 2026-07-02-codegraph-ua-hybrid: hybrid context subcommand.
+    // Routes UA-first / codegraph-fallback / hybrid in the service layer;
+    // the CLI is a thin shell that surfaces the envelope and exit code.
+    addJsonOption(understand
+        .command('context')
+        .description('Build a hybrid project-context envelope: UA knowledge graph when present, codegraph affected as fallback, or both in parallel')
+        .requiredOption('--project <path>', 'target project root')
+        .option('--artifact-dir <path>', 'override the default .understand-anything directory')
+        .option('--sample <n>', 'maximum number of sample node ids to include (default 5)', parsePositiveInteger)
+        .option('--files <file...>', 'file globs to feed `codegraph affected` (default: src/index.ts, package.json, README.md)')).action(async (options) => {
+        try {
+            const ctxOptions = { projectRoot: options.project };
+            if (options.artifactDir !== undefined)
+                ctxOptions.artifactDir = options.artifactDir;
+            if (options.sample !== undefined)
+                ctxOptions.sampleSize = options.sample;
+            if (options.files !== undefined)
+                ctxOptions.files = options.files;
+            const result = await buildUnderstandContext(ctxOptions);
+            const exitCode = result.source === 'both-missing' ? 2 : 0;
+            if (exitCode !== 0) {
+                printResult(io, fail('understand.context', 'UNDERSTAND_CONTEXT_NO_EVIDENCE', `No UA graph and codegraph affected produced no usable evidence`, result, [
+                    INSTALL_HINT,
+                    'Run `peaks codegraph index` in this project to populate the codegraph index, then retry'
+                ]), options.json);
+                process.exitCode = exitCode;
+                return;
+            }
+            printResult(io, ok('understand.context', result, [], result.warnings.length > 0 ? result.warnings : undefined), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('understand.context', 'UNDERSTAND_CONTEXT_FAILED', getErrorMessage(error), { projectRoot: options.project }, ['Check the project path and codegraph installation before retrying']), options.json);
+            process.exitCode = 1;
+        }
+    });
 }

package/dist/src/services/understand/hybrid-types.d.ts

@@ -0,0 +1,32 @@
+import type { CodegraphExecutionResult } from '../codegraph/codegraph-service.js';
+import type { UnderstandScanReport } from './understand-types.js';
+import type { UnderstandGraphSummary } from './understand-scan-service.js';
+/**
+ * Slice 2026-07-02-codegraph-ua-hybrid — envelope contract for the
+ * `peaks understand context` command. The service layer decides which
+ * evidence to include based on environment detection; the source field
+ * is the authoritative routing signal.
+ */
+export type UnderstandContextSource = 'ua-only' | 'ua-missing-fallback-codegraph' | 'ua-and-codegraph-hybrid' | 'both-missing';
+export type CodegraphContextBlock = {
+    invocation: {
+        subcommand: 'affected';
+        files: string[];
+    };
+    execution: CodegraphExecutionResult;
+    /** Parsed JSON from `codegraph affected --json` when exitCode === 0; null otherwise. */
+    payload: unknown;
+    parseError?: string;
+};
+export type UnderstandContextResult = {
+    projectRoot: string;
+    source: UnderstandContextSource;
+    ua?: {
+        scan: UnderstandScanReport;
+        summary?: UnderstandGraphSummary;
+    };
+    codegraph?: CodegraphContextBlock;
+    /** Wall-clock milliseconds spent on the slowest parallel branch. */
+    durationMs: number;
+    warnings: string[];
+};

package/dist/src/services/understand/hybrid-types.js

@@ -0,0 +1 @@
+export {};

package/dist/src/services/understand/understand-hybrid-service.d.ts

@@ -0,0 +1,10 @@
+import { type CodegraphProcessRunner } from '../codegraph/codegraph-service.js';
+import type { UnderstandContextResult } from './hybrid-types.js';
+export type BuildUnderstandContextOptions = {
+    projectRoot: string;
+    files?: string[];
+    sampleSize?: number;
+    artifactDir?: string;
+    codegraphRunner?: CodegraphProcessRunner;
+};
+export declare function buildUnderstandContext(options: BuildUnderstandContextOptions): Promise<UnderstandContextResult>;

package/dist/src/services/understand/understand-hybrid-service.js

@@ -0,0 +1,100 @@
+import { createCodegraphInvocation, executeCodegraphInvocation } from '../codegraph/codegraph-service.js';
+import { scanUnderstandAnything, summarizeKnowledgeGraph } from './understand-scan-service.js';
+import { getErrorMessage } from '../../shared/result.js';
+const DEFAULT_FILES = ['src/index.ts', 'package.json', 'README.md'];
+function resolveFiles(files) {
+    if (files !== undefined && files.length > 0) {
+        return [...files];
+    }
+    return [...DEFAULT_FILES];
+}
+async function safeSummarize(options) {
+    try {
+        return { summary: await summarizeKnowledgeGraph(options) };
+    }
+    catch (error) {
+        return { warning: `UA summary failed: ${getErrorMessage(error)}` };
+    }
+}
+async function runCodegraph(projectRoot, files, runner) {
+    try {
+        const invocation = createCodegraphInvocation({
+            subcommand: 'affected',
+            project: projectRoot,
+            files,
+            json: true
+        });
+        const execution = await executeCodegraphInvocation(invocation, runner);
+        if (execution.exitCode !== 0) {
+            return { warning: `codegraph affected exited with code ${execution.exitCode}: ${execution.stderr.slice(0, 200)}` };
+        }
+        let payload = null;
+        let parseError;
+        try {
+            payload = JSON.parse(execution.stdout);
+        }
+        catch (error) {
+            parseError = getErrorMessage(error);
+        }
+        return {
+            block: {
+                invocation: { subcommand: 'affected', files },
+                execution,
+                payload,
+                ...(parseError !== undefined ? { parseError } : {})
+            }
+        };
+    }
+    catch (error) {
+        return { warning: `codegraph affected failed: ${getErrorMessage(error)}` };
+    }
+}
+function decideSource(uaScan, hasCodegraph) {
+    const uaPresent = uaScan.exists && uaScan.graph.exists && uaScan.graph.parseError === undefined;
+    if (uaPresent && hasCodegraph)
+        return 'ua-and-codegraph-hybrid';
+    if (uaPresent)
+        return 'ua-only';
+    if (hasCodegraph)
+        return 'ua-missing-fallback-codegraph';
+    return 'both-missing';
+}
+export async function buildUnderstandContext(options) {
+    const startedAt = Date.now();
+    const files = resolveFiles(options.files);
+    const sampleSize = options.sampleSize ?? 5;
+    const warnings = [];
+    const scanOptions = { projectRoot: options.projectRoot };
+    if (options.artifactDir !== undefined) {
+        scanOptions.artifactDir = options.artifactDir;
+    }
+    const uaScan = await scanUnderstandAnything(scanOptions);
+    const uaSummaryPromise = uaScan.exists && uaScan.graph.exists
+        ? safeSummarize({ projectRoot: options.projectRoot, sampleSize, ...(options.artifactDir !== undefined ? { artifactDir: options.artifactDir } : {}) })
+        : Promise.resolve({});
+    const [uaSummary, codegraphResult] = await Promise.all([
+        uaSummaryPromise,
+        runCodegraph(options.projectRoot, files, options.codegraphRunner)
+    ]);
+    if (uaSummary.warning)
+        warnings.push(uaSummary.warning);
+    if (codegraphResult.warning)
+        warnings.push(codegraphResult.warning);
+    const source = decideSource(uaScan, codegraphResult.block !== undefined);
+    const result = {
+        projectRoot: options.projectRoot,
+        source,
+        durationMs: Date.now() - startedAt,
+        warnings
+    };
+    if (source === 'ua-only' || source === 'ua-and-codegraph-hybrid') {
+        result.ua = {
+            scan: uaScan,
+            ...(uaSummary.summary !== undefined ? { summary: uaSummary.summary } : {})
+        };
+    }
+    if (codegraphResult.block) {
+        result.codegraph = codegraphResult.block;
+    }
+    return result;
+}

package/dist/src/shared/version.d.ts

@@ -1 +1 @@
-export declare const CLI_VERSION = "3.0.1";
+export declare const CLI_VERSION = "3.0.2";

package/dist/src/shared/version.js

@@ -1 +1 @@
-export const CLI_VERSION = "3.0.1";
+export const CLI_VERSION = "3.0.2";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "peaks-loop",
-  "version": "3.0.1",
+  "version": "3.0.2",
   "description": "Loop Engineering CLI — workflow primitive / loop guards / evaluators / slice orchestration",
   "author": "SquabbyZ",
   "license": "MIT",