peaks-loop 4.0.0-beta.8 → 4.0.0-beta.9

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, {
+    api: string;
+    file: string;
+    line: number;
+    expectedVersion: string;
+    actualVersion: string;
+    severity: "error" | "warning";
+}, {
+    api: string;
+    file: string;
+    line: number;
+    expectedVersion: string;
+    actualVersion: string;
+    severity: "error" | "warning";
+}>;
+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, {
+        api: string;
+        file: string;
+        line: number;
+        expectedVersion: string;
+        actualVersion: string;
+        severity: "error" | "warning";
+    }, {
+        api: string;
+        file: string;
+        line: number;
+        expectedVersion: string;
+        actualVersion: string;
+        severity: "error" | "warning";
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    passed: boolean;
+    violations: {
+        api: string;
+        file: string;
+        line: number;
+        expectedVersion: string;
+        actualVersion: string;
+        severity: "error" | "warning";
+    }[];
+}, {
+    passed: boolean;
+    violations: {
+        api: string;
+        file: string;
+        line: number;
+        expectedVersion: string;
+        actualVersion: string;
+        severity: "error" | "warning";
+    }[];
+}>;
+export declare const ExternalApiCallSchema: z.ZodObject<{
+    file: z.ZodString;
+    line: z.ZodNumber;
+    api: z.ZodString;
+    version: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    version: string;
+    api: string;
+    file: string;
+    line: number;
+}, {
+    version: string;
+    api: string;
+    file: 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;
+        api: string;
+        file: string;
+        line: number;
+    }, {
+        version: string;
+        api: string;
+        file: 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, {
+            api: string;
+            file: string;
+            line: number;
+            expectedVersion: string;
+            actualVersion: string;
+            severity: "error" | "warning";
+        }, {
+            api: string;
+            file: string;
+            line: number;
+            expectedVersion: string;
+            actualVersion: string;
+            severity: "error" | "warning";
+        }>, "many">;
+    }, "strip", z.ZodTypeAny, {
+        passed: boolean;
+        violations: {
+            api: string;
+            file: string;
+            line: number;
+            expectedVersion: string;
+            actualVersion: string;
+            severity: "error" | "warning";
+        }[];
+    }, {
+        passed: boolean;
+        violations: {
+            api: string;
+            file: string;
+            line: number;
+            expectedVersion: string;
+            actualVersion: string;
+            severity: "error" | "warning";
+        }[];
+    }>;
+}, "strip", z.ZodTypeAny, {
+    version: "1.0";
+    sha256: string;
+    generatedAt: string;
+    inputSig: string;
+    changedFiles: string[];
+    externalApiCalls: {
+        version: string;
+        api: string;
+        file: string;
+        line: number;
+    }[];
+    astGateResult: {
+        passed: boolean;
+        violations: {
+            api: string;
+            file: string;
+            line: number;
+            expectedVersion: string;
+            actualVersion: string;
+            severity: "error" | "warning";
+        }[];
+    };
+}, {
+    version: "1.0";
+    sha256: string;
+    generatedAt: string;
+    inputSig: string;
+    changedFiles: string[];
+    externalApiCalls: {
+        version: string;
+        api: string;
+        file: string;
+        line: number;
+    }[];
+    astGateResult: {
+        passed: boolean;
+        violations: {
+            api: string;
+            file: string;
+            line: number;
+            expectedVersion: string;
+            actualVersion: string;
+            severity: "error" | "warning";
+        }[];
+    };
+}>;
+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/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;

package/dist/services/recommendations/capability-map-service.js

