peaks-loop 4.0.0-beta.8 → 4.0.1

package/dist/services/rd/tactical-stage.js

@@ -0,0 +1,62 @@
+/**
+ * Per spec §4.3 战术审计 (peaks-rd/战术) — orchestrator.
+ * Runs AST gate first; only writes TACT.sig if gate passes.
+ * Spec anchor: docs/superpowers/specs/2026-06-21-context-audit-redesign-design.md §4.3
+ * (R1-W3 consolidation; previously referenced as §4.2 which is `peaks-mut`).
+ */
+import { dirname } from 'node:path';
+import { runAstGate } from './ast-gate.js';
+import { writeImpl } from './impl.js';
+// H8 (audit trail hashable): TACT.inputSig MUST equal STRAT.sig upstream.
+// WHY load-bearing: without this check, an orchestrator could fabricate
+// any 64-hex inputSig and forge impl.json files that claim authority from
+// a non-existent strategy. Per-process Map keyed by dirname(stratOut)
+// because STRAT and TACT both write into the same project dir in v1.
+export const STRAT_SIG_REGISTRY = new Map();
+export function registerStratSig(projectDir, sig) {
+    STRAT_SIG_REGISTRY.set(projectDir, sig);
+}
+export const STRAT_SIG_CHAIN_INVARIANT = 'STRAT.sig chain broken';
+/**
+ * Run the tactical stage: AST gate → STRAT.sig chain check → TACT.sig write.
+ *
+ * @remarks
+ * **Call-order contract (H8 / load-bearing):** the caller MUST invoke
+ * `registerStratSig(projectDir, inputSig)` BEFORE calling `runTacticalStage`.
+ * The chain check runs AFTER the AST gate (intentionally — see inline comment
+ * below) and keys `STRAT_SIG_REGISTRY` by `dirname(input.out)`. If no STRAT.sig
+ * is registered for that key, this function throws
+ * `${STRAT_SIG_CHAIN_INVARIANT}: stratSig=<unregistered>`. The common
+ * production path is `runStrategicStage(...)` → `runTacticalStage(...)`;
+ * `runStrategicStage` calls `registerStratSig` internally.
+ *
+ * @param input - project, changed files, inputSig (must match registered
+ *                STRAT.sig for `dirname(input.out)`), AST-gate context, output path.
+ * @returns `ImplOutput` written atomically to `input.out`.
+ * @throws When the AST gate fails (re-thrown from `runAstGate`).
+ * @throws When `inputSig` does not match the registered STRAT.sig for the
+ *         project dir, or when no STRAT.sig is registered.
+ */
+export async function runTacticalStage(input) {
+    const astGate = await runAstGate({
+        project: input.project,
+        changedFiles: input.changedFiles,
+        context: input.context,
+    });
+    // H8 chain enforcement: inputSig must equal STRAT.sig for this project.
+    // Runs AFTER AST gate so existing AST-gate error semantics are preserved.
+    const projectDir = dirname(input.out);
+    const stratSig = STRAT_SIG_REGISTRY.get(projectDir);
+    if (stratSig === undefined || stratSig !== input.inputSig) {
+        throw new Error(`${STRAT_SIG_CHAIN_INVARIANT}: inputSig=${input.inputSig.slice(0, 12)}… ` +
+            `stratSig=${stratSig ? stratSig.slice(0, 12) + '…' : '<unregistered>'} ` +
+            `(projectDir=${projectDir})`);
+    }
+    return writeImpl({
+        out: input.out,
+        inputSig: input.inputSig,
+        changedFiles: input.changedFiles,
+        externalApiCalls: [], // v1: AST gate emits violations; future slice maps to calls
+        astGate,
+    });
+}

package/dist/services/rd/types.d.ts

