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

package/dist/services/agent/ecc-agent-service.js

@@ -0,0 +1,143 @@
+/**
+ * ECC 64 agents soft-optional integration — `peaks agent run`.
+ *
+ * Per spec §7.2 line 818: "64 agents — Soft Optional — 装了 L3
+ * 直接调; 不装 L3 退化到 peaks-loop 自有少数核心诊断". The
+ * canonical ECC subprocess contract is:
+ *
+ *   npx ecc consult "<topic>" --target claude
+ *   npx ecc agent run <agent-name> --target <path> --json
+ *
+ * The peaks-loop `peaks agent run <name> --target <path> --json`
+ * CLI shells out to the second form. When ECC is missing OR
+ * `agentShieldEnabled: false`, the audit completes with a
+ * peaks-loop-only envelope.
+ *
+ * Mirrors `static-service.ts` (the ECC AgentShield wrapper from
+ * L2.3 P2-a): same `subprocessRunner` injection point, same
+ * 5-state reason enum, same soft-fail policy.
+ */
+import { spawnSync } from 'node:child_process';
+/**
+ * The 12 most-used ECC agents per the upstream
+ * everything-claude-code catalog. The full 64-agent list is
+ * available at runtime via `npx ecc agent list`; this static
+ * subset covers the common L3-doctor dispatch paths.
+ */
+export const CANONICAL_ECC_AGENTS = [
+    { name: 'security-reviewer', description: 'Audit trust boundary + OWASP top-10' },
+    { name: 'code-reviewer', description: 'General-purpose code review' },
+    { name: 'typescript-reviewer', description: 'TypeScript-specific review' },
+    { name: 'python-reviewer', description: 'Python-specific review' },
+    { name: 'golang-reviewer', description: 'Go-specific review' },
+    { name: 'rust-reviewer', description: 'Rust-specific review' },
+    { name: 'java-reviewer', description: 'Java-specific review' },
+    { name: 'cpp-reviewer', description: 'C/C++-specific review' },
+    { name: 'backend-patterns', description: 'Backend service patterns' },
+    { name: 'frontend-patterns', description: 'Frontend patterns' },
+    { name: 'database-migrations', description: 'DB migration safety' },
+    { name: 'deployment-patterns', description: 'Deployment / CI-CD patterns' },
+];
+const ECC_DETECT_TIMEOUT_MS = 5000;
+const ECC_RUN_TIMEOUT_MS = 60000;
+const defaultSubprocessRunner = {
+    run(command, args, timeoutMs) {
+        try {
+            const r = spawnSync(command, args, {
+                timeout: timeoutMs,
+                encoding: 'utf8',
+                stdio: ['ignore', 'pipe', 'pipe'],
+                maxBuffer: 16 * 1024 * 1024,
+            });
+            return {
+                status: r.status,
+                stdout: r.stdout ?? '',
+                stderr: r.stderr ?? '',
+            };
+        }
+        catch (err) {
+            return {
+                status: null,
+                stdout: '',
+                stderr: '',
+                error: err,
+            };
+        }
+    },
+};
+function isEccInstalled(runner) {
+    const result = runner.run('npx', ['ecc', '--version'], ECC_DETECT_TIMEOUT_MS);
+    if (result.error)
+        return false;
+    return result.status === 0;
+}
+/**
+ * Validate the agent name against the canonical ECC catalog.
+ * Returns `null` if the agent is known; an error message otherwise.
+ */
+export function validateEccAgent(agent) {
+    if (typeof agent !== 'string' || agent.length === 0) {
+        return 'peaks agent run: agent name must be a non-empty string';
+    }
+    if (!/^[a-z][a-z0-9-]*$/.test(agent)) {
+        return `peaks agent run: agent name "${agent}" is invalid (must match [a-z][a-z0-9-]*)`;
+    }
+    return null;
+}
+export function runEccAgent(input, runner = defaultSubprocessRunner) {
+    const enableAgent = input.enableAgent === true;
+    const warnings = [];
+    let result = null;
+    // Resolve the effective "should spawn" decision.
+    // flagEnabled (CLI override) > preference (always-on for now; L3+ future) > false
+    const shouldSpawn = enableAgent;
+    const installed = isEccInstalled(runner);
+    let reason;
+    let spawned;
+    if (!shouldSpawn) {
+        reason = 'flag-disabled';
+        spawned = false;
+    }
+    else if (!installed) {
+        reason = 'flag-enabled-but-ecc-missing';
+        spawned = false;
+        warnings.push('`npx ecc --version` failed. Run `npx ecc --help` to install ECC, ' +
+            'then re-run `peaks agent run`. The peaks-loop native diagnostic ' +
+            'still runs via `peaks doctor scan`.');
+    }
+    else {
+        reason = 'enabled-and-installed';
+        spawned = true;
+        const start = Date.now();
+        const subResult = runner.run('npx', ['ecc', 'agent', 'run', input.agent, '--target', input.projectRoot, '--json'], ECC_RUN_TIMEOUT_MS);
+        let parsed;
+        let error;
+        if (subResult.error) {
+            error = subResult.error.message;
+        }
+        else if (subResult.status !== 0) {
+            error = `ecc agent run exited with status ${subResult.status}: ${subResult.stderr}`;
+        }
+        else {
+            try {
+                parsed = JSON.parse(subResult.stdout);
+            }
+            catch {
+                // Non-JSON output is allowed; peaks-loop surfaces the raw
+                // stdout for the human reader and treats the run as
+                // ok=true (the subprocess exited 0).
+                parsed = undefined;
+            }
+        }
+        result = {
+            agent: input.agent,
+            ok: error === undefined,
+            stdout: subResult.stdout,
+            stderr: subResult.stderr,
+            durationMs: Date.now() - start,
+            ...(parsed !== undefined ? { parsed } : {}),
+            ...(error !== undefined ? { error } : {}),
+        };
+    }
+    return { agent: input.agent, spawned, reason, result, warnings };
+}

