peaks-loop 4.0.0-beta.9 → 4.0.1

package/dist/services/migrate-skill-name/schema.d.ts

@@ -23,16 +23,16 @@ export declare const MigrateResultSchema: z.ZodObject<{
     skipped: z.ZodArray<z.ZodString, "many">;
     errors: z.ZodArray<z.ZodString, "many">;
 }, "strip", z.ZodTypeAny, {
-    ok: boolean;
     skipped: string[];
+    ok: boolean;
     scannedFiles: number;
     modifiedFiles: number;
     keyValueReplacements: number;
     stringReplacements: number;
     errors: string[];
 }, {
-    ok: boolean;
     skipped: string[];
+    ok: boolean;
     scannedFiles: number;
     modifiedFiles: number;
     keyValueReplacements: number;

package/dist/services/observability/aggregation.d.ts

@@ -62,3 +62,30 @@ export declare function periodStartIso(period: Period, now?: () => Date): string
 export declare function filterByPeriod(events: readonly ObservabilityEvent[], period: Period, now?: () => Date): ObservabilityEvent[];
 export declare function readAllSessionEvents(projectRoot: string): ObservabilityEvent[];
 export declare function readSessionEvents(projectRoot: string, sessionId: string): ObservabilityEvent[];
+/**
+ * Cumulative 5-metric surface for the `peaks dashboard summary` CLI.
+ * All values are derived from raw observability events (per-event
+ * counting), not from state files — semantics differ from
+ * `peaks dashboard long-run`, which derives indicators from
+ * `.peaks/_runtime/<sid>/24h-state.json`.
+ */
+export type DashboardMetrics = {
+    readonly cycleCount: number;
+    readonly tokenCount: number;
+    readonly dispatchCount: number;
+    readonly compactCount: number;
+    readonly monotonicTriggerCount: number;
+};
+/**
+ * Aggregate the 5 dashboard metric classes for a single session, filtered
+ * to events with `ts >= since`. Events with unparseable timestamps are
+ * counted (best-effort, mirrors `readObservabilityEvents` behavior). The
+ * `token-usage` total is summed from `detail.totalTokens` (falling back to
+ * `inputTokens + outputTokens` when the aggregate field is missing).
+ */
+export declare function aggregateDashboardMetrics(projectRoot: string, sessionId: string, since: Date): DashboardMetrics;
+/**
+ * Pure-function variant used by tests: counts across an already-loaded
+ * event list. `since` may be null to count everything.
+ */
+export declare function aggregateDashboardMetricsFromEvents(events: readonly ObservabilityEvent[], since?: Date | null): DashboardMetrics;

package/dist/services/observability/aggregation.js

@@ -215,3 +215,75 @@ export function readAllSessionEvents(projectRoot) {
 export function readSessionEvents(projectRoot, sessionId) {
     return readObservabilityEvents(projectRoot, sessionId);
 }
+/**
+ * Aggregate the 5 dashboard metric classes for a single session, filtered
+ * to events with `ts >= since`. Events with unparseable timestamps are
+ * counted (best-effort, mirrors `readObservabilityEvents` behavior). The
+ * `token-usage` total is summed from `detail.totalTokens` (falling back to
+ * `inputTokens + outputTokens` when the aggregate field is missing).
+ */
+export function aggregateDashboardMetrics(projectRoot, sessionId, since) {
+    const events = readObservabilityEvents(projectRoot, sessionId);
+    const cutoff = since.getTime();
+    let cycleCount = 0;
+    let tokenCount = 0;
+    let dispatchCount = 0;
+    let compactCount = 0;
+    let monotonicTriggerCount = 0;
+    for (const event of events) {
+        const ts = Date.parse(event.ts);
+        if (Number.isFinite(cutoff) && Number.isFinite(ts) && ts < cutoff)
+            continue;
+        if (event.category === 'cycle')
+            cycleCount += 1;
+        else if (event.category === 'token-usage') {
+            const detail = event.detail;
+            const t = typeof detail.totalTokens === 'number'
+                ? detail.totalTokens
+                : (typeof detail.inputTokens === 'number' ? detail.inputTokens : 0)
+                    + (typeof detail.outputTokens === 'number' ? detail.outputTokens : 0);
+            tokenCount += t;
+        }
+        else if (event.category === 'dispatch')
+            dispatchCount += 1;
+        else if (event.category === 'post-compact')
+            compactCount += 1;
+        else if (event.category === 'monotonic-trigger')
+            monotonicTriggerCount += 1;
+    }
+    return { cycleCount, tokenCount, dispatchCount, compactCount, monotonicTriggerCount };
+}
+/**
+ * Pure-function variant used by tests: counts across an already-loaded
+ * event list. `since` may be null to count everything.
+ */
+export function aggregateDashboardMetricsFromEvents(events, since = null) {
+    const cutoff = since?.getTime() ?? null;
+    let cycleCount = 0;
+    let tokenCount = 0;
+    let dispatchCount = 0;
+    let compactCount = 0;
+    let monotonicTriggerCount = 0;
+    for (const event of events) {
+        const ts = Date.parse(event.ts);
+        if (cutoff !== null && Number.isFinite(ts) && ts < cutoff)
+            continue;
+        if (event.category === 'cycle')
+            cycleCount += 1;
+        else if (event.category === 'token-usage') {
+            const detail = event.detail;
+            const t = typeof detail.totalTokens === 'number'
+                ? detail.totalTokens
+                : (typeof detail.inputTokens === 'number' ? detail.inputTokens : 0)
+                    + (typeof detail.outputTokens === 'number' ? detail.outputTokens : 0);
+            tokenCount += t;
+        }
+        else if (event.category === 'dispatch')
+            dispatchCount += 1;
+        else if (event.category === 'post-compact')
+            compactCount += 1;
+        else if (event.category === 'monotonic-trigger')
+            monotonicTriggerCount += 1;
+    }
+    return { cycleCount, tokenCount, dispatchCount, compactCount, monotonicTriggerCount };
+}

package/dist/services/observability/observability-service.d.ts

@@ -20,7 +20,7 @@
  */
 import { z } from 'zod';
 export declare const OBSERVABILITY_SCHEMA_VERSION: 1;
-export declare const OBSERVABILITY_CATEGORIES: readonly ["slice-transition", "dispatch", "checkpoint", "mode-gate", "context-trigger", "post-compact"];
+export declare const OBSERVABILITY_CATEGORIES: readonly ["slice-transition", "dispatch", "checkpoint", "mode-gate", "context-trigger", "post-compact", "cycle", "token-usage", "monotonic-trigger", "lease"];
 export type ObservabilityCategory = typeof OBSERVABILITY_CATEGORIES[number];
 export declare const OBSERVABILITY_SUBAGENT_ROLES: readonly ["rd", "qa", "code-reviewer", "karpathy-reviewer", "peaks-security-audit", "peaks-perf-audit"];
 export type ObservabilitySubagentRole = typeof OBSERVABILITY_SUBAGENT_ROLES[number];
@@ -28,24 +28,24 @@ export declare const ObservabilityEventSchema: z.ZodObject<{
     schemaVersion: z.ZodLiteral<1>;
     ts: z.ZodString;
     sessionId: z.ZodString;
-    category: z.ZodEnum<["slice-transition", "dispatch", "checkpoint", "mode-gate", "context-trigger", "post-compact"]>;
+    category: z.ZodEnum<["slice-transition", "dispatch", "checkpoint", "mode-gate", "context-trigger", "post-compact", "cycle", "token-usage", "monotonic-trigger", "lease"]>;
     sliceRid: z.ZodOptional<z.ZodString>;
     role: z.ZodOptional<z.ZodEnum<["rd", "qa", "code-reviewer", "karpathy-reviewer", "peaks-security-audit", "peaks-perf-audit"]>>;
     detail: z.ZodRecord<z.ZodString, z.ZodUnknown>;
 }, "strip", z.ZodTypeAny, {
     sessionId: string;
+    detail: Record<string, unknown>;
     schemaVersion: 1;
     ts: string;
-    category: "slice-transition" | "dispatch" | "checkpoint" | "mode-gate" | "context-trigger" | "post-compact";
-    detail: Record<string, unknown>;
+    category: "slice-transition" | "dispatch" | "checkpoint" | "mode-gate" | "context-trigger" | "post-compact" | "cycle" | "token-usage" | "monotonic-trigger" | "lease";
     role?: "qa" | "rd" | "code-reviewer" | "karpathy-reviewer" | "peaks-security-audit" | "peaks-perf-audit" | undefined;
     sliceRid?: string | undefined;
 }, {
     sessionId: string;
+    detail: Record<string, unknown>;
     schemaVersion: 1;
     ts: string;
-    category: "slice-transition" | "dispatch" | "checkpoint" | "mode-gate" | "context-trigger" | "post-compact";
-    detail: Record<string, unknown>;
+    category: "slice-transition" | "dispatch" | "checkpoint" | "mode-gate" | "context-trigger" | "post-compact" | "cycle" | "token-usage" | "monotonic-trigger" | "lease";
     role?: "qa" | "rd" | "code-reviewer" | "karpathy-reviewer" | "peaks-security-audit" | "peaks-perf-audit" | undefined;
     sliceRid?: string | undefined;
 }>;
@@ -90,6 +90,72 @@ export declare function readObservabilityEvents(projectRoot: string, sessionId:
 export declare function isCurrentSchemaVersion(record: unknown): record is ObservabilityEvent;
 export declare const OBSERVABILITY_CONSTANTS: {
     readonly SCHEMA_VERSION: 1;
-    readonly CATEGORIES: readonly ["slice-transition", "dispatch", "checkpoint", "mode-gate", "context-trigger", "post-compact"];
+    readonly CATEGORIES: readonly ["slice-transition", "dispatch", "checkpoint", "mode-gate", "context-trigger", "post-compact", "cycle", "token-usage", "monotonic-trigger", "lease"];
     readonly SUBAGENT_ROLES: readonly ["rd", "qa", "code-reviewer", "karpathy-reviewer", "peaks-security-audit", "peaks-perf-audit"];
 };
+/**
+ * Slice 2026-07-29-worktree-l2-extended Part 4.A: lease lifecycle
+ * observability. Each `peaks worktree spawn / renew / release /
+ * gc` CLI emits a `lease` event; the auto-release hook in
+ * dispatch finalization emits `autoRelease` (success) or
+ * `autoRelease-failed` (detached spawn failed). The
+ * `peaks lease metrics --json` reader aggregates these for the
+ * dashboard.
+ *
+ * Fire-and-forget by contract (mirrors emitCycleEvent /
+ * emitTokenUsageEvent): never throws, written=false on schema
+ * mismatch or IO failure. Callers do not inspect the result.
+ */
+export type LeaseEventKind = 'spawn' | 'renew' | 'release' | 'gc' | 'autoRelease' | 'autoRelease-failed' | 'autoRelease-skipped';
+export declare function emitLeaseEvent(opts: {
+    sessionId: string;
+    projectRoot: string;
+    kind: LeaseEventKind;
+    leaseId: string;
+    rid?: string;
+    role?: string;
+    /** Reason the autoRelease was skipped (e.g. "no-lease", "non-terminal-status"). */
+    reason?: string;
+}): EmitResult;
+/**
+ * rid-030 F-direction: per-cycle event (cycle started / completed / failed).
+ * Fire-and-forget; never throws. Tagging `kind` for downstream dashboards.
+ */
+export declare function emitCycleEvent(opts: {
+    sessionId: string;
+    projectRoot: string;
+    cycle: number;
+    status: 'started' | 'completed' | 'failed';
+}): EmitResult;
+/**
+ * rid-030 F-direction: per-token-usage event. `totalTokens` is the
+ * sum the dashboard cares about; `inputTokens`/`outputTokens` are kept
+ * for downstream drill-down.
+ */
+export declare function emitTokenUsageEvent(opts: {
+    sessionId: string;
+    projectRoot: string;
+    inputTokens: number;
+    outputTokens: number;
+}): EmitResult;
+/**
+ * rid-030 F-direction: per-monotonic-trigger event.
+ */
+export declare function emitMonotonicTriggerEvent(opts: {
+    sessionId: string;
+    projectRoot: string;
+    report: 'pass' | 'warn' | 'block';
+    action: string;
+}): EmitResult;
+/**
+ * rid-030 F-direction: per-subagent-dispatch event. Reuses the
+ * existing `dispatch` category (rd/qa/reviewer/audit). Provides a
+ * canonical emit helper so dashboards don't have to hand-author the
+ * `ObservabilityEvent` envelope.
+ */
+export declare function emitDispatchEvent(opts: {
+    sessionId: string;
+    projectRoot: string;
+    role: ObservabilitySubagentRole;
+    status?: 'queued' | 'running' | 'done' | 'failed';
+}): EmitResult;

package/dist/services/observability/observability-service.js

@@ -27,7 +27,17 @@ export const OBSERVABILITY_CATEGORIES = [
     'checkpoint',
     'mode-gate',
     'context-trigger',
-    'post-compact'
+    'post-compact',
+    'cycle',
+    'token-usage',
+    'monotonic-trigger',
+    // Slice 2026-07-29-worktree-l2-extended Part 4.A: lease lifecycle
+    // metrics. Emitted by `peaks worktree spawn / renew / release /
+    // gc` and by the auto-release hook in dispatch finalization (Part
+    // 3.A). Read by `peaks lease metrics`. The `detail.kind` field
+    // discriminates spawn / renew / release / gc / autoRelease /
+    // autoRelease-failed / autoRelease-skipped.
+    'lease'
 ];
 // v2.12.0 fan-out collapse: `security-reviewer` (in-process RD slot)
 // moved out to the standalone `peaks-security-audit` skill; the matching
@@ -117,3 +127,79 @@ export const OBSERVABILITY_CONSTANTS = {
     CATEGORIES: OBSERVABILITY_CATEGORIES,
     SUBAGENT_ROLES: OBSERVABILITY_SUBAGENT_ROLES
 };
+export function emitLeaseEvent(opts) {
+    const detail = { kind: opts.kind, leaseId: opts.leaseId };
+    if (opts.rid !== undefined)
+        detail['rid'] = opts.rid;
+    if (opts.role !== undefined)
+        detail['role'] = opts.role;
+    if (opts.reason !== undefined)
+        detail['reason'] = opts.reason;
+    return emitObservabilityEvent({
+        schemaVersion: OBSERVABILITY_SCHEMA_VERSION,
+        ts: new Date().toISOString(),
+        sessionId: opts.sessionId,
+        category: 'lease',
+        detail
+    }, { projectRoot: opts.projectRoot });
+}
+/**
+ * rid-030 F-direction: per-cycle event (cycle started / completed / failed).
+ * Fire-and-forget; never throws. Tagging `kind` for downstream dashboards.
+ */
+export function emitCycleEvent(opts) {
+    return emitObservabilityEvent({
+        schemaVersion: OBSERVABILITY_SCHEMA_VERSION,
+        ts: new Date().toISOString(),
+        sessionId: opts.sessionId,
+        category: 'cycle',
+        detail: { cycle: opts.cycle, status: opts.status }
+    }, { projectRoot: opts.projectRoot });
+}
+/**
+ * rid-030 F-direction: per-token-usage event. `totalTokens` is the
+ * sum the dashboard cares about; `inputTokens`/`outputTokens` are kept
+ * for downstream drill-down.
+ */
+export function emitTokenUsageEvent(opts) {
+    const totalTokens = Math.max(0, opts.inputTokens) + Math.max(0, opts.outputTokens);
+    return emitObservabilityEvent({
+        schemaVersion: OBSERVABILITY_SCHEMA_VERSION,
+        ts: new Date().toISOString(),
+        sessionId: opts.sessionId,
+        category: 'token-usage',
+        detail: {
+            inputTokens: opts.inputTokens,
+            outputTokens: opts.outputTokens,
+            totalTokens
+        }
+    }, { projectRoot: opts.projectRoot });
+}
+/**
+ * rid-030 F-direction: per-monotonic-trigger event.
+ */
+export function emitMonotonicTriggerEvent(opts) {
+    return emitObservabilityEvent({
+        schemaVersion: OBSERVABILITY_SCHEMA_VERSION,
+        ts: new Date().toISOString(),
+        sessionId: opts.sessionId,
+        category: 'monotonic-trigger',
+        detail: { report: opts.report, action: opts.action }
+    }, { projectRoot: opts.projectRoot });
+}
+/**
+ * rid-030 F-direction: per-subagent-dispatch event. Reuses the
+ * existing `dispatch` category (rd/qa/reviewer/audit). Provides a
+ * canonical emit helper so dashboards don't have to hand-author the
+ * `ObservabilityEvent` envelope.
+ */
+export function emitDispatchEvent(opts) {
+    return emitObservabilityEvent({
+        schemaVersion: OBSERVABILITY_SCHEMA_VERSION,
+        ts: new Date().toISOString(),
+        sessionId: opts.sessionId,
+        category: 'dispatch',
+        role: opts.role,
+        detail: { status: opts.status ?? 'done' }
+    }, { projectRoot: opts.projectRoot });
+}

package/dist/services/openspec/artifact-boundary.d.ts

@@ -0,0 +1,138 @@
+/**
+ * Artifact boundary helpers for peaks-loop.
+ *
+ * Slice rid-009:
+ *   - sub-slice 1: change-id validation (`validateChangeId`).
+ *   - sub-slice 2: artifact path planning (`planArtifactPath` + `isPathInsideArtifactRoot` re-export).
+ *   - sub-slice 3: workspace-unavailable response (`buildWorkspaceUnavailable`).
+ *
+ * The colocated single-file layout avoids creating two competing path-safety
+ * layers — `src/shared/path-safety.ts` already owns the primitive
+ * `isPathInsideArtifactRoot` which we re-export unchanged.
+ *
+ * Conventions:
+ *   - `Result<T, E>` is hand-rolled in this file (no `neverthrow` dep).
+ *   - All errors are typed unions — no thrown exceptions for validation.
+ *   - The change-id format mirrors the pre-existing
+ *     `[A-Za-z0-9][A-Za-z0-9._-]*` regex used by
+ *     `openspec-validate-service.ts` so the refactor (task 3) preserves
+ *     the exact error message byte-for-byte.
+ *   - Path planning uses `posix.normalize` to keep semantics stable across
+ *     win32/posix runners; JSON output always uses `/`.
+ */
+import { isPathInsideArtifactRoot as _isPathInsideArtifactRoot } from '../../shared/path-safety.js';
+export type Result<T, E> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: E;
+};
+export declare function ok<T>(value: T): Result<T, never>;
+export declare function err<E>(error: E): Result<never, E>;
+export declare function isOk<T, E>(result: Result<T, E>): result is {
+    ok: true;
+    value: T;
+};
+export type ChangeIdError = {
+    code: 'change-id-empty';
+    message: string;
+} | {
+    code: 'change-id-format';
+    message: string;
+} | {
+    code: 'change-id-reserved';
+    message: string;
+};
+export type BoundaryError = ChangeIdError | {
+    code: 'workspace-unconfigured';
+    message: string;
+} | {
+    code: 'path-outside-artifact-root';
+    path: string;
+    root: string;
+    message: string;
+} | {
+    code: 'unsafe-path-input';
+    message: string;
+};
+/**
+ * Validate a change-id string. Returns a typed `Result`; the error code
+ * distinguishes "empty" / "format" / "reserved" so callers can branch on
+ * the cause without re-parsing the message.
+ *
+ * Acceptance contract (rid-009 §3.3.1, task 1):
+ *   - accepts `[A-Za-z0-9][A-Za-z0-9._-]*` (existing regex semantics)
+ *   - rejects empty string with `change-id-empty`
+ *   - rejects `.` and `..` with `change-id-reserved`
+ *   - rejects everything else that does not match the regex with
+ *     `change-id-format`
+ *
+ * The format-error message is byte-for-byte identical to the pre-refactor
+ * string produced at `openspec-validate-service.ts:55` so existing
+ * `OpenSpecValidationIssue` consumers do not break.
+ */
+export declare function validateChangeId(id: string): Result<{
+    changeId: string;
+}, ChangeIdError>;
+/**
+ * Re-export of `src/shared/path-safety.ts#isPathInsideArtifactRoot`.
+ *
+ * Single source of truth: the primitive is owned by `src/shared/path-safety.ts`;
+ * this module owns the *domain* helpers (change-id + path planner) that consume
+ * the primitive. Tests in `tests/unit/services/openspec/artifact-boundary.test.ts`
+ * exercise the RE-EXPORT wiring; the primitive's own correctness is covered by
+ * its native test file.
+ */
+export { _isPathInsideArtifactRoot as isPathInsideArtifactRoot };
+/**
+ * Input for `planArtifactPath`. The caller MUST supply `changeId`, `workspaceRoot`,
+ * `role`, and `requestId`. Exactly one of `absolutePath` or `relativePath` may be
+ * supplied; if neither is supplied, a default template `"<changeId>/<role>/<requestId>"`
+ * is used. `template` overrides the default placeholder substitution when both
+ * `absolutePath` and `relativePath` are absent.
+ */
+export type PlanArtifactPathInput = {
+    changeId: string;
+    workspaceRoot: string;
+    role: string;
+    requestId: string;
+    absolutePath?: string;
+    relativePath?: string;
+    template?: string;
+};
+export type PlanArtifactPathOutput = {
+    absolutePath: string;
+    relativePath: string;
+    jsonSafeRelativePath: string;
+};
+/**
+ * Plan an artifact-relative path under the configured Peaks artifact workspace.
+ *
+ * Semantics (rid-009 §3.3.2, tasks 5–9):
+ *   - Backslashes in the candidate path are normalized to forward slashes for
+ *     JSON safety; empty segments (`foo//bar`) are collapsed by `posix.normalize`.
+ *   - If the resolved absolute path is NOT contained under `workspaceRoot`
+ *     (per `isPathInsideArtifactRoot`), returns
+ *     `BoundaryError.path-outside-artifact-root` — NO silent fallback to cwd.
+ *   - JSON output (`jsonSafeRelativePath`) ALWAYS uses `/` so it round-trips
+ *     cleanly through `JSON.stringify` on Windows.
+ *
+ * Path math only — this helper never touches the filesystem, so it is fully
+ * hermetic and safe to call on paths that do not exist yet.
+ */
+export declare function planArtifactPath(input: PlanArtifactPathInput): Result<PlanArtifactPathOutput, BoundaryError>;
+export type WorkspaceUnavailableResponse = {
+    ok: false;
+    mode: 'preview-only' | 'blocked';
+    reason: 'artifact-workspace-unavailable';
+    nextActions: string[];
+};
+/**
+ * Build the explicit response used when no artifact workspace is configured.
+ * The next action is static natural language so callers can surface remediation
+ * without requiring the user to type a CLI command or hand-author data.
+ */
+export declare function buildWorkspaceUnavailable(input: {
+    mode: WorkspaceUnavailableResponse['mode'];
+}): WorkspaceUnavailableResponse;

package/dist/services/openspec/artifact-boundary.js

@@ -0,0 +1,150 @@
+/**
+ * Artifact boundary helpers for peaks-loop.
+ *
+ * Slice rid-009:
+ *   - sub-slice 1: change-id validation (`validateChangeId`).
+ *   - sub-slice 2: artifact path planning (`planArtifactPath` + `isPathInsideArtifactRoot` re-export).
+ *   - sub-slice 3: workspace-unavailable response (`buildWorkspaceUnavailable`).
+ *
+ * The colocated single-file layout avoids creating two competing path-safety
+ * layers — `src/shared/path-safety.ts` already owns the primitive
+ * `isPathInsideArtifactRoot` which we re-export unchanged.
+ *
+ * Conventions:
+ *   - `Result<T, E>` is hand-rolled in this file (no `neverthrow` dep).
+ *   - All errors are typed unions — no thrown exceptions for validation.
+ *   - The change-id format mirrors the pre-existing
+ *     `[A-Za-z0-9][A-Za-z0-9._-]*` regex used by
+ *     `openspec-validate-service.ts` so the refactor (task 3) preserves
+ *     the exact error message byte-for-byte.
+ *   - Path planning uses `posix.normalize` to keep semantics stable across
+ *     win32/posix runners; JSON output always uses `/`.
+ */
+import { posix, relative, resolve, isAbsolute as nodeIsAbsolute } from 'node:path';
+import { isPathInsideArtifactRoot as _isPathInsideArtifactRoot } from '../../shared/path-safety.js';
+export function ok(value) {
+    return { ok: true, value };
+}
+export function err(error) {
+    return { ok: false, error };
+}
+export function isOk(result) {
+    return result.ok;
+}
+const CHANGE_ID_FORMAT_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+/**
+ * Validate a change-id string. Returns a typed `Result`; the error code
+ * distinguishes "empty" / "format" / "reserved" so callers can branch on
+ * the cause without re-parsing the message.
+ *
+ * Acceptance contract (rid-009 §3.3.1, task 1):
+ *   - accepts `[A-Za-z0-9][A-Za-z0-9._-]*` (existing regex semantics)
+ *   - rejects empty string with `change-id-empty`
+ *   - rejects `.` and `..` with `change-id-reserved`
+ *   - rejects everything else that does not match the regex with
+ *     `change-id-format`
+ *
+ * The format-error message is byte-for-byte identical to the pre-refactor
+ * string produced at `openspec-validate-service.ts:55` so existing
+ * `OpenSpecValidationIssue` consumers do not break.
+ */
+export function validateChangeId(id) {
+    if (id === '') {
+        return err({ code: 'change-id-empty', message: 'changeId is empty' });
+    }
+    if (id === '.' || id === '..') {
+        return err({ code: 'change-id-reserved', message: `changeId ${id} is reserved` });
+    }
+    if (id.startsWith('.') || id.endsWith('.')) {
+        return err({
+            code: 'change-id-format',
+            message: `changeId ${id} does not match [A-Za-z0-9][A-Za-z0-9._-]*`
+        });
+    }
+    if (!CHANGE_ID_FORMAT_PATTERN.test(id)) {
+        return err({
+            code: 'change-id-format',
+            message: `changeId ${id} does not match [A-Za-z0-9][A-Za-z0-9._-]*`
+        });
+    }
+    return ok({ changeId: id });
+}
+/**
+ * Re-export of `src/shared/path-safety.ts#isPathInsideArtifactRoot`.
+ *
+ * Single source of truth: the primitive is owned by `src/shared/path-safety.ts`;
+ * this module owns the *domain* helpers (change-id + path planner) that consume
+ * the primitive. Tests in `tests/unit/services/openspec/artifact-boundary.test.ts`
+ * exercise the RE-EXPORT wiring; the primitive's own correctness is covered by
+ * its native test file.
+ */
+export { _isPathInsideArtifactRoot as isPathInsideArtifactRoot };
+const DEFAULT_TEMPLATE = '<changeId>/<role>/<requestId>';
+function interpolateTemplate(template, changeId, role, requestId) {
+    return template
+        .replaceAll('<changeId>', changeId)
+        .replaceAll('<role>', role)
+        .replaceAll('<requestId>', requestId);
+}
+/**
+ * Plan an artifact-relative path under the configured Peaks artifact workspace.
+ *
+ * Semantics (rid-009 §3.3.2, tasks 5–9):
+ *   - Backslashes in the candidate path are normalized to forward slashes for
+ *     JSON safety; empty segments (`foo//bar`) are collapsed by `posix.normalize`.
+ *   - If the resolved absolute path is NOT contained under `workspaceRoot`
+ *     (per `isPathInsideArtifactRoot`), returns
+ *     `BoundaryError.path-outside-artifact-root` — NO silent fallback to cwd.
+ *   - JSON output (`jsonSafeRelativePath`) ALWAYS uses `/` so it round-trips
+ *     cleanly through `JSON.stringify` on Windows.
+ *
+ * Path math only — this helper never touches the filesystem, so it is fully
+ * hermetic and safe to call on paths that do not exist yet.
+ */
+export function planArtifactPath(input) {
+    const workspaceRoot = input.workspaceRoot;
+    const candidateRaw = input.absolutePath !== undefined
+        ? input.absolutePath
+        : input.relativePath !== undefined
+            ? input.relativePath
+            : interpolateTemplate(input.template ?? DEFAULT_TEMPLATE, input.changeId, input.role, input.requestId);
+    // Always normalize separators to forward-slashes for the JSON-safe output,
+    // then run posix.normalize so empty segments (foo//bar) and `..` segments
+    // collapse to canonical form.
+    const forwardSlashed = candidateRaw.replace(/\\/g, '/');
+    const normalized = posix.normalize(forwardSlashed);
+    // Resolve against workspaceRoot. If the candidate is already absolute,
+    // posix.normalize preserves the leading `/`; `resolve` keeps it absolute
+    // without prepending workspaceRoot (Node's path.resolve treats absolute
+    // candidates as already-resolved).
+    const absolutePath = nodeIsAbsolute(normalized)
+        ? resolve(normalized)
+        : resolve(workspaceRoot, normalized);
+    if (!_isPathInsideArtifactRoot(absolutePath, workspaceRoot)) {
+        return err({
+            code: 'path-outside-artifact-root',
+            path: absolutePath,
+            root: workspaceRoot,
+            message: `path "${absolutePath}" resolves outside artifact root "${workspaceRoot}"`
+        });
+    }
+    const relativePath = relative(workspaceRoot, absolutePath);
+    const jsonSafeRelativePath = relativePath.replace(/\\/g, '/');
+    return ok({ absolutePath, relativePath, jsonSafeRelativePath });
+}
+const WORKSPACE_UNAVAILABLE_NEXT_ACTIONS = [
+    'Configure artifact workspace by describing where Peaks should store artifacts.'
+];
+/**
+ * Build the explicit response used when no artifact workspace is configured.
+ * The next action is static natural language so callers can surface remediation
+ * without requiring the user to type a CLI command or hand-author data.
+ */
+export function buildWorkspaceUnavailable(input) {
+    return {
+        ok: false,
+        mode: input.mode,
+        reason: 'artifact-workspace-unavailable',
+        nextActions: [...WORKSPACE_UNAVAILABLE_NEXT_ACTIONS]
+    };
+}