@@ -0,0 +1,252 @@
+/**
+ * Per spec §4.2 战略审计 + 战术审计 — sub-stage outputs.
+ *
+ * Hard constraint H8 (audit trail hashable): every output has sha256.
+ * TACT.sig inputSig chain must reference STRAT.sig.
+ */
+import { z } from 'zod';
+export declare const StrategyOutputSchema: z.ZodObject<{
+    version: z.ZodLiteral<"1.0">;
+    sha256: z.ZodString;
+    generatedAt: z.ZodString;
+    goal: z.ZodString;
+    rootCauseAnalysis: z.ZodString;
+    impactSurface: z.ZodArray<z.ZodString, "many">;
+    designRationale: z.ZodString;
+    askUserQuestion: z.ZodOptional<z.ZodObject<{
+        question: z.ZodString;
+        options: z.ZodArray<z.ZodString, "many">;
+    }, "strip", z.ZodTypeAny, {
+        options: string[];
+        question: string;
+    }, {
+        options: string[];
+        question: string;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    version: "1.0";
+    goal: string;
+    sha256: string;
+    generatedAt: string;
+    rootCauseAnalysis: string;
+    impactSurface: string[];
+    designRationale: string;
+    askUserQuestion?: {
+        options: string[];
+        question: string;
+    } | undefined;
+}, {
+    version: "1.0";
+    goal: string;
+    sha256: string;
+    generatedAt: string;
+    rootCauseAnalysis: string;
+    impactSurface: string[];
+    designRationale: string;
+    askUserQuestion?: {
+        options: string[];
+        question: string;
+    } | undefined;
+}>;
+export type StrategyOutput = z.infer<typeof StrategyOutputSchema>;
+export declare const AstViolationSchema: z.ZodObject<{
+    file: z.ZodString;
+    line: z.ZodNumber;
+    api: z.ZodString;
+    expectedVersion: z.ZodString;
+    actualVersion: z.ZodString;
+    severity: z.ZodEnum<["error", "warning"]>;
+}, "strip", z.ZodTypeAny, {
+    file: string;
+    api: string;
+    severity: "error" | "warning";
+    line: number;
+    expectedVersion: string;
+    actualVersion: string;
+}, {
+    file: string;
+    api: string;
+    severity: "error" | "warning";
+    line: number;
+    expectedVersion: string;
+    actualVersion: string;
+}>;
+export declare const AstGateResultSchema: z.ZodObject<{
+    passed: z.ZodBoolean;
+    violations: z.ZodArray<z.ZodObject<{
+        file: z.ZodString;
+        line: z.ZodNumber;
+        api: z.ZodString;
+        expectedVersion: z.ZodString;
+        actualVersion: z.ZodString;
+        severity: z.ZodEnum<["error", "warning"]>;
+    }, "strip", z.ZodTypeAny, {
+        file: string;
+        api: string;
+        severity: "error" | "warning";
+        line: number;
+        expectedVersion: string;
+        actualVersion: string;
+    }, {
+        file: string;
+        api: string;
+        severity: "error" | "warning";
+        line: number;
+        expectedVersion: string;
+        actualVersion: string;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    passed: boolean;
+    violations: {
+        file: string;
+        api: string;
+        severity: "error" | "warning";
+        line: number;
+        expectedVersion: string;
+        actualVersion: string;
+    }[];
+}, {
+    passed: boolean;
+    violations: {
+        file: string;
+        api: string;
+        severity: "error" | "warning";
+        line: number;
+        expectedVersion: string;
+        actualVersion: string;
+    }[];
+}>;
+export declare const ExternalApiCallSchema: z.ZodObject<{
+    file: z.ZodString;
+    line: z.ZodNumber;
+    api: z.ZodString;
+    version: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    version: string;
+    file: string;
+    api: string;
+    line: number;
+}, {
+    version: string;
+    file: string;
+    api: string;
+    line: number;
+}>;
+export declare const ImplOutputSchema: z.ZodObject<{
+    version: z.ZodLiteral<"1.0">;
+    sha256: z.ZodString;
+    generatedAt: z.ZodString;
+    inputSig: z.ZodString;
+    changedFiles: z.ZodArray<z.ZodString, "many">;
+    externalApiCalls: z.ZodArray<z.ZodObject<{
+        file: z.ZodString;
+        line: z.ZodNumber;
+        api: z.ZodString;
+        version: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        version: string;
+        file: string;
+        api: string;
+        line: number;
+    }, {
+        version: string;
+        file: string;
+        api: string;
+        line: number;
+    }>, "many">;
+    astGateResult: z.ZodObject<{
+        passed: z.ZodBoolean;
+        violations: z.ZodArray<z.ZodObject<{
+            file: z.ZodString;
+            line: z.ZodNumber;
+            api: z.ZodString;
+            expectedVersion: z.ZodString;
+            actualVersion: z.ZodString;
+            severity: z.ZodEnum<["error", "warning"]>;
+        }, "strip", z.ZodTypeAny, {
+            file: string;
+            api: string;
+            severity: "error" | "warning";
+            line: number;
+            expectedVersion: string;
+            actualVersion: string;
+        }, {
+            file: string;
+            api: string;
+            severity: "error" | "warning";
+            line: number;
+            expectedVersion: string;
+            actualVersion: string;
+        }>, "many">;
+    }, "strip", z.ZodTypeAny, {
+        passed: boolean;
+        violations: {
+            file: string;
+            api: string;
+            severity: "error" | "warning";
+            line: number;
+            expectedVersion: string;
+            actualVersion: string;
+        }[];
+    }, {
+        passed: boolean;
+        violations: {
+            file: string;
+            api: string;
+            severity: "error" | "warning";
+            line: number;
+            expectedVersion: string;
+            actualVersion: string;
+        }[];
+    }>;
+}, "strip", z.ZodTypeAny, {
+    version: "1.0";
+    sha256: string;
+    generatedAt: string;
+    changedFiles: string[];
+    inputSig: string;
+    externalApiCalls: {
+        version: string;
+        file: string;
+        api: string;
+        line: number;
+    }[];
+    astGateResult: {
+        passed: boolean;
+        violations: {
+            file: string;
+            api: string;
+            severity: "error" | "warning";
+            line: number;
+            expectedVersion: string;
+            actualVersion: string;
+        }[];
+    };
+}, {
+    version: "1.0";
+    sha256: string;
+    generatedAt: string;
+    changedFiles: string[];
+    inputSig: string;
+    externalApiCalls: {
+        version: string;
+        file: string;
+        api: string;
+        line: number;
+    }[];
+    astGateResult: {
+        passed: boolean;
+        violations: {
+            file: string;
+            api: string;
+            severity: "error" | "warning";
+            line: number;
+            expectedVersion: string;
+            actualVersion: string;
+        }[];
+    };
+}>;
+export type ImplOutput = z.infer<typeof ImplOutputSchema>;
+export type AstViolation = z.infer<typeof AstViolationSchema>;
+export type AstGateResult = z.infer<typeof AstGateResultSchema>;
+export type ExternalApiCall = z.infer<typeof ExternalApiCallSchema>;

package/dist/services/rd/types.js

@@ -0,0 +1,47 @@
+/**
+ * Per spec §4.2 战略审计 + 战术审计 — sub-stage outputs.
+ *
+ * Hard constraint H8 (audit trail hashable): every output has sha256.
+ * TACT.sig inputSig chain must reference STRAT.sig.
+ */
+import { z } from 'zod';
+export const StrategyOutputSchema = z.object({
+    version: z.literal('1.0'),
+    sha256: z.string().regex(/^[a-f0-9]{64}$/),
+    generatedAt: z.string().datetime(),
+    goal: z.string(),
+    rootCauseAnalysis: z.string(),
+    impactSurface: z.array(z.string()),
+    designRationale: z.string(),
+    askUserQuestion: z.object({
+        question: z.string(),
+        options: z.array(z.string()),
+    }).optional(),
+});
+export const AstViolationSchema = z.object({
+    file: z.string(),
+    line: z.number().int(),
+    api: z.string(),
+    expectedVersion: z.string(),
+    actualVersion: z.string(),
+    severity: z.enum(['error', 'warning']),
+});
+export const AstGateResultSchema = z.object({
+    passed: z.boolean(),
+    violations: z.array(AstViolationSchema),
+});
+export const ExternalApiCallSchema = z.object({
+    file: z.string(),
+    line: z.number().int(),
+    api: z.string(),
+    version: z.string(),
+});
+export const ImplOutputSchema = z.object({
+    version: z.literal('1.0'),
+    sha256: z.string().regex(/^[a-f0-9]{64}$/),
+    generatedAt: z.string().datetime(),
+    inputSig: z.string().regex(/^[a-f0-9]{64}$/), // STRAT.sig
+    changedFiles: z.array(z.string()),
+    externalApiCalls: z.array(ExternalApiCallSchema),
+    astGateResult: AstGateResultSchema,
+});

package/dist/services/rd-swarm/rd-swarm-service.d.ts

@@ -0,0 +1,60 @@
+import type { WorkspaceConfig } from '../config/config-types.js';
+import { type BoundaryError } from '../openspec/artifact-boundary.js';
+export type RdSwarmPlanRequest = {
+    skill: 'rd' | string;
+    changeId: string;
+    goal: string;
+    maxWorkers?: number;
+    dryRun: true;
+    workspaceRoot: string;
+    targetRepoRoot?: string;
+    requiresTechApproval?: boolean;
+    workspace?: WorkspaceConfig;
+};
+export type RdWaveName = 'discovery' | 'planning' | 'implementation candidates' | 'quality gates' | 'reducer';
+export type RdTask = {
+    taskId: string;
+    wave: RdWaveName;
+    workerKind: string;
+    purpose: string;
+    inputs: string[];
+    outputs: [string, ...string[]];
+    dependsOn: string[];
+    conflictGroup: string;
+    targetArea: string;
+    expectedEvidence: string;
+};
+export type RdConflictGroup = {
+    groupId: string;
+    ownedPaths: string[];
+    parallelismPolicy: 'parallel' | 'sequential';
+    reason: string;
+};
+export type RdTaskGraph = {
+    changeId: string;
+    goal: string;
+    available: boolean;
+    workerTarget: number;
+    waves: Array<{
+        name: RdWaveName;
+        taskIds: string[];
+    }>;
+    tasks: RdTask[];
+    conflictGroups: RdConflictGroup[];
+    artifactRoot: string;
+    outputs: {
+        taskGraph: string;
+        waveManifests: string[];
+        workerBriefs: string[];
+        reducerReport: string;
+    };
+    gateStatus: {
+        techApprovalRequired: boolean;
+        techStatus: string;
+        skipReason?: string;
+    };
+    blockedReasons: string[];
+    nextActions: string[];
+};
+export declare function planRdSwarmGraph(input: RdSwarmPlanRequest): RdTaskGraph;
+export type { BoundaryError };

package/dist/services/rd-swarm/rd-swarm-service.js

@@ -0,0 +1,93 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { planArtifactPath, validateChangeId } from '../openspec/artifact-boundary.js';
+import { getTechStatus as getLegacyTechStatus } from '../tech/tech-service.js';
+const MIN_WORKERS = 25;
+const MAX_WORKERS = 40;
+const REQUIRED_TECH_FILES = ['frontend-tech-doc.md', 'backend-tech-doc.md', 'tech-approval-record.md'];
+function failure(input, reasons, actions, gateStatus, workerTarget) {
+    return { ...input, available: false, workerTarget, waves: [], tasks: [], conflictGroups: [], outputs: { taskGraph: `${input.artifactRoot}/task-graph.json`, waveManifests: [], workerBriefs: [], reducerReport: `${input.artifactRoot}/reducer-report.md` }, gateStatus, blockedReasons: reasons, nextActions: actions };
+}
+function validate(input) {
+    if (input.skill !== 'rd')
+        return { ok: false, error: { code: 'UNSUPPORTED_SWARM_SKILL', message: `Unsupported skill ${input.skill}` } };
+    const id = validateChangeId(input.changeId);
+    if (!id.ok)
+        return { ok: false, error: id.error };
+    const goal = input.goal.trim();
+    if (!goal)
+        return { ok: false, error: { code: 'INVALID_GOAL', message: 'Goal must be non-empty' } };
+    return { ok: true, value: { changeId: id.value.changeId, goal } };
+}
+function localTechStatus(input) {
+    try {
+        const canonical = getLegacyTechStatus({ sessionId: input.changeId, artifactWorkspacePath: input.workspaceRoot, ...(input.workspace ? { workspace: input.workspace } : {}) });
+        if (canonical.status === 'approved')
+            return 'approved';
+    }
+    catch { /* pure planner fallback for an unconfigured workspace */ }
+    const root = join(input.workspaceRoot, input.changeId, 'rd', 'architecture');
+    const missing = REQUIRED_TECH_FILES.filter((name) => !existsSync(join(root, name)));
+    if (missing.length > 0)
+        return missing.includes('tech-approval-record.md') && missing.length === 1 ? 'missing-approval' : 'missing';
+    try {
+        return readFileSync(join(root, 'tech-approval-record.md'), 'utf8').split(/\r?\n/).some((line) => line.trim() === 'status: approved') ? 'approved' : 'not-approved';
+    }
+    catch {
+        return 'not-approved';
+    }
+}
+function path(input, template) {
+    const result = planArtifactPath({ changeId: input.changeId, workspaceRoot: input.workspaceRoot, role: 'rd', requestId: 'swarm', template });
+    if (!result.ok)
+        throw new Error(result.error.message);
+    return result.value.jsonSafeRelativePath;
+}
+function createTask(taskId, wave, goal, dependencies, index) {
+    const output = `workers/${taskId}/brief.md`;
+    return { taskId, wave, workerKind: taskId, purpose: `${taskId} for ${goal}`, inputs: [goal], outputs: [output], dependsOn: [...dependencies], conflictGroup: `group-${wave.replace(/\s/g, '-')}`, targetArea: wave === 'implementation candidates' ? `slice-${index + 1}` : wave, expectedEvidence: `${taskId}-evidence.md` };
+}
+function taskIds(target) {
+    const discovery = ['rd-frontend-scan', 'rd-backend-scan', 'rd-test-scan', 'rd-contract-scan', 'rd-risk-scan'];
+    const planning = ['rd-frontend-slicer', 'rd-backend-slicer', 'rd-unit-test-slicer', 'rd-contract-planner', 'rd-quality-gate-planner'];
+    const quality = ['rd-code-review-worker', 'rd-security-review-worker', 'rd-typecheck-worker', 'rd-coverage-worker', 'rd-regression-worker'];
+    const implementationCount = Math.max(1, target - discovery.length - planning.length - quality.length - 1);
+    const implementation = Array.from({ length: implementationCount }, (_, i) => `rd-impl-${String(i + 1).padStart(3, '0')}`);
+    return { discovery, planning, 'implementation candidates': implementation, 'quality gates': quality, reducer: ['rd-reducer-worker'] };
+}
+export function planRdSwarmGraph(input) {
+    const checked = validate(input);
+    const defaultRoot = `${input.changeId}/swarm`;
+    const common = { changeId: input.changeId, goal: input.goal.trim(), artifactRoot: defaultRoot };
+    const requested = input.maxWorkers ?? 25;
+    if (!checked.ok)
+        return failure(common, [checked.error.code], [checked.error.message], { techApprovalRequired: input.requiresTechApproval === true, techStatus: 'unavailable' }, Number.isInteger(requested) && requested > 0 ? Math.min(requested, MAX_WORKERS) : 0);
+    if (!Number.isInteger(requested) || requested < 1)
+        return failure({ ...common, goal: checked.value.goal, changeId: checked.value.changeId, artifactRoot: `${checked.value.changeId}/swarm` }, ['INVALID_MAX_WORKERS'], ['Use a positive integer for max-workers.'], { techApprovalRequired: input.requiresTechApproval === true, techStatus: 'unavailable' }, 0);
+    const goal = checked.value.goal;
+    const changeId = checked.value.changeId;
+    const artifactRoot = `${changeId}/swarm`;
+    const target = Math.min(requested, MAX_WORKERS);
+    const reasons = requested > MAX_WORKERS ? ['WORKER_CAP_EXCEEDED'] : [];
+    if (requested < MIN_WORKERS)
+        reasons.push('SMALL_SCOPE');
+    const required = input.requiresTechApproval === true;
+    const techStatus = localTechStatus({ ...input, changeId, goal });
+    const gateStatus = { techApprovalRequired: required, techStatus, ...(required ? {} : { skipReason: 'tech-gate-not-required' }) };
+    if (required && techStatus !== 'approved') {
+        reasons.push('TECH_APPROVAL_REQUIRED');
+        if (techStatus === 'missing-approval' || techStatus === 'missing')
+            reasons.push('TECH_APPROVAL_MISSING');
+    }
+    if (reasons.includes('SMALL_SCOPE'))
+        return failure({ changeId, goal, artifactRoot }, reasons, ['Describe the small scope in natural language or increase the worker target to at least 25.'], gateStatus, target);
+    if (required && techStatus !== 'approved')
+        return failure({ changeId, goal, artifactRoot }, reasons, ['Review and approve the technical plan before running the RD swarm.'], gateStatus, target);
+    const ids = taskIds(target);
+    const waves = Object.entries(ids).map(([name, taskIds]) => ({ name, taskIds }));
+    const dependencies = { discovery: [], planning: ids.discovery, 'implementation candidates': ids.planning, 'quality gates': ids['implementation candidates'], reducer: ids['quality gates'] };
+    const tasks = waves.flatMap(({ name, taskIds: waveTaskIds }) => waveTaskIds.map((id, i) => createTask(id, name, goal, dependencies[name], i)));
+    const conflictGroups = waves.map(({ name, taskIds: waveTaskIds }) => ({ groupId: `group-${name.replace(/\s/g, '-')}`, ownedPaths: waveTaskIds.map((id) => `${artifactRoot}/workers/${id}/brief.md`), parallelismPolicy: waveTaskIds.length > 1 ? 'parallel' : 'sequential', reason: `${name} workers have isolated artifact ownership` }));
+    const outputs = { taskGraph: path(input, '<changeId>/swarm/task-graph.json'), waveManifests: waves.map((wave, i) => path(input, `<changeId>/swarm/waves/wave-${i + 1}-${wave.name}.json`)), workerBriefs: tasks.map((task) => path(input, `<changeId>/swarm/${task.outputs[0]}`)), reducerReport: path(input, '<changeId>/swarm/reducer-report.md') };
+    return { changeId, goal, available: true, workerTarget: target, waves, tasks, conflictGroups, artifactRoot, outputs, gateStatus, blockedReasons: reasons, nextActions: reasons.includes('WORKER_CAP_EXCEEDED') ? ['Worker target was capped at 40.'] : [] };
+}

package/dist/services/recommendations/capability-availability.d.ts

@@ -0,0 +1,5 @@
+import type { CapabilityAvailability, CapabilityItem } from './recommendation-types.js';
+export type CapabilityAvailabilityOptions = {
+    installedCapabilityIds?: string[];
+};
+export declare function resolveCapabilityAvailability(items: CapabilityItem[], options?: CapabilityAvailabilityOptions): CapabilityAvailability[];

package/dist/services/recommendations/capability-availability.js

@@ -0,0 +1,40 @@
+function getAvailabilityType(item) {
+    if (item.itemType === 'mcp') {
+        return 'mcp';
+    }
+    if (item.itemType === 'agent') {
+        return 'agent';
+    }
+    if (item.itemType === 'cli') {
+        return 'cli';
+    }
+    return 'skill';
+}
+function getMissingStatus(item) {
+    if (item.itemType === 'mcp' || item.itemType === 'skill' || item.itemType === 'agent') {
+        return 'installable';
+    }
+    return 'unknown';
+}
+export function resolveCapabilityAvailability(items, options = {}) {
+    const installedCapabilityIds = new Set(options.installedCapabilityIds ?? []);
+    return items.map((item) => {
+        const isInstalled = installedCapabilityIds.has(item.capabilityId);
+        const status = isInstalled ? 'available' : getMissingStatus(item);
+        const installPlan = isInstalled
+            ? undefined
+            : {
+                available: status === 'installable',
+                requiresApproval: true
+            };
+        return {
+            capabilityId: item.capabilityId,
+            type: getAvailabilityType(item),
+            status,
+            requiredFor: item.workflows,
+            ...(installPlan ? { installPlan } : {}),
+            fallback: item.fallback,
+            risk: item.riskLevel
+        };
+    });
+}

package/dist/services/recommendations/capability-map-service.d.ts

@@ -0,0 +1,7 @@
+import type { CapabilityMapPlan, CapabilityMapSourceFilter } from './recommendation-types.js';
+export type CapabilityMapOptions = {
+    source?: CapabilityMapSourceFilter;
+    installedCapabilityIds?: string[];
+    httpProxy?: string;
+};
+export declare function createCapabilityMapPlan(options?: CapabilityMapOptions): CapabilityMapPlan;