package/dist/services/artifacts/artifact-lint-service.d.ts

@@ -0,0 +1,23 @@
+import { type RequestArtifactRole } from './request-artifact-service.js';
+export type ArtifactLintSeverity = 'error' | 'warning';
+export type ArtifactLintFinding = {
+    line: number;
+    text: string;
+    reason: string;
+    severity: ArtifactLintSeverity;
+};
+export type ArtifactLintReport = {
+    ok: boolean;
+    role: RequestArtifactRole;
+    requestId: string;
+    path: string;
+    totalLines: number;
+    findings: ArtifactLintFinding[];
+};
+export type LintArtifactOptions = {
+    projectRoot: string;
+    role: RequestArtifactRole;
+    requestId: string;
+    sessionId?: string;
+};
+export declare function lintRequestArtifact(options: LintArtifactOptions): Promise<ArtifactLintReport | null>;

package/dist/services/artifacts/artifact-lint-service.js

@@ -0,0 +1,99 @@
+import { showRequestArtifact } from './request-artifact-service.js';
+const RULES = [
+    {
+        test: (line) => /<[A-Za-z][^>]*>/.test(line.trim()) && !/^\s*-?\s*linked-/i.test(line),
+        reason: 'Contains an unfilled <placeholder> token',
+        severity: 'error'
+    },
+    {
+        test: (line) => /^\s*-\s*\.\.\.\s*$/.test(line),
+        reason: 'Bullet point is only "..." — replace with real content',
+        severity: 'error'
+    },
+    {
+        test: (line) => /\bTBD\b|\bTODO\b|\bFIXME\b|\bXXX\b/.test(line),
+        reason: 'Contains TBD/TODO/FIXME/XXX marker',
+        severity: 'warning'
+    },
+    {
+        test: (line) => /^\s*-\s*$/.test(line),
+        reason: 'Empty bullet point — replace with real content or remove',
+        severity: 'warning'
+    }
+];
+// Lines that should never be flagged even if they match a rule (template scaffolding).
+const ALLOWLIST_PATTERNS = [
+    /^#+\s/, // markdown headers
+    /^\s*```/, // code fences
+    /^\s*-\s*last update:/i, // metadata
+    /^\s*-\s*created:/i,
+    /^\s*-\s*state:/i,
+    /^\s*-\s*type:\s*(feature|bugfix|refactor|docs|config|chore)\s*$/i,
+    /^\s*-\s*session:\s*[a-z0-9-]+/i,
+    /^\s*-\s*transition note/i // bypass / repair notes are not placeholders
+];
+function isAllowlisted(line) {
+    return ALLOWLIST_PATTERNS.some((pattern) => pattern.test(line));
+}
+/**
+ * Remove inline code spans (`...`) before applying placeholder rules. Content
+ * inside backticks is literal example text — e.g. a documented command syntax
+ * `peaks sop init <id>` — not an unfilled prose placeholder. Lint checks prose,
+ * not code, so a `<...>` token only counts when it appears outside code spans.
+ */
+function stripInlineCode(line) {
+    return line.replace(/`[^`]*`/g, '');
+}
+export async function lintRequestArtifact(options) {
+    const showOptions = {
+        projectRoot: options.projectRoot,
+        role: options.role,
+        requestId: options.requestId
+    };
+    if (options.sessionId !== undefined) {
+        showOptions.sessionId = options.sessionId;
+    }
+    const artifact = await showRequestArtifact(showOptions);
+    if (artifact === null) {
+        return null;
+    }
+    const lines = artifact.content.split(/\r?\n/);
+    const findings = [];
+    let insideFence = false;
+    for (let index = 0; index < lines.length; index += 1) {
+        const rawLine = lines[index];
+        if (rawLine === undefined)
+            continue;
+        // Fenced code blocks hold literal examples, not prose to fill; skip their
+        // contents entirely (the fence delimiters themselves toggle the state).
+        if (/^\s*```/.test(rawLine)) {
+            insideFence = !insideFence;
+            continue;
+        }
+        if (insideFence)
+            continue;
+        if (isAllowlisted(rawLine))
+            continue;
+        const testLine = stripInlineCode(rawLine);
+        for (const rule of RULES) {
+            if (rule.test(testLine)) {
+                findings.push({
+                    line: index + 1,
+                    text: rawLine.trim(),
+                    reason: rule.reason,
+                    severity: rule.severity
+                });
+                break;
+            }
+        }
+    }
+    const hasError = findings.some((finding) => finding.severity === 'error');
+    return {
+        ok: !hasError,
+        role: options.role,
+        requestId: options.requestId,
+        path: artifact.path,
+        totalLines: lines.length,
+        findings
+    };
+}

package/dist/services/artifacts/artifact-prerequisites.d.ts

@@ -0,0 +1,78 @@
+import type { RequestArtifactRole, RequestArtifactState } from './request-artifact-service.js';
+export type RequestType = 'feature' | 'bugfix' | 'refactor' | 'docs' | 'config' | 'chore';
+export declare const VALID_REQUEST_TYPES: ReadonlyArray<RequestType>;
+export declare const DEFAULT_REQUEST_TYPE: RequestType;
+export declare function isRequestType(value: string): value is RequestType;
+export type ArtifactPrerequisite = {
+    /** Relative path under `.peaks/_runtime/<session-id>/`. May contain `<rid>` placeholder. */
+    relativePath: string;
+    /** Human-readable description of what this artifact represents. */
+    description: string;
+    /** Optional content markers — when set, the file must contain ALL of these (case-insensitive substring). */
+    mustContain?: ReadonlyArray<string>;
+    /**
+     * Optional content markers — when set, the file must contain AT LEAST ONE of
+     * these (case-insensitive substring). Use this for escape-hatch patterns
+     * (e.g. perf-baseline's "Results table" OR "N/A — no perf surface" stub).
+     * `mustContain` and `mustContainAny` are independent: when both are set,
+     * `mustContain` markers must all be present AND at least one `mustContainAny`
+     * marker must be present.
+     */
+    mustContainAny?: ReadonlyArray<string>;
+    /**
+     * Slice 2.6.1.F: structural heading markers — when set, the file must
+     * contain ALL of these as markdown headings (line beginning with `#`–`###`
+     * followed by the marker, case-insensitive). This prevents a file from
+     * passing the gate by simply mentioning the marker as prose. Use this for
+     * section-anchored gates like the karpathy 4-guideline review.
+     * Independent of `mustContain` / `mustContainAny`.
+     */
+    headingMustContain?: ReadonlyArray<string>;
+    /**
+     * Slice v2.12.0 Group B Tier 5: optional legacy path that satisfies
+     * the same gate. When `relativePath` does not resolve on disk, the
+     * resolver tries this fallback path before reporting the prereq as
+     * missing. Use this for 1-minor-release back-compat windows where
+     * an old artifact location is still accepted alongside the new one.
+     * v2.13.0 should remove all `legacyRelativePath` entries.
+     *
+     * Body checks (`mustContain` / `mustContainAny` /
+     * `headingMustContain`) apply to whichever path resolved — the
+     * gate does not distinguish which path served the file.
+     */
+    legacyRelativePath?: string;
+};
+export type PrerequisiteCheckResult = {
+    ok: boolean;
+    missing: Array<{
+        path: string;
+        description: string;
+    }>;
+    /**
+     * v2.13.2 AC-5 — soft-block warnings. Each entry is a prereq
+     * path that is currently missing but is in a 1-minor-release
+     * back-compat window. The transition gate does not throw on
+     * `missing`-only (so legacy callers keep working) but surfaces the
+     * warning to the operator so they can plan the v2.14.0 hard cut.
+     */
+    warnings: Array<{
+        path: string;
+        code: string;
+        message: string;
+    }>;
+};
+export type CheckPrerequisitesOptions = {
+    projectRoot: string;
+    /**
+     * Durable scope of the artifact (the `.peaks/_runtime/<sessionId>/` directory
+     * the file lives in). The gate scans under `.peaks/_runtime/<sessionId>/<role>/`
+     * for prerequisite artifacts.
+     */
+    sessionId: string;
+    role: RequestArtifactRole;
+    newState: RequestArtifactState;
+    requestId: string;
+    requestType?: RequestType;
+};
+export declare function getPrerequisitesFor(role: RequestArtifactRole, newState: RequestArtifactState, requestType?: RequestType): ReadonlyArray<ArtifactPrerequisite>;
+export declare function checkPrerequisites(options: CheckPrerequisitesOptions): Promise<PrerequisiteCheckResult>;