@@ -0,0 +1,131 @@
+import { seedCapabilityItems, seedCapabilityLandingMappings, seedCapabilitySources } from './seed-capability-catalog.js';
+export function createCapabilityMapPlan(options = {}) {
+    const sourceFilter = options.source ?? 'all';
+    const httpProxy = normalizeProxyUrl(options.httpProxy);
+    const sources = sortSources(filterSources(sourceFilter));
+    const sourceIds = new Set(sources.map((source) => source.sourceId));
+    const items = sortItems(seedCapabilityItems.filter((item) => sourceIds.has(item.sourceId)));
+    const mappings = sortMappings(seedCapabilityLandingMappings.filter((mapping) => sourceIds.has(mapping.sourceId)));
+    const constraints = [
+        'dry-run only: do not install MCP servers, skills, hooks, agents, or browser tooling from this map',
+        'do not clone external repositories or write Claude settings from this map',
+        'do not write Peaks config or credentials from this map',
+        'do not send secrets, private code, or business data to external resources without explicit approval'
+    ];
+    if (httpProxy) {
+        constraints.push(`use HTTP proxy ${httpProxy} for GitHub, registries, MCP directories, and external web access`);
+    }
+    return {
+        dryRunOnly: true,
+        executionPolicy: {
+            allowInstall: false,
+            allowClone: false,
+            allowConfigWrite: false,
+            allowSecretExfiltration: false
+        },
+        ...(httpProxy
+            ? {
+                proxyPolicy: {
+                    requiredForExternalAccess: true,
+                    httpProxy
+                }
+            }
+            : {}),
+        sources: cloneSources(sources),
+        items: cloneItems(items),
+        mappings: cloneMappings(mappings),
+        availability: resolveDryRunAvailability(items, options.installedCapabilityIds ?? []),
+        constraints,
+        warnings: [
+            'Browser automation capabilities require explicit app target approval and must not submit forms, purchase, delete, or mutate authenticated state without confirmation.',
+            'Database capabilities require explicit credentials and confirmation before any write query.',
+            'Figma and design-source capabilities require user-authorized project access and must not persist tokens in project artifacts.',
+            'Cloud capabilities can affect cost or infrastructure and require explicit confirmation and credential boundaries.',
+            'External skill packs stay catalog-only until inspected for license, safety, and project fit.'
+        ]
+    };
+}
+function normalizeProxyUrl(value) {
+    if (value === undefined)
+        return undefined;
+    try {
+        const url = new URL(value);
+        return (url.protocol === 'http:' || url.protocol === 'https:') && url.username.length === 0 && url.password.length === 0 && url.pathname === '/' && url.search.length === 0 && url.hash.length === 0 ? value : undefined;
+    }
+    catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+        return undefined;
+    }
+}
+function filterSources(sourceFilter) {
+    if (sourceFilter === 'all') {
+        return seedCapabilitySources;
+    }
+    return seedCapabilitySources.filter((source) => source.sourceGroup === sourceFilter);
+}
+function sortSources(sources) {
+    return [...sources].sort((left, right) => left.sourceId.localeCompare(right.sourceId));
+}
+function sortItems(items) {
+    return [...items].sort((left, right) => left.capabilityId.localeCompare(right.capabilityId));
+}
+function sortMappings(mappings) {
+    return [...mappings].sort((left, right) => `${left.sourceId}:${left.capabilityId}`.localeCompare(`${right.sourceId}:${right.capabilityId}`));
+}
+function resolveDryRunAvailability(items, installedCapabilityIds) {
+    const installedIds = new Set(installedCapabilityIds);
+    return items.map((item) => ({
+        capabilityId: item.capabilityId,
+        type: getAvailabilityType(item),
+        status: installedIds.has(item.capabilityId) ? 'available' : 'unknown',
+        requiredFor: [...item.workflows],
+        fallback: cloneFallback(item.fallback),
+        risk: item.riskLevel
+    }));
+}
+function getAvailabilityType(item) {
+    if (item.itemType === 'mcp') {
+        return 'mcp';
+    }
+    if (item.itemType === 'agent') {
+        return 'agent';
+    }
+    if (item.itemType === 'cli') {
+        return 'cli';
+    }
+    return 'skill';
+}
+function cloneSources(sources) {
+    return sources.map((source) => ({
+        ...source,
+        ...(source.trustSignals
+            ? {
+                trustSignals: {
+                    ...source.trustSignals,
+                    ...(source.trustSignals.notes ? { notes: [...source.trustSignals.notes] } : {})
+                }
+            }
+            : {}),
+        items: [...source.items]
+    }));
+}
+function cloneItems(items) {
+    return items.map((item) => ({
+        ...item,
+        workflows: [...item.workflows],
+        audience: [...item.audience],
+        fallback: cloneFallback(item.fallback),
+        presentation: {
+            displayName: cloneLocalizedText(item.presentation.displayName),
+            description: cloneLocalizedText(item.presentation.description)
+        }
+    }));
+}
+function cloneMappings(mappings) {
+    return mappings.map((mapping) => ({ ...mapping }));
+}
+function cloneFallback(fallback) {
+    return { ...fallback };
+}
+function cloneLocalizedText(text) {
+    return { ...text };
+}

package/dist/services/recommendations/capability-seed-items.d.ts

@@ -0,0 +1,2 @@
+import type { CapabilityItem } from './recommendation-types.js';
+export declare const seedCapabilityItems: CapabilityItem[];